Bluetooth Low Energy
High level Bluetooth Low Energy API and radio abstraction layer
Dependents: BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more
Overview
The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.
Supported Services
Supported services can be found in the BLE_API/services folder.
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?
| User | Revision | Line number | New 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__ |