Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/GattClient.h@1179:4ab722f8dca0, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:30 2016 +0100
Revision:
1179:4ab722f8dca0
Parent:
1164:7e84487d45fc
Child:
1183:1589830dbdb7
Synchronized with git rev ca632aaf

Author: Andres Amaya Garcia

Update Gap state after advertising times out



The BLE API was not updating the Gap internal state when the advertising stops

because of a user timeout. This commit fixes the issue by updating the internal

state structure in Gap just before the registered callbacks are notified of the

advertising timeout.

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 1179:4ab722f8dca0 59 * @param connectionHandle
vcoubard 1179:4ab722f8dca0 60 * Handle for the connection with the peer.
vcoubard 1179:4ab722f8dca0 61 * @param sc
vcoubard 1179:4ab722f8dca0 62 * This is the application callback for a matching service. Taken as
vcoubard 1179:4ab722f8dca0 63 * NULL by default. Note: service discovery may still be active
vcoubard 1179:4ab722f8dca0 64 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1179:4ab722f8dca0 65 * APIs from within this application callback might cause the
vcoubard 1179:4ab722f8dca0 66 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1179:4ab722f8dca0 67 * may be better to make a local copy of the discoveredService and
vcoubard 1179:4ab722f8dca0 68 * wait for service discovery to terminate before operating on the
vcoubard 1179:4ab722f8dca0 69 * service.
vcoubard 1179:4ab722f8dca0 70 * @param cc
vcoubard 1179:4ab722f8dca0 71 * This is the application callback for a matching characteristic.
vcoubard 1179:4ab722f8dca0 72 * Taken as NULL by default. Note: service discovery may still be
vcoubard 1179:4ab722f8dca0 73 * active when this callback is issued; calling asynchronous
vcoubard 1179:4ab722f8dca0 74 * BLE-stack APIs from within this application callback might cause
vcoubard 1179:4ab722f8dca0 75 * the stack to abort service discovery. If this becomes an issue,
vcoubard 1179:4ab722f8dca0 76 * it may be better to make a local copy of the discoveredCharacteristic
vcoubard 1179:4ab722f8dca0 77 * and wait for service discovery to terminate before operating on the
vcoubard 1179:4ab722f8dca0 78 * characteristic.
vcoubard 1179:4ab722f8dca0 79 * @param matchingServiceUUID
vcoubard 1179:4ab722f8dca0 80 * UUID-based filter for specifying a service in which the application is
vcoubard 1179:4ab722f8dca0 81 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 1179:4ab722f8dca0 82 * in which case it matches all services. If characteristic-UUID
vcoubard 1179:4ab722f8dca0 83 * filter (below) is set to the wildcard value, then a service
vcoubard 1179:4ab722f8dca0 84 * callback will be invoked for the matching service (or for every
vcoubard 1179:4ab722f8dca0 85 * service if the service filter is a wildcard).
vcoubard 1179:4ab722f8dca0 86 * @param matchingCharacteristicUUIDIn
vcoubard 1179:4ab722f8dca0 87 * UUID-based filter for specifying characteristic in which the application
vcoubard 1179:4ab722f8dca0 88 * is interested. By default it is set as the wildcard UUID_UKNOWN
vcoubard 1179:4ab722f8dca0 89 * to match against any characteristic. If both service-UUID
vcoubard 1179:4ab722f8dca0 90 * filter and characteristic-UUID filter are used with non-wildcard
vcoubard 1179:4ab722f8dca0 91 * values, then only a single characteristic callback is
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 129 * @param connectionHandle
vcoubard 1179:4ab722f8dca0 130 * Handle for the connection with the peer.
vcoubard 1179:4ab722f8dca0 131 * @param sc
vcoubard 1179:4ab722f8dca0 132 * This is the application callback for a matching service. Note: service discovery may still be active
vcoubard 1179:4ab722f8dca0 133 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1179:4ab722f8dca0 134 * APIs from within this application callback might cause the
vcoubard 1179:4ab722f8dca0 135 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1179:4ab722f8dca0 136 * may be better to make a local copy of the discoveredService and
vcoubard 1179:4ab722f8dca0 137 * wait for service discovery to terminate before operating on the
vcoubard 1179:4ab722f8dca0 138 * service.
vcoubard 1179:4ab722f8dca0 139 * @param matchingServiceUUID
vcoubard 1179:4ab722f8dca0 140 * UUID-based filter for specifying a service in which the application is
vcoubard 1179:4ab722f8dca0 141 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 165 * @param connectionHandle
vcoubard 1179:4ab722f8dca0 166 * Handle for the connection with the peer.
vcoubard 1179:4ab722f8dca0 167 * @param sc
vcoubard 1179:4ab722f8dca0 168 * This is the application callback for a matching service. Note: service discovery may still be active
vcoubard 1179:4ab722f8dca0 169 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1179:4ab722f8dca0 170 * APIs from within this application callback might cause the
vcoubard 1179:4ab722f8dca0 171 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1179:4ab722f8dca0 172 * may be better to make a local copy of the discoveredService and
vcoubard 1179:4ab722f8dca0 173 * wait for service discovery to terminate before operating on the
vcoubard 1179:4ab722f8dca0 174 * service.
vcoubard 1179:4ab722f8dca0 175 * @param startHandle, endHandle
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 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 1179:4ab722f8dca0 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 1179:4ab722f8dca0 254 * It is possible to remove registered callbacks using
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 262 * @brief provide access to the callchain of read callbacks
vcoubard 1179:4ab722f8dca0 263 * It is possible to register callbacks using onDataRead().add(callback);
vcoubard 1179:4ab722f8dca0 264 * It is possible to unregister callbacks using onDataRead().detach(callback)
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 273 * It is possible to remove registered callbacks using
vcoubard 1131:692ddf04fc42 274 * onDataWritten().detach(callbackToRemove).
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 282 * @brief provide access to the callchain of data written callbacks
vcoubard 1179:4ab722f8dca0 283 * It is possible to register callbacks using onDataWritten().add(callback);
vcoubard 1179:4ab722f8dca0 284 * It is possible to unregister callbacks using onDataWritten().detach(callback)
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 293 * @Note: Write commands (issued using writeWoResponse) don't generate a response.
vcoubard 1131:692ddf04fc42 294 *
vcoubard 1179:4ab722f8dca0 295 * @note: This API is now *deprecated* and will be dropped in the future.
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 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 1179:4ab722f8dca0 314 * specific characteristic.
vcoubard 1135:22aada733dbd 315 *
vcoubard 1179:4ab722f8dca0 316 * @param characteristic[in] The characteristic targeted by this discovery
vcoubard 1179:4ab722f8dca0 317 * procedure
vcoubard 1179:4ab722f8dca0 318 * @param discoveryCallback[in] User function called each time a descriptor
vcoubard 1179:4ab722f8dca0 319 * is found during the procedure.
vcoubard 1179:4ab722f8dca0 320 * @param terminationCallback[in] User provided function which will be called
vcoubard 1179:4ab722f8dca0 321 * once the discovery procedure is terminating. This will get called when all
vcoubard 1179:4ab722f8dca0 322 * the descriptors have been discovered or if an error occur during the discovery
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 341 * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic
vcoubard 1179:4ab722f8dca0 342 * or not.
vcoubard 1179:4ab722f8dca0 343 * @param characteristic[in] The characteristic concerned by the descriptors discovery.
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 354 * @detail This should result in an invocation of the TerminationCallback if
vcoubard 1179:4ab722f8dca0 355 * the characteristic descriptor discovery is active.
vcoubard 1179:4ab722f8dca0 356 * @param characteristic[in] The characteristic on which the running descriptors
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 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 1179:4ab722f8dca0 367 * GATT server.
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 379 * @Note: It is possible to chain together multiple onShutdown callbacks
vcoubard 1179:4ab722f8dca0 380 * (potentially from different modules of an application) to be notified
vcoubard 1179:4ab722f8dca0 381 * before the GattClient is shutdown.
vcoubard 1135:22aada733dbd 382 *
vcoubard 1179:4ab722f8dca0 383 * @Note: It is also possible to set up a callback into a member function of
vcoubard 1179:4ab722f8dca0 384 * some object.
vcoubard 1135:22aada733dbd 385 *
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 397 * @brief provide access to the callchain of shutdown event callbacks
vcoubard 1179:4ab722f8dca0 398 * It is possible to register callbacks using onShutdown().add(callback);
vcoubard 1179:4ab722f8dca0 399 * It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard 1179:4ab722f8dca0 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 1179:4ab722f8dca0 407 * @brief provide access to the callchain of HVX callbacks
vcoubard 1179:4ab722f8dca0 408 * It is possible to register callbacks using onHVX().add(callback);
vcoubard 1179:4ab722f8dca0 409 * It is possible to unregister callbacks using onHVX().detach(callback)
vcoubard 1179:4ab722f8dca0 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
vcoubard 1179:4ab722f8dca0 475 #endif // ifndef __GATT_CLIENT_H__