Andrew Fox / BLE_API

add "LE Device Address" 0x1B to advertising data types

Fork of BLE_API by Bluetooth Low Energy

ble/GattClient.h@1088:709ebced28ab, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:49 2016 +0000
Revision:
1088:709ebced28ab
Parent:
1082:127667021827
Child:
1089:8e810a8e083e
Synchronized with git rev 0781293b

Author: Andres Amaya Garcia

Add onShutdown to register callbacks



Add an onShutdown() function to Gap, GattClient, GattServer and

SecurityManager. The callbacks are added to a private callback chain in each of

the instances. The callbacks will be executed inside each object's reset()

function BEFORE the state of the instance is cleared. The developers of the

platform-specific implementation must call the parent class' reset() function

for the callbacks to be executed.



Finally, an onShutdown() function that returns the shutdown callchain is added

to allow detaching callbacks.

Who changed what in which revision?

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