Marco Ferreira / BLE_API

just a fork

Fork of BLE_API by Bluetooth Low Energy

ble/GattClient.h@1155:e28c7aac64ab, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:14:34 2016 +0100
Revision:
1155:e28c7aac64ab
Parent:
1138:a9d4156efe16
Child:
1156:e1ea38b576c6
Synchronized with git rev e20c8c58

Author: Vincent Coubard

Merge pull request #163 from ARMmbed/develop



merge version 2.5.0 into master

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 1131:692ddf04fc42 1 /* mbed Microcontroller Library
vcoubard 1131:692ddf04fc42 2 * Copyright (c) 2006-2013 ARM Limited
vcoubard 1131:692ddf04fc42 3 *
vcoubard 1131:692ddf04fc42 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 1131:692ddf04fc42 5 * you may not use this file except in compliance with the License.
vcoubard 1131:692ddf04fc42 6 * You may obtain a copy of the License at
vcoubard 1131:692ddf04fc42 7 *
vcoubard 1131:692ddf04fc42 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 1131:692ddf04fc42 9 *
vcoubard 1131:692ddf04fc42 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 1131:692ddf04fc42 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 1131:692ddf04fc42 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 1131:692ddf04fc42 13 * See the License for the specific language governing permissions and
vcoubard 1131:692ddf04fc42 14 * limitations under the License.
vcoubard 1131:692ddf04fc42 15 */
vcoubard 1131:692ddf04fc42 16
vcoubard 1131:692ddf04fc42 17 #ifndef __GATT_CLIENT_H__
vcoubard 1131:692ddf04fc42 18 #define __GATT_CLIENT_H__
vcoubard 1131:692ddf04fc42 19
vcoubard 1131:692ddf04fc42 20 #include "Gap.h"
vcoubard 1131:692ddf04fc42 21 #include "GattAttribute.h"
vcoubard 1131:692ddf04fc42 22 #include "ServiceDiscovery.h"
vcoubard 1135:22aada733dbd 23 #include "CharacteristicDescriptorDiscovery.h"
vcoubard 1131:692ddf04fc42 24
vcoubard 1131:692ddf04fc42 25 #include "GattCallbackParamTypes.h"
vcoubard 1131:692ddf04fc42 26
vcoubard 1131:692ddf04fc42 27 #include "CallChainOfFunctionPointersWithContext.h"
vcoubard 1131:692ddf04fc42 28
vcoubard 1131:692ddf04fc42 29 class GattClient {
vcoubard 1131:692ddf04fc42 30 public:
vcoubard 1131:692ddf04fc42 31 typedef FunctionPointerWithContext<const GattReadCallbackParams*> ReadCallback_t;
vcoubard 1131:692ddf04fc42 32 typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams*> ReadCallbackChain_t;
vcoubard 1131:692ddf04fc42 33
vcoubard 1131:692ddf04fc42 34 enum WriteOp_t {
vcoubard 1131:692ddf04fc42 35 GATT_OP_WRITE_REQ = 0x01, /**< Write request. */
vcoubard 1131:692ddf04fc42 36 GATT_OP_WRITE_CMD = 0x02, /**< Write command. */
vcoubard 1131:692ddf04fc42 37 };
vcoubard 1131:692ddf04fc42 38
vcoubard 1131:692ddf04fc42 39 typedef FunctionPointerWithContext<const GattWriteCallbackParams*> WriteCallback_t;
vcoubard 1131:692ddf04fc42 40 typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> WriteCallbackChain_t;
vcoubard 1131:692ddf04fc42 41
vcoubard 1131:692ddf04fc42 42 typedef FunctionPointerWithContext<const GattHVXCallbackParams*> HVXCallback_t;
vcoubard 1131:692ddf04fc42 43 typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> HVXCallbackChain_t;
vcoubard 1131:692ddf04fc42 44
vcoubard 1135:22aada733dbd 45 typedef FunctionPointerWithContext<const GattClient *> GattClientShutdownCallback_t;
vcoubard 1135:22aada733dbd 46 typedef CallChainOfFunctionPointersWithContext<const GattClient *> GattClientShutdownCallbackChain_t;
vcoubard 1135:22aada733dbd 47
vcoubard 1131:692ddf04fc42 48 /*
vcoubard 1131:692ddf04fc42 49 * The following functions are meant to be overridden in the platform-specific sub-class.
vcoubard 1131:692ddf04fc42 50 */
vcoubard 1131:692ddf04fc42 51 public:
vcoubard 1131:692ddf04fc42 52 /**
vcoubard 1131:692ddf04fc42 53 * Launch service discovery. Once launched, application callbacks will be
vcoubard 1131:692ddf04fc42 54 * invoked for matching services or characteristics. isServiceDiscoveryActive()
vcoubard 1131:692ddf04fc42 55 * can be used to determine status, and a termination callback (if one was set up)
vcoubard 1131:692ddf04fc42 56 * will be invoked at the end. Service discovery can be terminated prematurely,
vcoubard 1131:692ddf04fc42 57 * if needed, using terminateServiceDiscovery().
vcoubard 1131:692ddf04fc42 58 *
vcoubard 1131:692ddf04fc42 59 * @param connectionHandle
vcoubard 1131:692ddf04fc42 60 * Handle for the connection with the peer.
vcoubard 1131:692ddf04fc42 61 * @param sc
vcoubard 1131:692ddf04fc42 62 * This is the application callback for a matching service. Taken as
vcoubard 1131:692ddf04fc42 63 * NULL by default. Note: service discovery may still be active
vcoubard 1131:692ddf04fc42 64 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1131:692ddf04fc42 65 * APIs from within this application callback might cause the
vcoubard 1131:692ddf04fc42 66 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1131:692ddf04fc42 67 * may be better to make a local copy of the discoveredService and
vcoubard 1131:692ddf04fc42 68 * wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 69 * service.
vcoubard 1131:692ddf04fc42 70 * @param cc
vcoubard 1131:692ddf04fc42 71 * This is the application callback for a matching characteristic.
vcoubard 1131:692ddf04fc42 72 * Taken as NULL by default. Note: service discovery may still be
vcoubard 1131:692ddf04fc42 73 * active when this callback is issued; calling asynchronous
vcoubard 1131:692ddf04fc42 74 * BLE-stack APIs from within this application callback might cause
vcoubard 1131:692ddf04fc42 75 * the stack to abort service discovery. If this becomes an issue,
vcoubard 1131:692ddf04fc42 76 * it may be better to make a local copy of the discoveredCharacteristic
vcoubard 1131:692ddf04fc42 77 * and wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 78 * characteristic.
vcoubard 1131:692ddf04fc42 79 * @param matchingServiceUUID
vcoubard 1131:692ddf04fc42 80 * UUID-based filter for specifying a service in which the application is
vcoubard 1131:692ddf04fc42 81 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 1131:692ddf04fc42 82 * in which case it matches all services. If characteristic-UUID
vcoubard 1131:692ddf04fc42 83 * filter (below) is set to the wildcard value, then a service
vcoubard 1131:692ddf04fc42 84 * callback will be invoked for the matching service (or for every
vcoubard 1131:692ddf04fc42 85 * service if the service filter is a wildcard).
vcoubard 1131:692ddf04fc42 86 * @param matchingCharacteristicUUIDIn
vcoubard 1131:692ddf04fc42 87 * UUID-based filter for specifying characteristic in which the application
vcoubard 1131:692ddf04fc42 88 * is interested. By default it is set as the wildcard UUID_UKNOWN
vcoubard 1131:692ddf04fc42 89 * to match against any characteristic. If both service-UUID
vcoubard 1131:692ddf04fc42 90 * filter and characteristic-UUID filter are used with non-wildcard
vcoubard 1131:692ddf04fc42 91 * values, then only a single characteristic callback is
vcoubard 1131:692ddf04fc42 92 * invoked for the matching characteristic.
vcoubard 1131:692ddf04fc42 93 *
vcoubard 1131:692ddf04fc42 94 * @note Using wildcard values for both service-UUID and characteristic-
vcoubard 1131:692ddf04fc42 95 * UUID will result in complete service discovery: callbacks being
vcoubard 1131:692ddf04fc42 96 * called for every service and characteristic.
vcoubard 1131:692ddf04fc42 97 *
vcoubard 1131:692ddf04fc42 98 * @note Providing NULL for the characteristic callback will result in
vcoubard 1131:692ddf04fc42 99 * characteristic discovery being skipped for each matching
vcoubard 1131:692ddf04fc42 100 * service. This allows for an inexpensive method to discover only
vcoubard 1131:692ddf04fc42 101 * services.
vcoubard 1131:692ddf04fc42 102 *
vcoubard 1131:692ddf04fc42 103 * @return
vcoubard 1131:692ddf04fc42 104 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
vcoubard 1131:692ddf04fc42 105 */
vcoubard 1131:692ddf04fc42 106 virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle,
vcoubard 1131:692ddf04fc42 107 ServiceDiscovery::ServiceCallback_t sc = NULL,
vcoubard 1131:692ddf04fc42 108 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
vcoubard 1131:692ddf04fc42 109 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
vcoubard 1131:692ddf04fc42 110 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
vcoubard 1131:692ddf04fc42 111 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 112 (void)connectionHandle;
vcoubard 1131:692ddf04fc42 113 (void)sc;
vcoubard 1131:692ddf04fc42 114 (void)cc;
vcoubard 1131:692ddf04fc42 115 (void)matchingServiceUUID;
vcoubard 1131:692ddf04fc42 116 (void)matchingCharacteristicUUIDIn;
vcoubard 1131:692ddf04fc42 117
vcoubard 1131:692ddf04fc42 118 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 119 }
vcoubard 1131:692ddf04fc42 120
vcoubard 1131:692ddf04fc42 121 /**
vcoubard 1131:692ddf04fc42 122 * Launch service discovery for services. Once launched, service discovery will remain
vcoubard 1131:692ddf04fc42 123 * active with service-callbacks being issued back into the application for matching
vcoubard 1131:692ddf04fc42 124 * services. isServiceDiscoveryActive() can be used to
vcoubard 1131:692ddf04fc42 125 * determine status, and a termination callback (if set up) will be invoked
vcoubard 1131:692ddf04fc42 126 * at the end. Service discovery can be terminated prematurely, if needed,
vcoubard 1131:692ddf04fc42 127 * using terminateServiceDiscovery().
vcoubard 1131:692ddf04fc42 128 *
vcoubard 1131:692ddf04fc42 129 * @param connectionHandle
vcoubard 1131:692ddf04fc42 130 * Handle for the connection with the peer.
vcoubard 1131:692ddf04fc42 131 * @param sc
vcoubard 1131:692ddf04fc42 132 * This is the application callback for a matching service. Note: service discovery may still be active
vcoubard 1131:692ddf04fc42 133 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1131:692ddf04fc42 134 * APIs from within this application callback might cause the
vcoubard 1131:692ddf04fc42 135 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1131:692ddf04fc42 136 * may be better to make a local copy of the discoveredService and
vcoubard 1131:692ddf04fc42 137 * wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 138 * service.
vcoubard 1131:692ddf04fc42 139 * @param matchingServiceUUID
vcoubard 1131:692ddf04fc42 140 * UUID-based filter for specifying a service in which the application is
vcoubard 1131:692ddf04fc42 141 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 1131:692ddf04fc42 142 * in which case it matches all services.
vcoubard 1131:692ddf04fc42 143 *
vcoubard 1131:692ddf04fc42 144 * @return
vcoubard 1131:692ddf04fc42 145 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
vcoubard 1131:692ddf04fc42 146 */
vcoubard 1131:692ddf04fc42 147 virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle,
vcoubard 1131:692ddf04fc42 148 ServiceDiscovery::ServiceCallback_t callback,
vcoubard 1131:692ddf04fc42 149 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
vcoubard 1131:692ddf04fc42 150 return launchServiceDiscovery(connectionHandle, callback, NULL, matchingServiceUUID); /* We take advantage of the property
vcoubard 1131:692ddf04fc42 151 * that providing NULL for the characteristic callback will result in
vcoubard 1131:692ddf04fc42 152 * characteristic discovery being skipped for each matching
vcoubard 1131:692ddf04fc42 153 * service. This allows for an inexpensive method to discover only
vcoubard 1131:692ddf04fc42 154 * services. Porters are free to override this. */
vcoubard 1131:692ddf04fc42 155 }
vcoubard 1131:692ddf04fc42 156
vcoubard 1131:692ddf04fc42 157 /**
vcoubard 1131:692ddf04fc42 158 * Launch service discovery for services. Once launched, service discovery will remain
vcoubard 1131:692ddf04fc42 159 * active with service-callbacks being issued back into the application for matching
vcoubard 1131:692ddf04fc42 160 * services. isServiceDiscoveryActive() can be used to
vcoubard 1131:692ddf04fc42 161 * determine status, and a termination callback (if set up) will be invoked
vcoubard 1131:692ddf04fc42 162 * at the end. Service discovery can be terminated prematurely, if needed,
vcoubard 1131:692ddf04fc42 163 * using terminateServiceDiscovery().
vcoubard 1131:692ddf04fc42 164 *
vcoubard 1131:692ddf04fc42 165 * @param connectionHandle
vcoubard 1131:692ddf04fc42 166 * Handle for the connection with the peer.
vcoubard 1131:692ddf04fc42 167 * @param sc
vcoubard 1131:692ddf04fc42 168 * This is the application callback for a matching service. Note: service discovery may still be active
vcoubard 1131:692ddf04fc42 169 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1131:692ddf04fc42 170 * APIs from within this application callback might cause the
vcoubard 1131:692ddf04fc42 171 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1131:692ddf04fc42 172 * may be better to make a local copy of the discoveredService and
vcoubard 1131:692ddf04fc42 173 * wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 174 * service.
vcoubard 1131:692ddf04fc42 175 * @param startHandle, endHandle
vcoubard 1131:692ddf04fc42 176 * Handle range within which to limit the search.
vcoubard 1131:692ddf04fc42 177 *
vcoubard 1131:692ddf04fc42 178 * @return
vcoubard 1131:692ddf04fc42 179 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
vcoubard 1131:692ddf04fc42 180 */
vcoubard 1131:692ddf04fc42 181 virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle,
vcoubard 1131:692ddf04fc42 182 ServiceDiscovery::ServiceCallback_t callback,
vcoubard 1131:692ddf04fc42 183 GattAttribute::Handle_t startHandle,
vcoubard 1131:692ddf04fc42 184 GattAttribute::Handle_t endHandle) {
vcoubard 1131:692ddf04fc42 185 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 186 (void)connectionHandle;
vcoubard 1131:692ddf04fc42 187 (void)callback;
vcoubard 1131:692ddf04fc42 188 (void)startHandle;
vcoubard 1131:692ddf04fc42 189 (void)endHandle;
vcoubard 1131:692ddf04fc42 190
vcoubard 1131:692ddf04fc42 191 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 192 }
vcoubard 1131:692ddf04fc42 193
vcoubard 1131:692ddf04fc42 194 /**
vcoubard 1131:692ddf04fc42 195 * Is service-discovery currently active?
vcoubard 1131:692ddf04fc42 196 */
vcoubard 1131:692ddf04fc42 197 virtual bool isServiceDiscoveryActive(void) const {
vcoubard 1131:692ddf04fc42 198 return false; /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 199 }
vcoubard 1131:692ddf04fc42 200
vcoubard 1131:692ddf04fc42 201 /**
vcoubard 1131:692ddf04fc42 202 * Terminate an ongoing service discovery. This should result in an
vcoubard 1131:692ddf04fc42 203 * invocation of TerminationCallback if service-discovery is active.
vcoubard 1131:692ddf04fc42 204 */
vcoubard 1131:692ddf04fc42 205 virtual void terminateServiceDiscovery(void) {
vcoubard 1131:692ddf04fc42 206 /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 207 }
vcoubard 1131:692ddf04fc42 208
vcoubard 1131:692ddf04fc42 209 /* Initiate a GATT Client read procedure by attribute-handle. */
vcoubard 1131:692ddf04fc42 210 virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
vcoubard 1131:692ddf04fc42 211 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 212 (void)connHandle;
vcoubard 1131:692ddf04fc42 213 (void)attributeHandle;
vcoubard 1131:692ddf04fc42 214 (void)offset;
vcoubard 1131:692ddf04fc42 215
vcoubard 1131:692ddf04fc42 216 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 217 }
vcoubard 1131:692ddf04fc42 218
vcoubard 1131:692ddf04fc42 219 /**
vcoubard 1131:692ddf04fc42 220 * Initiate a GATT Client write procedure.
vcoubard 1131:692ddf04fc42 221 *
vcoubard 1131:692ddf04fc42 222 * @param[in] cmd
vcoubard 1135:22aada733dbd 223 * Command can be either a write-request (which generates a
vcoubard 1135:22aada733dbd 224 * matching response from the peripheral), or a write-command
vcoubard 1131:692ddf04fc42 225 * (which doesn't require the connected peer to respond).
vcoubard 1131:692ddf04fc42 226 * @param[in] connHandle
vcoubard 1131:692ddf04fc42 227 * Connection handle.
vcoubard 1131:692ddf04fc42 228 * @param[in] attributeHandle
vcoubard 1131:692ddf04fc42 229 * Handle for the target attribtue on the remote GATT server.
vcoubard 1131:692ddf04fc42 230 * @param[in] length
vcoubard 1131:692ddf04fc42 231 * Length of the new value.
vcoubard 1131:692ddf04fc42 232 * @param[in] value
vcoubard 1131:692ddf04fc42 233 * New value being written.
vcoubard 1131:692ddf04fc42 234 */
vcoubard 1131:692ddf04fc42 235 virtual ble_error_t write(GattClient::WriteOp_t cmd,
vcoubard 1131:692ddf04fc42 236 Gap::Handle_t connHandle,
vcoubard 1131:692ddf04fc42 237 GattAttribute::Handle_t attributeHandle,
vcoubard 1131:692ddf04fc42 238 size_t length,
vcoubard 1131:692ddf04fc42 239 const uint8_t *value) const {
vcoubard 1131:692ddf04fc42 240 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 241 (void)cmd;
vcoubard 1131:692ddf04fc42 242 (void)connHandle;
vcoubard 1131:692ddf04fc42 243 (void)attributeHandle;
vcoubard 1131:692ddf04fc42 244 (void)length;
vcoubard 1131:692ddf04fc42 245 (void)value;
vcoubard 1131:692ddf04fc42 246
vcoubard 1131:692ddf04fc42 247 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 248 }
vcoubard 1131:692ddf04fc42 249
vcoubard 1131:692ddf04fc42 250 /* Event callback handlers. */
vcoubard 1131:692ddf04fc42 251 public:
vcoubard 1131:692ddf04fc42 252 /**
vcoubard 1135:22aada733dbd 253 * Set up a callback for read response events.
vcoubard 1135:22aada733dbd 254 * It is possible to remove registered callbacks using
vcoubard 1131:692ddf04fc42 255 * onDataRead().detach(callbackToRemove)
vcoubard 1131:692ddf04fc42 256 */
vcoubard 1131:692ddf04fc42 257 void onDataRead(ReadCallback_t callback) {
vcoubard 1131:692ddf04fc42 258 onDataReadCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 259 }
vcoubard 1131:692ddf04fc42 260
vcoubard 1131:692ddf04fc42 261 /**
vcoubard 1131:692ddf04fc42 262 * @brief provide access to the callchain of read callbacks
vcoubard 1131:692ddf04fc42 263 * It is possible to register callbacks using onDataRead().add(callback);
vcoubard 1135:22aada733dbd 264 * It is possible to unregister callbacks using onDataRead().detach(callback)
vcoubard 1131:692ddf04fc42 265 * @return The read callbacks chain
vcoubard 1131:692ddf04fc42 266 */
vcoubard 1131:692ddf04fc42 267 ReadCallbackChain_t& onDataRead() {
vcoubard 1131:692ddf04fc42 268 return onDataReadCallbackChain;
vcoubard 1131:692ddf04fc42 269 }
vcoubard 1131:692ddf04fc42 270
vcoubard 1131:692ddf04fc42 271 /**
vcoubard 1131:692ddf04fc42 272 * Set up a callback for write response events.
vcoubard 1135:22aada733dbd 273 * It is possible to remove registered callbacks using
vcoubard 1131:692ddf04fc42 274 * onDataWritten().detach(callbackToRemove).
vcoubard 1131:692ddf04fc42 275 * @Note: Write commands (issued using writeWoResponse) don't generate a response.
vcoubard 1131:692ddf04fc42 276 */
vcoubard 1131:692ddf04fc42 277 void onDataWritten(WriteCallback_t callback) {
vcoubard 1131:692ddf04fc42 278 onDataWriteCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 279 }
vcoubard 1131:692ddf04fc42 280
vcoubard 1131:692ddf04fc42 281 /**
vcoubard 1131:692ddf04fc42 282 * @brief provide access to the callchain of data written callbacks
vcoubard 1131:692ddf04fc42 283 * It is possible to register callbacks using onDataWritten().add(callback);
vcoubard 1135:22aada733dbd 284 * It is possible to unregister callbacks using onDataWritten().detach(callback)
vcoubard 1131:692ddf04fc42 285 * @return The data written callbacks chain
vcoubard 1131:692ddf04fc42 286 */
vcoubard 1135:22aada733dbd 287 WriteCallbackChain_t& onDataWritten() {
vcoubard 1131:692ddf04fc42 288 return onDataWriteCallbackChain;
vcoubard 1131:692ddf04fc42 289 }
vcoubard 1131:692ddf04fc42 290
vcoubard 1131:692ddf04fc42 291 /**
vcoubard 1131:692ddf04fc42 292 * Set up a callback for write response events.
vcoubard 1131:692ddf04fc42 293 * @Note: Write commands (issued using writeWoResponse) don't generate a response.
vcoubard 1131:692ddf04fc42 294 *
vcoubard 1131:692ddf04fc42 295 * @note: This API is now *deprecated* and will be dropped in the future.
vcoubard 1131:692ddf04fc42 296 * Please use onDataWritten() instead.
vcoubard 1131:692ddf04fc42 297 */
vcoubard 1131:692ddf04fc42 298 void onDataWrite(WriteCallback_t callback) {
vcoubard 1131:692ddf04fc42 299 onDataWritten(callback);
vcoubard 1131:692ddf04fc42 300 }
vcoubard 1131:692ddf04fc42 301
vcoubard 1131:692ddf04fc42 302 /**
vcoubard 1131:692ddf04fc42 303 * Set up a callback for when serviceDiscovery terminates.
vcoubard 1131:692ddf04fc42 304 */
vcoubard 1131:692ddf04fc42 305 virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
vcoubard 1131:692ddf04fc42 306 (void)callback; /* Avoid compiler warnings about ununsed variables. */
vcoubard 1131:692ddf04fc42 307
vcoubard 1131:692ddf04fc42 308 /* Requesting action from porters: override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 309 }
vcoubard 1131:692ddf04fc42 310
vcoubard 1131:692ddf04fc42 311 /**
vcoubard 1135:22aada733dbd 312 * @brief launch discovery of descriptors for a given characteristic
vcoubard 1135:22aada733dbd 313 * @details This function will discover all descriptors available for a
vcoubard 1135:22aada733dbd 314 * specific characteristic.
vcoubard 1135:22aada733dbd 315 *
vcoubard 1135:22aada733dbd 316 * @param characteristic[in] The characteristic targeted by this discovery
vcoubard 1135:22aada733dbd 317 * procedure
vcoubard 1135:22aada733dbd 318 * @param discoveryCallback[in] User function called each time a descriptor
vcoubard 1135:22aada733dbd 319 * is found during the procedure.
vcoubard 1135:22aada733dbd 320 * @param terminationCallback[in] User provided function which will be called
vcoubard 1135:22aada733dbd 321 * once the discovery procedure is terminating. This will get called when all
vcoubard 1135:22aada733dbd 322 * the descriptors have been discovered or if an error occur during the discovery
vcoubard 1135:22aada733dbd 323 * procedure.
vcoubard 1135:22aada733dbd 324 *
vcoubard 1135:22aada733dbd 325 * @return
vcoubard 1135:22aada733dbd 326 * BLE_ERROR_NONE if characteristic descriptor discovery is launched
vcoubard 1135:22aada733dbd 327 * successfully; else an appropriate error.
vcoubard 1135:22aada733dbd 328 */
vcoubard 1135:22aada733dbd 329 virtual ble_error_t discoverCharacteristicDescriptors(
vcoubard 1135:22aada733dbd 330 const DiscoveredCharacteristic& characteristic,
vcoubard 1135:22aada733dbd 331 const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback,
vcoubard 1135:22aada733dbd 332 const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) {
vcoubard 1135:22aada733dbd 333 (void) characteristic;
vcoubard 1135:22aada733dbd 334 (void) discoveryCallback;
vcoubard 1135:22aada733dbd 335 (void) terminationCallback;
vcoubard 1135:22aada733dbd 336 /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1135:22aada733dbd 337 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 338 }
vcoubard 1135:22aada733dbd 339
vcoubard 1135:22aada733dbd 340 /**
vcoubard 1135:22aada733dbd 341 * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic
vcoubard 1135:22aada733dbd 342 * or not.
vcoubard 1135:22aada733dbd 343 * @param characteristic[in] The characteristic concerned by the descriptors discovery.
vcoubard 1135:22aada733dbd 344 * @return true if a descriptors discovery is active for the characteristic in input; otherwise false.
vcoubard 1135:22aada733dbd 345 */
vcoubard 1135:22aada733dbd 346 virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const
vcoubard 1135:22aada733dbd 347 {
vcoubard 1135:22aada733dbd 348 (void) characteristic;
vcoubard 1135:22aada733dbd 349 return false; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1135:22aada733dbd 350 }
vcoubard 1135:22aada733dbd 351
vcoubard 1135:22aada733dbd 352 /**
vcoubard 1135:22aada733dbd 353 * @brief Terminate an ongoing characteristic descriptor discovery.
vcoubard 1155:e28c7aac64ab 354 * @detail This should result in an invocation of the TerminationCallback if
vcoubard 1135:22aada733dbd 355 * the characteristic descriptor discovery is active.
vcoubard 1135:22aada733dbd 356 * @param characteristic[in] The characteristic on which the running descriptors
vcoubard 1135:22aada733dbd 357 * discovery should be stopped.
vcoubard 1135:22aada733dbd 358 */
vcoubard 1135:22aada733dbd 359 virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) {
vcoubard 1135:22aada733dbd 360 /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1135:22aada733dbd 361 (void) characteristic;
vcoubard 1135:22aada733dbd 362 }
vcoubard 1135:22aada733dbd 363
vcoubard 1135:22aada733dbd 364 /**
vcoubard 1131:692ddf04fc42 365 * Set up a callback for when the GATT client receives an update event
vcoubard 1131:692ddf04fc42 366 * corresponding to a change in the value of a characteristic on the remote
vcoubard 1131:692ddf04fc42 367 * GATT server.
vcoubard 1131:692ddf04fc42 368 * It is possible to remove registered callbacks using onHVX().detach(callbackToRemove).
vcoubard 1131:692ddf04fc42 369 */
vcoubard 1131:692ddf04fc42 370 void onHVX(HVXCallback_t callback) {
vcoubard 1131:692ddf04fc42 371 onHVXCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 372 }
vcoubard 1131:692ddf04fc42 373
vcoubard 1135:22aada733dbd 374 /**
vcoubard 1135:22aada733dbd 375 * Setup a callback to be invoked to notify the user application that the
vcoubard 1135:22aada733dbd 376 * GattClient instance is about to shutdown (possibly as a result of a call
vcoubard 1135:22aada733dbd 377 * to BLE::shutdown()).
vcoubard 1135:22aada733dbd 378 *
vcoubard 1135:22aada733dbd 379 * @Note: It is possible to chain together multiple onShutdown callbacks
vcoubard 1135:22aada733dbd 380 * (potentially from different modules of an application) to be notified
vcoubard 1135:22aada733dbd 381 * before the GattClient is shutdown.
vcoubard 1135:22aada733dbd 382 *
vcoubard 1135:22aada733dbd 383 * @Note: It is also possible to set up a callback into a member function of
vcoubard 1135:22aada733dbd 384 * some object.
vcoubard 1135:22aada733dbd 385 *
vcoubard 1135:22aada733dbd 386 * @Note It is possible to unregister a callback using onShutdown().detach(callback)
vcoubard 1135:22aada733dbd 387 */
vcoubard 1135:22aada733dbd 388 void onShutdown(const GattClientShutdownCallback_t& callback) {
vcoubard 1135:22aada733dbd 389 shutdownCallChain.add(callback);
vcoubard 1135:22aada733dbd 390 }
vcoubard 1135:22aada733dbd 391 template <typename T>
vcoubard 1135:22aada733dbd 392 void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
vcoubard 1135:22aada733dbd 393 shutdownCallChain.add(objPtr, memberPtr);
vcoubard 1135:22aada733dbd 394 }
vcoubard 1135:22aada733dbd 395
vcoubard 1135:22aada733dbd 396 /**
vcoubard 1135:22aada733dbd 397 * @brief provide access to the callchain of shutdown event callbacks
vcoubard 1135:22aada733dbd 398 * It is possible to register callbacks using onShutdown().add(callback);
vcoubard 1135:22aada733dbd 399 * It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard 1135:22aada733dbd 400 * @return The shutdown event callbacks chain
vcoubard 1135:22aada733dbd 401 */
vcoubard 1135:22aada733dbd 402 GattClientShutdownCallbackChain_t& onShutdown() {
vcoubard 1135:22aada733dbd 403 return shutdownCallChain;
vcoubard 1135:22aada733dbd 404 }
vcoubard 1131:692ddf04fc42 405
vcoubard 1131:692ddf04fc42 406 /**
vcoubard 1131:692ddf04fc42 407 * @brief provide access to the callchain of HVX callbacks
vcoubard 1131:692ddf04fc42 408 * It is possible to register callbacks using onHVX().add(callback);
vcoubard 1135:22aada733dbd 409 * It is possible to unregister callbacks using onHVX().detach(callback)
vcoubard 1131:692ddf04fc42 410 * @return The HVX callbacks chain
vcoubard 1131:692ddf04fc42 411 */
vcoubard 1135:22aada733dbd 412 HVXCallbackChain_t& onHVX() {
vcoubard 1131:692ddf04fc42 413 return onHVXCallbackChain;
vcoubard 1131:692ddf04fc42 414 }
vcoubard 1131:692ddf04fc42 415
vcoubard 1135:22aada733dbd 416 public:
vcoubard 1135:22aada733dbd 417 /**
vcoubard 1135:22aada733dbd 418 * Notify all registered onShutdown callbacks that the GattClient is
vcoubard 1135:22aada733dbd 419 * about to be shutdown and clear all GattClient state of the
vcoubard 1135:22aada733dbd 420 * associated object.
vcoubard 1135:22aada733dbd 421 *
vcoubard 1135:22aada733dbd 422 * This function is meant to be overridden in the platform-specific
vcoubard 1135:22aada733dbd 423 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1135:22aada733dbd 424 * state and not the data held in GattClient members. This shall be achieved
vcoubard 1135:22aada733dbd 425 * by a call to GattClient::reset() from the sub-class' reset()
vcoubard 1135:22aada733dbd 426 * implementation.
vcoubard 1135:22aada733dbd 427 *
vcoubard 1135:22aada733dbd 428 * @return BLE_ERROR_NONE on success.
vcoubard 1135:22aada733dbd 429 */
vcoubard 1135:22aada733dbd 430 virtual ble_error_t reset(void) {
vcoubard 1135:22aada733dbd 431 /* Notify that the instance is about to shutdown */
vcoubard 1135:22aada733dbd 432 shutdownCallChain.call(this);
vcoubard 1135:22aada733dbd 433 shutdownCallChain.clear();
vcoubard 1135:22aada733dbd 434
vcoubard 1135:22aada733dbd 435 onDataReadCallbackChain.clear();
vcoubard 1135:22aada733dbd 436 onDataWriteCallbackChain.clear();
vcoubard 1135:22aada733dbd 437 onHVXCallbackChain.clear();
vcoubard 1135:22aada733dbd 438
vcoubard 1135:22aada733dbd 439 return BLE_ERROR_NONE;
vcoubard 1135:22aada733dbd 440 }
vcoubard 1135:22aada733dbd 441
vcoubard 1131:692ddf04fc42 442 protected:
vcoubard 1131:692ddf04fc42 443 GattClient() {
vcoubard 1131:692ddf04fc42 444 /* Empty */
vcoubard 1131:692ddf04fc42 445 }
vcoubard 1131:692ddf04fc42 446
vcoubard 1131:692ddf04fc42 447 /* Entry points for the underlying stack to report events back to the user. */
vcoubard 1131:692ddf04fc42 448 public:
vcoubard 1131:692ddf04fc42 449 void processReadResponse(const GattReadCallbackParams *params) {
vcoubard 1131:692ddf04fc42 450 onDataReadCallbackChain(params);
vcoubard 1131:692ddf04fc42 451 }
vcoubard 1131:692ddf04fc42 452
vcoubard 1131:692ddf04fc42 453 void processWriteResponse(const GattWriteCallbackParams *params) {
vcoubard 1131:692ddf04fc42 454 onDataWriteCallbackChain(params);
vcoubard 1131:692ddf04fc42 455 }
vcoubard 1131:692ddf04fc42 456
vcoubard 1131:692ddf04fc42 457 void processHVXEvent(const GattHVXCallbackParams *params) {
vcoubard 1131:692ddf04fc42 458 if (onHVXCallbackChain) {
vcoubard 1131:692ddf04fc42 459 onHVXCallbackChain(params);
vcoubard 1131:692ddf04fc42 460 }
vcoubard 1131:692ddf04fc42 461 }
vcoubard 1131:692ddf04fc42 462
vcoubard 1131:692ddf04fc42 463 protected:
vcoubard 1135:22aada733dbd 464 ReadCallbackChain_t onDataReadCallbackChain;
vcoubard 1135:22aada733dbd 465 WriteCallbackChain_t onDataWriteCallbackChain;
vcoubard 1135:22aada733dbd 466 HVXCallbackChain_t onHVXCallbackChain;
vcoubard 1135:22aada733dbd 467 GattClientShutdownCallbackChain_t shutdownCallChain;
vcoubard 1131:692ddf04fc42 468
vcoubard 1131:692ddf04fc42 469 private:
vcoubard 1131:692ddf04fc42 470 /* Disallow copy and assignment. */
vcoubard 1131:692ddf04fc42 471 GattClient(const GattClient &);
vcoubard 1131:692ddf04fc42 472 GattClient& operator=(const GattClient &);
vcoubard 1131:692ddf04fc42 473 };
vcoubard 1131:692ddf04fc42 474
rgrover1 716:11b41f651697 475 #endif // ifndef __GATT_CLIENT_H__