EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

features/FEATURE_BLE/ble/GattClient.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

UserRevisionLine numberNew contents of line
be_bryan 0:b74591d5ab33 1 /* mbed Microcontroller Library
be_bryan 0:b74591d5ab33 2 * Copyright (c) 2006-2013 ARM Limited
be_bryan 0:b74591d5ab33 3 *
be_bryan 0:b74591d5ab33 4 * Licensed under the Apache License, Version 2.0 (the "License");
be_bryan 0:b74591d5ab33 5 * you may not use this file except in compliance with the License.
be_bryan 0:b74591d5ab33 6 * You may obtain a copy of the License at
be_bryan 0:b74591d5ab33 7 *
be_bryan 0:b74591d5ab33 8 * http://www.apache.org/licenses/LICENSE-2.0
be_bryan 0:b74591d5ab33 9 *
be_bryan 0:b74591d5ab33 10 * Unless required by applicable law or agreed to in writing, software
be_bryan 0:b74591d5ab33 11 * distributed under the License is distributed on an "AS IS" BASIS,
be_bryan 0:b74591d5ab33 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
be_bryan 0:b74591d5ab33 13 * See the License for the specific language governing permissions and
be_bryan 0:b74591d5ab33 14 * limitations under the License.
be_bryan 0:b74591d5ab33 15 */
be_bryan 0:b74591d5ab33 16
be_bryan 0:b74591d5ab33 17 #ifndef MBED_GATT_CLIENT_H__
be_bryan 0:b74591d5ab33 18 #define MBED_GATT_CLIENT_H__
be_bryan 0:b74591d5ab33 19
be_bryan 0:b74591d5ab33 20 #include "Gap.h"
be_bryan 0:b74591d5ab33 21 #include "GattAttribute.h"
be_bryan 0:b74591d5ab33 22 #include "ServiceDiscovery.h"
be_bryan 0:b74591d5ab33 23 #include "CharacteristicDescriptorDiscovery.h"
be_bryan 0:b74591d5ab33 24
be_bryan 0:b74591d5ab33 25 #include "GattCallbackParamTypes.h"
be_bryan 0:b74591d5ab33 26
be_bryan 0:b74591d5ab33 27 #include "CallChainOfFunctionPointersWithContext.h"
be_bryan 0:b74591d5ab33 28
be_bryan 0:b74591d5ab33 29 /**
be_bryan 0:b74591d5ab33 30 * @addtogroup ble
be_bryan 0:b74591d5ab33 31 * @{
be_bryan 0:b74591d5ab33 32 * @addtogroup gatt
be_bryan 0:b74591d5ab33 33 * @{
be_bryan 0:b74591d5ab33 34 * @addtogroup client
be_bryan 0:b74591d5ab33 35 * @{
be_bryan 0:b74591d5ab33 36 */
be_bryan 0:b74591d5ab33 37
be_bryan 0:b74591d5ab33 38 /**
be_bryan 0:b74591d5ab33 39 * Define procedures required for interacting with a distant GATT server.
be_bryan 0:b74591d5ab33 40 *
be_bryan 0:b74591d5ab33 41 * @par Discovery procedures
be_bryan 0:b74591d5ab33 42 *
be_bryan 0:b74591d5ab33 43 * A GATT server hosts a fixed set of services. These services are a logical
be_bryan 0:b74591d5ab33 44 * composition of characteristics that may be discovered, read, written or also
be_bryan 0:b74591d5ab33 45 * broadcast their state to a connected client. These characteristics may also
be_bryan 0:b74591d5ab33 46 * contain metainformation named characteristic descriptors. A characteristic
be_bryan 0:b74591d5ab33 47 * descriptor may be used to indicate the unit used for a characteristic value,
be_bryan 0:b74591d5ab33 48 * describe in a textual form the characterisic purpose or allow a client to
be_bryan 0:b74591d5ab33 49 * register for notification of updates of the characteristic value.
be_bryan 0:b74591d5ab33 50 *
be_bryan 0:b74591d5ab33 51 * Prior to any interaction with server characteristic, a GATT client
be_bryan 0:b74591d5ab33 52 * discovers the layout of the services and characteristics present on the
be_bryan 0:b74591d5ab33 53 * server.
be_bryan 0:b74591d5ab33 54 *
be_bryan 0:b74591d5ab33 55 * The layout of the descriptors of a characteristic may also be issued to
be_bryan 0:b74591d5ab33 56 * as an extra discovery step.
be_bryan 0:b74591d5ab33 57 *
be_bryan 0:b74591d5ab33 58 * @par Attribute manipulation
be_bryan 0:b74591d5ab33 59 *
be_bryan 0:b74591d5ab33 60 * As a result of the discovery process, the client can start interacting with
be_bryan 0:b74591d5ab33 61 * the characteristic discovered. Depending on the characteristic properties
be_bryan 0:b74591d5ab33 62 * (acquired during discovery), a client can read or write the value of a given
be_bryan 0:b74591d5ab33 63 * characteristic.
be_bryan 0:b74591d5ab33 64 *
be_bryan 0:b74591d5ab33 65 * Mbed BLE abstracts most read and write operations to offer a single API that
be_bryan 0:b74591d5ab33 66 * can be used to read or write characteristics values. Application code does not
be_bryan 0:b74591d5ab33 67 * have to handle the fragmentation/reassembly process necessary if the attribute
be_bryan 0:b74591d5ab33 68 * value to transported cannot fit in a single data packet.
be_bryan 0:b74591d5ab33 69 *
be_bryan 0:b74591d5ab33 70 * @par Server Initiated events
be_bryan 0:b74591d5ab33 71 *
be_bryan 0:b74591d5ab33 72 * If a characteristic has to notify or indicate a property set; then, a client may
be_bryan 0:b74591d5ab33 73 * register to a notification or indication from the characteristic. When the
be_bryan 0:b74591d5ab33 74 * server updates the characteristic value, the server can forward the
be_bryan 0:b74591d5ab33 75 * new value to the registered clients. The notification/indication mechanism
be_bryan 0:b74591d5ab33 76 * prevents polling from the client and therefore minimize the transactions
be_bryan 0:b74591d5ab33 77 * involved between a client and a server.
be_bryan 0:b74591d5ab33 78 *
be_bryan 0:b74591d5ab33 79 * Registration is made by writing the Client Characteristic Configuration
be_bryan 0:b74591d5ab33 80 * Descriptor, which is present in the characteristic if the notify or
be_bryan 0:b74591d5ab33 81 * indicate properties are set. The client discovers that descriptor
be_bryan 0:b74591d5ab33 82 * if it intends to register to server initiated events.
be_bryan 0:b74591d5ab33 83 */
be_bryan 0:b74591d5ab33 84 class GattClient {
be_bryan 0:b74591d5ab33 85 public:
be_bryan 0:b74591d5ab33 86 /**
be_bryan 0:b74591d5ab33 87 * Attribute read event handler.
be_bryan 0:b74591d5ab33 88 *
be_bryan 0:b74591d5ab33 89 * @see GattClient::onDataRead().
be_bryan 0:b74591d5ab33 90 */
be_bryan 0:b74591d5ab33 91 typedef FunctionPointerWithContext<const GattReadCallbackParams*>
be_bryan 0:b74591d5ab33 92 ReadCallback_t;
be_bryan 0:b74591d5ab33 93
be_bryan 0:b74591d5ab33 94 /**
be_bryan 0:b74591d5ab33 95 * Callchain of attribute read event handlers.
be_bryan 0:b74591d5ab33 96 */
be_bryan 0:b74591d5ab33 97 typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams*>
be_bryan 0:b74591d5ab33 98 ReadCallbackChain_t;
be_bryan 0:b74591d5ab33 99
be_bryan 0:b74591d5ab33 100 /**
be_bryan 0:b74591d5ab33 101 * GATT write operations.
be_bryan 0:b74591d5ab33 102 */
be_bryan 0:b74591d5ab33 103 enum WriteOp_t {
be_bryan 0:b74591d5ab33 104 /**
be_bryan 0:b74591d5ab33 105 * Write request.
be_bryan 0:b74591d5ab33 106 *
be_bryan 0:b74591d5ab33 107 * It is used to request the server to write the value of an attribute
be_bryan 0:b74591d5ab33 108 * and acknowledge that this has been achieved in a Write Response.
be_bryan 0:b74591d5ab33 109 */
be_bryan 0:b74591d5ab33 110 GATT_OP_WRITE_REQ = 0x01,
be_bryan 0:b74591d5ab33 111
be_bryan 0:b74591d5ab33 112 /**
be_bryan 0:b74591d5ab33 113 * Write command.
be_bryan 0:b74591d5ab33 114 *
be_bryan 0:b74591d5ab33 115 * It is used to request the server to write the value of an attribute.
be_bryan 0:b74591d5ab33 116 * The server does not acknowledge the status of the operation.
be_bryan 0:b74591d5ab33 117 */
be_bryan 0:b74591d5ab33 118 GATT_OP_WRITE_CMD = 0x02,
be_bryan 0:b74591d5ab33 119 };
be_bryan 0:b74591d5ab33 120
be_bryan 0:b74591d5ab33 121 /**
be_bryan 0:b74591d5ab33 122 * Attribute write event handler.
be_bryan 0:b74591d5ab33 123 *
be_bryan 0:b74591d5ab33 124 * @see GattClient::onDataWrite().
be_bryan 0:b74591d5ab33 125 */
be_bryan 0:b74591d5ab33 126 typedef FunctionPointerWithContext<const GattWriteCallbackParams*>
be_bryan 0:b74591d5ab33 127 WriteCallback_t;
be_bryan 0:b74591d5ab33 128
be_bryan 0:b74591d5ab33 129 /**
be_bryan 0:b74591d5ab33 130 * Callchain of attribute write event handlers.
be_bryan 0:b74591d5ab33 131 *
be_bryan 0:b74591d5ab33 132 * @see GattClient::onDataWrite().
be_bryan 0:b74591d5ab33 133 */
be_bryan 0:b74591d5ab33 134 typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*>
be_bryan 0:b74591d5ab33 135 WriteCallbackChain_t;
be_bryan 0:b74591d5ab33 136
be_bryan 0:b74591d5ab33 137 /**
be_bryan 0:b74591d5ab33 138 * Handle value notification/indication event handler.
be_bryan 0:b74591d5ab33 139 *
be_bryan 0:b74591d5ab33 140 * @see to GattClient::onHVX().
be_bryan 0:b74591d5ab33 141 */
be_bryan 0:b74591d5ab33 142 typedef FunctionPointerWithContext<const GattHVXCallbackParams*>
be_bryan 0:b74591d5ab33 143 HVXCallback_t;
be_bryan 0:b74591d5ab33 144
be_bryan 0:b74591d5ab33 145 /**
be_bryan 0:b74591d5ab33 146 * Callchain of handle value notification/indication event handlers.
be_bryan 0:b74591d5ab33 147 *
be_bryan 0:b74591d5ab33 148 * @see GattClient::onHVX().
be_bryan 0:b74591d5ab33 149 */
be_bryan 0:b74591d5ab33 150 typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*>
be_bryan 0:b74591d5ab33 151 HVXCallbackChain_t;
be_bryan 0:b74591d5ab33 152
be_bryan 0:b74591d5ab33 153 /**
be_bryan 0:b74591d5ab33 154 * Shutdown event handler.
be_bryan 0:b74591d5ab33 155 *
be_bryan 0:b74591d5ab33 156 * @see GattClient::onShutdown().
be_bryan 0:b74591d5ab33 157 */
be_bryan 0:b74591d5ab33 158 typedef FunctionPointerWithContext<const GattClient *>
be_bryan 0:b74591d5ab33 159 GattClientShutdownCallback_t;
be_bryan 0:b74591d5ab33 160
be_bryan 0:b74591d5ab33 161
be_bryan 0:b74591d5ab33 162 /**
be_bryan 0:b74591d5ab33 163 * Callchain of shutdown event handlers.
be_bryan 0:b74591d5ab33 164 *
be_bryan 0:b74591d5ab33 165 * @see to GattClient::onShutown().
be_bryan 0:b74591d5ab33 166 */
be_bryan 0:b74591d5ab33 167 typedef CallChainOfFunctionPointersWithContext<const GattClient *>
be_bryan 0:b74591d5ab33 168 GattClientShutdownCallbackChain_t;
be_bryan 0:b74591d5ab33 169
be_bryan 0:b74591d5ab33 170 /*
be_bryan 0:b74591d5ab33 171 * The following functions are meant to be overridden in the platform
be_bryan 0:b74591d5ab33 172 * specific subclass.
be_bryan 0:b74591d5ab33 173 */
be_bryan 0:b74591d5ab33 174 public:
be_bryan 0:b74591d5ab33 175
be_bryan 0:b74591d5ab33 176 virtual ~GattClient() { }
be_bryan 0:b74591d5ab33 177
be_bryan 0:b74591d5ab33 178 /**
be_bryan 0:b74591d5ab33 179 * Launch the service and characteristic discovery procedure of a GATT server
be_bryan 0:b74591d5ab33 180 * peer.
be_bryan 0:b74591d5ab33 181 *
be_bryan 0:b74591d5ab33 182 * The procedure invokes application callbacks for matching services or
be_bryan 0:b74591d5ab33 183 * characteristics. The process ends after all the services and
be_bryan 0:b74591d5ab33 184 * characteristics present on the distant GATT server have been discovered.
be_bryan 0:b74591d5ab33 185 * Termination callbacks registered with onServiceDiscoveryTermination() are
be_bryan 0:b74591d5ab33 186 * invoked to notify the application of the termination of the procedure.
be_bryan 0:b74591d5ab33 187 *
be_bryan 0:b74591d5ab33 188 * Application code can track the status of the procedure by invoking the
be_bryan 0:b74591d5ab33 189 * function isServiceDiscoveryActive(), which returns true if the
be_bryan 0:b74591d5ab33 190 * procedure is ongoing.
be_bryan 0:b74591d5ab33 191 *
be_bryan 0:b74591d5ab33 192 * At any point, application code can prematurely terminate the discovery
be_bryan 0:b74591d5ab33 193 * procedure by calling terminateServiceDiscovery().
be_bryan 0:b74591d5ab33 194 *
be_bryan 0:b74591d5ab33 195 * @param[in] connectionHandle Handle of the connection with the peer GATT
be_bryan 0:b74591d5ab33 196 * server.
be_bryan 0:b74591d5ab33 197 * @param[in] sc Service discovered event handler invoked when a matching
be_bryan 0:b74591d5ab33 198 * service has been discovered. This parameter may be NULL.
be_bryan 0:b74591d5ab33 199 * @param[in] cc Characteristic discovered event handler invoked when a
be_bryan 0:b74591d5ab33 200 * matching characteristic has been found. This parameter may be NULL.
be_bryan 0:b74591d5ab33 201 * @param[in] matchingServiceUUID UUID of the service the caller is
be_bryan 0:b74591d5ab33 202 * interested in. If a service discovered matches this filter, then @p sc is
be_bryan 0:b74591d5ab33 203 * invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard,
be_bryan 0:b74591d5ab33 204 * which can be used to discover all services present on the peer GATT
be_bryan 0:b74591d5ab33 205 * server.
be_bryan 0:b74591d5ab33 206 * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the
be_bryan 0:b74591d5ab33 207 * caller is interested in. If a characteristic discovered matches this
be_bryan 0:b74591d5ab33 208 * filter, then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN
be_bryan 0:b74591d5ab33 209 * acts as a wildcard, which can be used to discover all services present on
be_bryan 0:b74591d5ab33 210 * the peer GATT server.
be_bryan 0:b74591d5ab33 211 *
be_bryan 0:b74591d5ab33 212 * @par Discovery procedure implementation detail
be_bryan 0:b74591d5ab33 213 *
be_bryan 0:b74591d5ab33 214 * It is recommended to implement several strategies based on the
be_bryan 0:b74591d5ab33 215 * combination of callbacks and filters passed in input to efficiently
be_bryan 0:b74591d5ab33 216 * realize the discovery procedure:
be_bryan 0:b74591d5ab33 217 * - If @p sc and @p cc are NULL, then it is not necessay to initiate any
be_bryan 0:b74591d5ab33 218 * discovery, and the termination handlers can be invoked immediately.
be_bryan 0:b74591d5ab33 219 * - If @p matchingServiceUUID is set, then the GATT discover services by
be_bryan 0:b74591d5ab33 220 * service UUID procedure should be used; otherwise, the GATT discover primary
be_bryan 0:b74591d5ab33 221 * services procedure should be used.
be_bryan 0:b74591d5ab33 222 * - If @p cc is NULL, then the discovery process should end after the discovery
be_bryan 0:b74591d5ab33 223 * of the services.
be_bryan 0:b74591d5ab33 224 *
be_bryan 0:b74591d5ab33 225 * @return BLE_ERROR_NONE if the discovery procedure has been successfully
be_bryan 0:b74591d5ab33 226 * started and an appropriate error otherwise.
be_bryan 0:b74591d5ab33 227 */
be_bryan 0:b74591d5ab33 228 virtual ble_error_t launchServiceDiscovery(
be_bryan 0:b74591d5ab33 229 Gap::Handle_t connectionHandle,
be_bryan 0:b74591d5ab33 230 ServiceDiscovery::ServiceCallback_t sc = NULL,
be_bryan 0:b74591d5ab33 231 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
be_bryan 0:b74591d5ab33 232 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
be_bryan 0:b74591d5ab33 233 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)
be_bryan 0:b74591d5ab33 234 ) {
be_bryan 0:b74591d5ab33 235 /* Avoid compiler warnings about unused variables. */
be_bryan 0:b74591d5ab33 236 (void)connectionHandle;
be_bryan 0:b74591d5ab33 237 (void)sc;
be_bryan 0:b74591d5ab33 238 (void)cc;
be_bryan 0:b74591d5ab33 239 (void)matchingServiceUUID;
be_bryan 0:b74591d5ab33 240 (void)matchingCharacteristicUUIDIn;
be_bryan 0:b74591d5ab33 241
be_bryan 0:b74591d5ab33 242 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 243 is supported. */
be_bryan 0:b74591d5ab33 244 return BLE_ERROR_NOT_IMPLEMENTED;
be_bryan 0:b74591d5ab33 245 }
be_bryan 0:b74591d5ab33 246
be_bryan 0:b74591d5ab33 247 /**
be_bryan 0:b74591d5ab33 248 * Launch the service discovery procedure of a GATT server peer.
be_bryan 0:b74591d5ab33 249 *
be_bryan 0:b74591d5ab33 250 * The procedure invokes the application callback for matching services.
be_bryan 0:b74591d5ab33 251 * The process ends after all the services present on the distant GATT
be_bryan 0:b74591d5ab33 252 * server have been discovered.
be_bryan 0:b74591d5ab33 253 * Termination callbacks registered with onServiceDiscoveryTermination() are
be_bryan 0:b74591d5ab33 254 * invoked to notify the application of the termination of the procedure.
be_bryan 0:b74591d5ab33 255 *
be_bryan 0:b74591d5ab33 256 * Application code can track the status of the procedure by invoking the
be_bryan 0:b74591d5ab33 257 * function isServiceDiscoveryActive(), which returns true if the
be_bryan 0:b74591d5ab33 258 * procedure is ongoing.
be_bryan 0:b74591d5ab33 259 *
be_bryan 0:b74591d5ab33 260 * At any point, application code can prematurely terminate the discovery
be_bryan 0:b74591d5ab33 261 * procedure by calling terminateServiceDiscovery().
be_bryan 0:b74591d5ab33 262 *
be_bryan 0:b74591d5ab33 263 * @param[in] connectionHandle Handle of the connection with the peer GATT
be_bryan 0:b74591d5ab33 264 * server.
be_bryan 0:b74591d5ab33 265 * @param[in] callback Service discovered event handler invoked when a
be_bryan 0:b74591d5ab33 266 * matching service has been discovered. This parameter may be NULL.
be_bryan 0:b74591d5ab33 267 * @param[in] matchingServiceUUID UUID of the service the caller is
be_bryan 0:b74591d5ab33 268 * interested in. If a service discovered matches this filter, then @p sc is
be_bryan 0:b74591d5ab33 269 * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard,
be_bryan 0:b74591d5ab33 270 * which can be used to discover all services present on the peer GATT
be_bryan 0:b74591d5ab33 271 * server.
be_bryan 0:b74591d5ab33 272 *
be_bryan 0:b74591d5ab33 273 * @return BLE_ERROR_NONE if the discovery procedure has been successfully
be_bryan 0:b74591d5ab33 274 * started and an appropriate error otherwise.
be_bryan 0:b74591d5ab33 275 */
be_bryan 0:b74591d5ab33 276 virtual ble_error_t discoverServices(
be_bryan 0:b74591d5ab33 277 Gap::Handle_t connectionHandle,
be_bryan 0:b74591d5ab33 278 ServiceDiscovery::ServiceCallback_t callback,
be_bryan 0:b74591d5ab33 279 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)
be_bryan 0:b74591d5ab33 280 ) {
be_bryan 0:b74591d5ab33 281 /* We take advantage of the property
be_bryan 0:b74591d5ab33 282 * that providing NULL for the characteristic callback results in
be_bryan 0:b74591d5ab33 283 * characteristic discovery being skipped for each matching
be_bryan 0:b74591d5ab33 284 * service. This allows for an inexpensive method to discover only
be_bryan 0:b74591d5ab33 285 * services. Porters are free to override this. */
be_bryan 0:b74591d5ab33 286 return launchServiceDiscovery(
be_bryan 0:b74591d5ab33 287 connectionHandle, callback, NULL, matchingServiceUUID
be_bryan 0:b74591d5ab33 288 );
be_bryan 0:b74591d5ab33 289 }
be_bryan 0:b74591d5ab33 290
be_bryan 0:b74591d5ab33 291 /**
be_bryan 0:b74591d5ab33 292 * Launch the service discovery procedure of a GATT server peer.
be_bryan 0:b74591d5ab33 293 *
be_bryan 0:b74591d5ab33 294 * The process ends after all the services present in the attribute range @p
be_bryan 0:b74591d5ab33 295 * startHandle to @p endHandle have been discovered.
be_bryan 0:b74591d5ab33 296 *
be_bryan 0:b74591d5ab33 297 * Termination callbacks registered with onServiceDiscoveryTermination() are
be_bryan 0:b74591d5ab33 298 * invoked to notify the application of the termination of the procedure.
be_bryan 0:b74591d5ab33 299 *
be_bryan 0:b74591d5ab33 300 * Application code can track the status of the procedure by invoking the
be_bryan 0:b74591d5ab33 301 * function isServiceDiscoveryActive(), which returns true if the
be_bryan 0:b74591d5ab33 302 * procedure is ongoing.
be_bryan 0:b74591d5ab33 303 *
be_bryan 0:b74591d5ab33 304 * At any point, application code can prematurely terminate the discovery
be_bryan 0:b74591d5ab33 305 * procedure by calling terminateServiceDiscovery().
be_bryan 0:b74591d5ab33 306 *
be_bryan 0:b74591d5ab33 307 * @param[in] connectionHandle Handle of the connection with the peer GATT
be_bryan 0:b74591d5ab33 308 * server.
be_bryan 0:b74591d5ab33 309 * @param[in] callback Service discovered event handler invoked when a
be_bryan 0:b74591d5ab33 310 * matching service has been discovered. This parameter may be NULL.
be_bryan 0:b74591d5ab33 311 * @param[in] startHandle First attribute handle of the discovery range.
be_bryan 0:b74591d5ab33 312 * @param[in] endHandle end Lasr attribute handle of the discovery range.
be_bryan 0:b74591d5ab33 313 *
be_bryan 0:b74591d5ab33 314 * @return BLE_ERROR_NONE if the discovery procedure has been successfully
be_bryan 0:b74591d5ab33 315 * started and an appropriate error otherwise.
be_bryan 0:b74591d5ab33 316 */
be_bryan 0:b74591d5ab33 317 virtual ble_error_t discoverServices(
be_bryan 0:b74591d5ab33 318 Gap::Handle_t connectionHandle,
be_bryan 0:b74591d5ab33 319 ServiceDiscovery::ServiceCallback_t callback,
be_bryan 0:b74591d5ab33 320 GattAttribute::Handle_t startHandle,
be_bryan 0:b74591d5ab33 321 GattAttribute::Handle_t endHandle
be_bryan 0:b74591d5ab33 322 ) {
be_bryan 0:b74591d5ab33 323 /* Avoid compiler warnings about unused variables. */
be_bryan 0:b74591d5ab33 324 (void)connectionHandle;
be_bryan 0:b74591d5ab33 325 (void)callback;
be_bryan 0:b74591d5ab33 326 (void)startHandle;
be_bryan 0:b74591d5ab33 327 (void)endHandle;
be_bryan 0:b74591d5ab33 328
be_bryan 0:b74591d5ab33 329 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 330 is supported. */
be_bryan 0:b74591d5ab33 331 return BLE_ERROR_NOT_IMPLEMENTED;
be_bryan 0:b74591d5ab33 332 }
be_bryan 0:b74591d5ab33 333
be_bryan 0:b74591d5ab33 334 /**
be_bryan 0:b74591d5ab33 335 * Check if the service discovery procedure is currently active.
be_bryan 0:b74591d5ab33 336 *
be_bryan 0:b74591d5ab33 337 * @return true if service discovery procedure is active and false otherwise.
be_bryan 0:b74591d5ab33 338 */
be_bryan 0:b74591d5ab33 339 virtual bool isServiceDiscoveryActive(void) const
be_bryan 0:b74591d5ab33 340 {
be_bryan 0:b74591d5ab33 341 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 342 is supported. */
be_bryan 0:b74591d5ab33 343 return false;
be_bryan 0:b74591d5ab33 344 }
be_bryan 0:b74591d5ab33 345
be_bryan 0:b74591d5ab33 346 /**
be_bryan 0:b74591d5ab33 347 * Terminate all ongoing service discovery procedures.
be_bryan 0:b74591d5ab33 348 *
be_bryan 0:b74591d5ab33 349 * It results in an invocation of the service discovery termination handler
be_bryan 0:b74591d5ab33 350 * registered with onServiceDiscoveryTermination().
be_bryan 0:b74591d5ab33 351 */
be_bryan 0:b74591d5ab33 352 virtual void terminateServiceDiscovery(void)
be_bryan 0:b74591d5ab33 353 {
be_bryan 0:b74591d5ab33 354 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 355 is supported. */
be_bryan 0:b74591d5ab33 356 }
be_bryan 0:b74591d5ab33 357
be_bryan 0:b74591d5ab33 358 /**
be_bryan 0:b74591d5ab33 359 * Initiate the read procedure of an attribute handle.
be_bryan 0:b74591d5ab33 360 *
be_bryan 0:b74591d5ab33 361 * Once the attribute value has been read in its entirety, the process issues
be_bryan 0:b74591d5ab33 362 * an attribute read event and passes it to all events handlers registered
be_bryan 0:b74591d5ab33 363 * by onDataRead.
be_bryan 0:b74591d5ab33 364 *
be_bryan 0:b74591d5ab33 365 * @param[in] connHandle Handle of the connection used to send the read
be_bryan 0:b74591d5ab33 366 * request.
be_bryan 0:b74591d5ab33 367 * @param[in] attributeHandle Handle of the attribute to read data from.
be_bryan 0:b74591d5ab33 368 * @param[in] offset The offset from the start of the attribute value to be
be_bryan 0:b74591d5ab33 369 * read.
be_bryan 0:b74591d5ab33 370 *
be_bryan 0:b74591d5ab33 371 * @return BLE_ERROR_NONE if read procedure successfully started.
be_bryan 0:b74591d5ab33 372 *
be_bryan 0:b74591d5ab33 373 * @par Implementation notes:
be_bryan 0:b74591d5ab33 374 *
be_bryan 0:b74591d5ab33 375 * Reading the attribute value in its entirety may involve sending several
be_bryan 0:b74591d5ab33 376 * GATT requests to the peer. The following algorithm may be used to
be_bryan 0:b74591d5ab33 377 * implement the process:
be_bryan 0:b74591d5ab33 378 *
be_bryan 0:b74591d5ab33 379 * If the offset is equal to 0, then send a read request; otherwise, send a
be_bryan 0:b74591d5ab33 380 * read blob request at the specified offset.
be_bryan 0:b74591d5ab33 381 *
be_bryan 0:b74591d5ab33 382 * While the attribute data in the response are MTU - 1 long:
be_bryan 0:b74591d5ab33 383 * - Concat the response to the value containing the previous responses.
be_bryan 0:b74591d5ab33 384 * - Increment the value of the offset by MTU - 1.
be_bryan 0:b74591d5ab33 385 * - Send a read blob request with the updated offset.
be_bryan 0:b74591d5ab33 386 *
be_bryan 0:b74591d5ab33 387 * Finally, concat the last response with the value containing all the
be_bryan 0:b74591d5ab33 388 * previous responses and forward that value to the event handlers.
be_bryan 0:b74591d5ab33 389 */
be_bryan 0:b74591d5ab33 390 virtual ble_error_t read(
be_bryan 0:b74591d5ab33 391 Gap::Handle_t connHandle,
be_bryan 0:b74591d5ab33 392 GattAttribute::Handle_t attributeHandle,
be_bryan 0:b74591d5ab33 393 uint16_t offset
be_bryan 0:b74591d5ab33 394 ) const {
be_bryan 0:b74591d5ab33 395 /* Avoid compiler warnings about unused variables. */
be_bryan 0:b74591d5ab33 396 (void)connHandle;
be_bryan 0:b74591d5ab33 397 (void)attributeHandle;
be_bryan 0:b74591d5ab33 398 (void)offset;
be_bryan 0:b74591d5ab33 399
be_bryan 0:b74591d5ab33 400 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 401 is supported. */
be_bryan 0:b74591d5ab33 402 return BLE_ERROR_NOT_IMPLEMENTED;
be_bryan 0:b74591d5ab33 403 }
be_bryan 0:b74591d5ab33 404
be_bryan 0:b74591d5ab33 405 /**
be_bryan 0:b74591d5ab33 406 * Initiate a write procedure on an attribute value.
be_bryan 0:b74591d5ab33 407 *
be_bryan 0:b74591d5ab33 408 * If @p cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation
be_bryan 0:b74591d5ab33 409 * is reported to the event handlers registered through onDataWritten().
be_bryan 0:b74591d5ab33 410 *
be_bryan 0:b74591d5ab33 411 * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD
be_bryan 0:b74591d5ab33 412 * is set, then value length is not greater than the size of the mtu
be_bryan 0:b74591d5ab33 413 * of connHandle minus three.
be_bryan 0:b74591d5ab33 414 * @param[in] connHandle Handle of the connection used to send the write
be_bryan 0:b74591d5ab33 415 * request or command.
be_bryan 0:b74591d5ab33 416 * @param[in] attributeHandle Handle of the attribute value to write.
be_bryan 0:b74591d5ab33 417 * @param[in] length Number of bytes present in @p value.
be_bryan 0:b74591d5ab33 418 * @param[in] value Data buffer to write to attributeHandle.
be_bryan 0:b74591d5ab33 419 *
be_bryan 0:b74591d5ab33 420 * @return BLE_ERROR_NONE if the write procedure successfully started.
be_bryan 0:b74591d5ab33 421 *
be_bryan 0:b74591d5ab33 422 * @par Implementation notes:
be_bryan 0:b74591d5ab33 423 *
be_bryan 0:b74591d5ab33 424 * If the operation is a write command, then an implementation uses the
be_bryan 0:b74591d5ab33 425 * GATT write without response procedure and an error is returned if
be_bryan 0:b74591d5ab33 426 * the data buffer to write is larger than the size of the MTU - 3.
be_bryan 0:b74591d5ab33 427 *
be_bryan 0:b74591d5ab33 428 * If the operation is a write command and the size of the data buffer to
be_bryan 0:b74591d5ab33 429 * write is less than than the size of the MTU - 3, then the ATT write request
be_bryan 0:b74591d5ab33 430 * procedure is used, and the response is reported to the handlers
be_bryan 0:b74591d5ab33 431 * listening for write response.
be_bryan 0:b74591d5ab33 432 *
be_bryan 0:b74591d5ab33 433 * Otherwise, the data buffer to write is divided in chunks with a
be_bryan 0:b74591d5ab33 434 * maximum size of MTU - 5. Those chunks are sent sequentially to the
be_bryan 0:b74591d5ab33 435 * peer in ATT prepare write requests. If an error response is received
be_bryan 0:b74591d5ab33 436 * during the process, the procedure ends immediately, the prepared
be_bryan 0:b74591d5ab33 437 * write is discarded and an error is reported to the application handlers.
be_bryan 0:b74591d5ab33 438 * Once all the chunks have been sent, the transaction is completed
be_bryan 0:b74591d5ab33 439 * by sending an execute write request to the peer. The peer response is
be_bryan 0:b74591d5ab33 440 * forwarded to the application handlers.
be_bryan 0:b74591d5ab33 441 */
be_bryan 0:b74591d5ab33 442 virtual ble_error_t write(
be_bryan 0:b74591d5ab33 443 GattClient::WriteOp_t cmd,
be_bryan 0:b74591d5ab33 444 Gap::Handle_t connHandle,
be_bryan 0:b74591d5ab33 445 GattAttribute::Handle_t attributeHandle,
be_bryan 0:b74591d5ab33 446 size_t length,
be_bryan 0:b74591d5ab33 447 const uint8_t *value
be_bryan 0:b74591d5ab33 448 ) const {
be_bryan 0:b74591d5ab33 449 /* Avoid compiler warnings about unused variables. */
be_bryan 0:b74591d5ab33 450 (void)cmd;
be_bryan 0:b74591d5ab33 451 (void)connHandle;
be_bryan 0:b74591d5ab33 452 (void)attributeHandle;
be_bryan 0:b74591d5ab33 453 (void)length;
be_bryan 0:b74591d5ab33 454 (void)value;
be_bryan 0:b74591d5ab33 455
be_bryan 0:b74591d5ab33 456 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 457 is supported. */
be_bryan 0:b74591d5ab33 458 return BLE_ERROR_NOT_IMPLEMENTED;
be_bryan 0:b74591d5ab33 459 }
be_bryan 0:b74591d5ab33 460
be_bryan 0:b74591d5ab33 461 /* Event callback handlers. */
be_bryan 0:b74591d5ab33 462 public:
be_bryan 0:b74591d5ab33 463
be_bryan 0:b74591d5ab33 464 /**
be_bryan 0:b74591d5ab33 465 * Register an attribute read event handler.
be_bryan 0:b74591d5ab33 466 *
be_bryan 0:b74591d5ab33 467 * @note It is possible to unregister a callback using
be_bryan 0:b74591d5ab33 468 * onDataRead().detach(callbackToRemove).
be_bryan 0:b74591d5ab33 469 *
be_bryan 0:b74591d5ab33 470 * @param[in] callback Event handler being registered.
be_bryan 0:b74591d5ab33 471 */
be_bryan 0:b74591d5ab33 472 void onDataRead(ReadCallback_t callback)
be_bryan 0:b74591d5ab33 473 {
be_bryan 0:b74591d5ab33 474 onDataReadCallbackChain.add(callback);
be_bryan 0:b74591d5ab33 475 }
be_bryan 0:b74591d5ab33 476
be_bryan 0:b74591d5ab33 477 /**
be_bryan 0:b74591d5ab33 478 * Get the callchain of attribute read event handlers.
be_bryan 0:b74591d5ab33 479 *
be_bryan 0:b74591d5ab33 480 * @return A reference to the read event callback chain.
be_bryan 0:b74591d5ab33 481 *
be_bryan 0:b74591d5ab33 482 * @note It is possible to register new handlers using
be_bryan 0:b74591d5ab33 483 * onDataRead().add(callback).
be_bryan 0:b74591d5ab33 484 *
be_bryan 0:b74591d5ab33 485 * @note It is possible to unregister an handler by using
be_bryan 0:b74591d5ab33 486 * onDataRead().detach(callback).
be_bryan 0:b74591d5ab33 487 */
be_bryan 0:b74591d5ab33 488 ReadCallbackChain_t& onDataRead()
be_bryan 0:b74591d5ab33 489 {
be_bryan 0:b74591d5ab33 490 return onDataReadCallbackChain;
be_bryan 0:b74591d5ab33 491 }
be_bryan 0:b74591d5ab33 492
be_bryan 0:b74591d5ab33 493 /**
be_bryan 0:b74591d5ab33 494 * Register an attribute write event handler.
be_bryan 0:b74591d5ab33 495 *
be_bryan 0:b74591d5ab33 496 * @param[in] callback Event handler being registered.
be_bryan 0:b74591d5ab33 497 *
be_bryan 0:b74591d5ab33 498 * @note It is possible to remove registered handlers using
be_bryan 0:b74591d5ab33 499 * onDataWritten().detach(callbackToRemove).
be_bryan 0:b74591d5ab33 500 *
be_bryan 0:b74591d5ab33 501 * @note Write commands (issued using writeWoResponse) don't generate a
be_bryan 0:b74591d5ab33 502 * response.
be_bryan 0:b74591d5ab33 503 */
be_bryan 0:b74591d5ab33 504 void onDataWritten(WriteCallback_t callback)
be_bryan 0:b74591d5ab33 505 {
be_bryan 0:b74591d5ab33 506 onDataWriteCallbackChain.add(callback);
be_bryan 0:b74591d5ab33 507 }
be_bryan 0:b74591d5ab33 508
be_bryan 0:b74591d5ab33 509 /**
be_bryan 0:b74591d5ab33 510 * Get the callchain of attribute write event handlers.
be_bryan 0:b74591d5ab33 511 *
be_bryan 0:b74591d5ab33 512 * @return A reference to the data written callbacks chain.
be_bryan 0:b74591d5ab33 513 *
be_bryan 0:b74591d5ab33 514 * @note It is possible to register new handlers by using
be_bryan 0:b74591d5ab33 515 * onDataWritten().add(callback).
be_bryan 0:b74591d5ab33 516 *
be_bryan 0:b74591d5ab33 517 * @note It is possible to unregister an handler by using
be_bryan 0:b74591d5ab33 518 * onDataWritten().detach(callback).
be_bryan 0:b74591d5ab33 519 */
be_bryan 0:b74591d5ab33 520 WriteCallbackChain_t& onDataWritten()
be_bryan 0:b74591d5ab33 521 {
be_bryan 0:b74591d5ab33 522 return onDataWriteCallbackChain;
be_bryan 0:b74591d5ab33 523 }
be_bryan 0:b74591d5ab33 524
be_bryan 0:b74591d5ab33 525 /**
be_bryan 0:b74591d5ab33 526 * Register an attribute write event handler.
be_bryan 0:b74591d5ab33 527 *
be_bryan 0:b74591d5ab33 528 * @param[in] callback Event handler being registered.
be_bryan 0:b74591d5ab33 529 *
be_bryan 0:b74591d5ab33 530 * @note It is possible to remove registered handlers using
be_bryan 0:b74591d5ab33 531 * onDataWritten().detach(callbackToRemove).
be_bryan 0:b74591d5ab33 532 *
be_bryan 0:b74591d5ab33 533 * @note Write commands (issued using writeWoResponse) don't generate a
be_bryan 0:b74591d5ab33 534 * response.
be_bryan 0:b74591d5ab33 535 *
be_bryan 0:b74591d5ab33 536 * @deprecated Use GattServer::onDataWritten().
be_bryan 0:b74591d5ab33 537 */
be_bryan 0:b74591d5ab33 538 MBED_DEPRECATED("Use GattServer::onDataWritten()")
be_bryan 0:b74591d5ab33 539 void onDataWrite(WriteCallback_t callback)
be_bryan 0:b74591d5ab33 540 {
be_bryan 0:b74591d5ab33 541 onDataWritten(callback);
be_bryan 0:b74591d5ab33 542 }
be_bryan 0:b74591d5ab33 543
be_bryan 0:b74591d5ab33 544 /**
be_bryan 0:b74591d5ab33 545 * Register a service discovery termination event handler.
be_bryan 0:b74591d5ab33 546 *
be_bryan 0:b74591d5ab33 547 * @param[in] callback Event handler being registered.
be_bryan 0:b74591d5ab33 548 */
be_bryan 0:b74591d5ab33 549 virtual void onServiceDiscoveryTermination(
be_bryan 0:b74591d5ab33 550 ServiceDiscovery::TerminationCallback_t callback
be_bryan 0:b74591d5ab33 551 ) {
be_bryan 0:b74591d5ab33 552 (void)callback; /* Avoid compiler warnings about ununsed variables. */
be_bryan 0:b74591d5ab33 553
be_bryan 0:b74591d5ab33 554 /* Requesting action from porters: override this API if this capability
be_bryan 0:b74591d5ab33 555 is supported. */
be_bryan 0:b74591d5ab33 556 }
be_bryan 0:b74591d5ab33 557
be_bryan 0:b74591d5ab33 558 /**
be_bryan 0:b74591d5ab33 559 * Initiate the descriptor discovery procedure for a given characteristic.
be_bryan 0:b74591d5ab33 560 *
be_bryan 0:b74591d5ab33 561 * When a descriptor is discovered the discovered descriptor is forwarded
be_bryan 0:b74591d5ab33 562 * to @p discoveryCallback. After the discovery of all the descriptors, the
be_bryan 0:b74591d5ab33 563 * procedure ends and send a descriptor discovery termination event to @p
be_bryan 0:b74591d5ab33 564 * termination callback.
be_bryan 0:b74591d5ab33 565 *
be_bryan 0:b74591d5ab33 566 * Application code may monitor the discovery process by querying its status
be_bryan 0:b74591d5ab33 567 * with isCharacteristicDescriptorDiscoveryActive(). It can also end the
be_bryan 0:b74591d5ab33 568 * discovery process by calling terminateCharacteristicDescriptorDiscovery().
be_bryan 0:b74591d5ab33 569 *
be_bryan 0:b74591d5ab33 570 * @param[in] characteristic The characteristic owning the descriptors to
be_bryan 0:b74591d5ab33 571 * discover.
be_bryan 0:b74591d5ab33 572 * @param[in] discoveryCallback Handle descriptor discovered events for the
be_bryan 0:b74591d5ab33 573 * duration of the procedure.
be_bryan 0:b74591d5ab33 574 * @param[in] terminationCallback Handle descriptor discovery termination
be_bryan 0:b74591d5ab33 575 * event of the procedure.
be_bryan 0:b74591d5ab33 576 *
be_bryan 0:b74591d5ab33 577 * @return BLE_ERROR_NONE if the characteristic descriptor discovery
be_bryan 0:b74591d5ab33 578 * procedure has been launched successfully otherwise an appropriate error.
be_bryan 0:b74591d5ab33 579 */
be_bryan 0:b74591d5ab33 580 virtual ble_error_t discoverCharacteristicDescriptors(
be_bryan 0:b74591d5ab33 581 const DiscoveredCharacteristic& characteristic,
be_bryan 0:b74591d5ab33 582 const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback,
be_bryan 0:b74591d5ab33 583 const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback
be_bryan 0:b74591d5ab33 584 ) {
be_bryan 0:b74591d5ab33 585 (void) characteristic;
be_bryan 0:b74591d5ab33 586 (void) discoveryCallback;
be_bryan 0:b74591d5ab33 587 (void) terminationCallback;
be_bryan 0:b74591d5ab33 588 /* Requesting action from porter(s): override this API if this
be_bryan 0:b74591d5ab33 589 capability is supported. */
be_bryan 0:b74591d5ab33 590 return BLE_ERROR_NOT_IMPLEMENTED;
be_bryan 0:b74591d5ab33 591 }
be_bryan 0:b74591d5ab33 592
be_bryan 0:b74591d5ab33 593 /**
be_bryan 0:b74591d5ab33 594 * Query status of the descriptor discovery procedure for a given
be_bryan 0:b74591d5ab33 595 * characteristic.
be_bryan 0:b74591d5ab33 596 *
be_bryan 0:b74591d5ab33 597 * @param[in] characteristic The characteristic concerned by the descriptors
be_bryan 0:b74591d5ab33 598 * discovery.
be_bryan 0:b74591d5ab33 599 *
be_bryan 0:b74591d5ab33 600 * @return true if a descriptors discovery is active for the characteristic
be_bryan 0:b74591d5ab33 601 * in input otherwise false.
be_bryan 0:b74591d5ab33 602 */
be_bryan 0:b74591d5ab33 603 virtual bool isCharacteristicDescriptorDiscoveryActive(
be_bryan 0:b74591d5ab33 604 const DiscoveredCharacteristic& characteristic
be_bryan 0:b74591d5ab33 605 ) const {
be_bryan 0:b74591d5ab33 606 (void) characteristic;
be_bryan 0:b74591d5ab33 607 /* Requesting action from porter(s): override this API if this
be_bryan 0:b74591d5ab33 608 capability is supported. */
be_bryan 0:b74591d5ab33 609 return false;
be_bryan 0:b74591d5ab33 610 }
be_bryan 0:b74591d5ab33 611
be_bryan 0:b74591d5ab33 612 /**
be_bryan 0:b74591d5ab33 613 * @brief Terminate an ongoing characteristic descriptor discovery procedure.
be_bryan 0:b74591d5ab33 614 *
be_bryan 0:b74591d5ab33 615 * If the procedure is active, then it ends, and the termination handler
be_bryan 0:b74591d5ab33 616 * associated with the procedure is called.
be_bryan 0:b74591d5ab33 617 *
be_bryan 0:b74591d5ab33 618 * @param[in] characteristic The characteristic containing the descriptors
be_bryan 0:b74591d5ab33 619 * being discovered.
be_bryan 0:b74591d5ab33 620 */
be_bryan 0:b74591d5ab33 621 virtual void terminateCharacteristicDescriptorDiscovery(
be_bryan 0:b74591d5ab33 622 const DiscoveredCharacteristic& characteristic
be_bryan 0:b74591d5ab33 623 ) {
be_bryan 0:b74591d5ab33 624 /* Requesting action from porter(s): override this API if this
be_bryan 0:b74591d5ab33 625 capability is supported. */
be_bryan 0:b74591d5ab33 626 (void) characteristic;
be_bryan 0:b74591d5ab33 627 }
be_bryan 0:b74591d5ab33 628
be_bryan 0:b74591d5ab33 629 /**
be_bryan 0:b74591d5ab33 630 * Register an handler for Handle Value Notification/Indication events.
be_bryan 0:b74591d5ab33 631 *
be_bryan 0:b74591d5ab33 632 * @param callback Event handler to register.
be_bryan 0:b74591d5ab33 633 *
be_bryan 0:b74591d5ab33 634 * @note It is possible to unregister a callback by using
be_bryan 0:b74591d5ab33 635 * onHVX().detach(callbackToRemove).
be_bryan 0:b74591d5ab33 636 */
be_bryan 0:b74591d5ab33 637 void onHVX(HVXCallback_t callback)
be_bryan 0:b74591d5ab33 638 {
be_bryan 0:b74591d5ab33 639 onHVXCallbackChain.add(callback);
be_bryan 0:b74591d5ab33 640 }
be_bryan 0:b74591d5ab33 641
be_bryan 0:b74591d5ab33 642 /**
be_bryan 0:b74591d5ab33 643 * Register a shutdown event handler.
be_bryan 0:b74591d5ab33 644 *
be_bryan 0:b74591d5ab33 645 * The registered handler is invoked when the GattClient instance is
be_bryan 0:b74591d5ab33 646 * about to be shut down.
be_bryan 0:b74591d5ab33 647 *
be_bryan 0:b74591d5ab33 648 * @param[in] callback Event handler to invoke when a shutdown event is
be_bryan 0:b74591d5ab33 649 * available.
be_bryan 0:b74591d5ab33 650 *
be_bryan 0:b74591d5ab33 651 * @note onShutdown().detach(callback) may be used to unregister a given
be_bryan 0:b74591d5ab33 652 * callback.
be_bryan 0:b74591d5ab33 653 *
be_bryan 0:b74591d5ab33 654 * @see BLE::shutdown()
be_bryan 0:b74591d5ab33 655 */
be_bryan 0:b74591d5ab33 656 void onShutdown(const GattClientShutdownCallback_t& callback)
be_bryan 0:b74591d5ab33 657 {
be_bryan 0:b74591d5ab33 658 shutdownCallChain.add(callback);
be_bryan 0:b74591d5ab33 659 }
be_bryan 0:b74591d5ab33 660
be_bryan 0:b74591d5ab33 661 /**
be_bryan 0:b74591d5ab33 662 * Register a shutdown event handler.
be_bryan 0:b74591d5ab33 663 *
be_bryan 0:b74591d5ab33 664 * The registered handler is invoked when the GattClient instance is
be_bryan 0:b74591d5ab33 665 * about to be shut down.
be_bryan 0:b74591d5ab33 666 *
be_bryan 0:b74591d5ab33 667 * @param[in] objPtr Instance that will be used to invoke @p memberPtr.
be_bryan 0:b74591d5ab33 668 * @param[in] memberPtr Event handler to invoke when a shutdown event is
be_bryan 0:b74591d5ab33 669 * available.
be_bryan 0:b74591d5ab33 670 */
be_bryan 0:b74591d5ab33 671 template <typename T>
be_bryan 0:b74591d5ab33 672 void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *))
be_bryan 0:b74591d5ab33 673 {
be_bryan 0:b74591d5ab33 674 shutdownCallChain.add(objPtr, memberPtr);
be_bryan 0:b74591d5ab33 675 }
be_bryan 0:b74591d5ab33 676
be_bryan 0:b74591d5ab33 677 /**
be_bryan 0:b74591d5ab33 678 * Get the callchain of shutdown event handlers.
be_bryan 0:b74591d5ab33 679 *
be_bryan 0:b74591d5ab33 680 * @return A reference to the shutdown event callbacks chain.
be_bryan 0:b74591d5ab33 681 *
be_bryan 0:b74591d5ab33 682 * @note onShutdown().add(callback) may be used to register new handlers.
be_bryan 0:b74591d5ab33 683 *
be_bryan 0:b74591d5ab33 684 * @note onShutdown().detach(callback) may be used to unregister an handler.
be_bryan 0:b74591d5ab33 685 */
be_bryan 0:b74591d5ab33 686 GattClientShutdownCallbackChain_t& onShutdown()
be_bryan 0:b74591d5ab33 687 {
be_bryan 0:b74591d5ab33 688 return shutdownCallChain;
be_bryan 0:b74591d5ab33 689 }
be_bryan 0:b74591d5ab33 690
be_bryan 0:b74591d5ab33 691 /**
be_bryan 0:b74591d5ab33 692 * @brief provide access to the callchain of HVX callbacks.
be_bryan 0:b74591d5ab33 693 *
be_bryan 0:b74591d5ab33 694 * @return A reference to the HVX callbacks chain.
be_bryan 0:b74591d5ab33 695 *
be_bryan 0:b74591d5ab33 696 * @note It is possible to register callbacks using onHVX().add(callback).
be_bryan 0:b74591d5ab33 697 *
be_bryan 0:b74591d5ab33 698 * @note It is possible to unregister callbacks using onHVX().detach(callback).
be_bryan 0:b74591d5ab33 699 */
be_bryan 0:b74591d5ab33 700 HVXCallbackChain_t& onHVX() {
be_bryan 0:b74591d5ab33 701 return onHVXCallbackChain;
be_bryan 0:b74591d5ab33 702 }
be_bryan 0:b74591d5ab33 703
be_bryan 0:b74591d5ab33 704 public:
be_bryan 0:b74591d5ab33 705 /**
be_bryan 0:b74591d5ab33 706 * Reset the state of the GattClient instance.
be_bryan 0:b74591d5ab33 707 *
be_bryan 0:b74591d5ab33 708 * Prior to any state modification, shutdown event handlers are notified
be_bryan 0:b74591d5ab33 709 * that the GattClient instance is about to be shut down. Then, running
be_bryan 0:b74591d5ab33 710 * procedures end. Finally, the state of the instance is reset.
be_bryan 0:b74591d5ab33 711 *
be_bryan 0:b74591d5ab33 712 * @par implementation note
be_bryan 0:b74591d5ab33 713 *
be_bryan 0:b74591d5ab33 714 * This function is meant to be overridden in the platform-specific
be_bryan 0:b74591d5ab33 715 * subclass. Nevertheless, the subclass only resets its
be_bryan 0:b74591d5ab33 716 * state and not the data held in GattClient members. This is achieved
be_bryan 0:b74591d5ab33 717 * by a call to GattClient::reset() from the subclass' reset()
be_bryan 0:b74591d5ab33 718 * implementation.
be_bryan 0:b74591d5ab33 719 *
be_bryan 0:b74591d5ab33 720 * @return BLE_ERROR_NONE on success.
be_bryan 0:b74591d5ab33 721 */
be_bryan 0:b74591d5ab33 722 virtual ble_error_t reset(void)
be_bryan 0:b74591d5ab33 723 {
be_bryan 0:b74591d5ab33 724 /* Notify that the instance is about to shut down. */
be_bryan 0:b74591d5ab33 725 shutdownCallChain.call(this);
be_bryan 0:b74591d5ab33 726 shutdownCallChain.clear();
be_bryan 0:b74591d5ab33 727
be_bryan 0:b74591d5ab33 728 onDataReadCallbackChain.clear();
be_bryan 0:b74591d5ab33 729 onDataWriteCallbackChain.clear();
be_bryan 0:b74591d5ab33 730 onHVXCallbackChain.clear();
be_bryan 0:b74591d5ab33 731
be_bryan 0:b74591d5ab33 732 return BLE_ERROR_NONE;
be_bryan 0:b74591d5ab33 733 }
be_bryan 0:b74591d5ab33 734
be_bryan 0:b74591d5ab33 735 protected:
be_bryan 0:b74591d5ab33 736 GattClient()
be_bryan 0:b74591d5ab33 737 {
be_bryan 0:b74591d5ab33 738 /* Empty */
be_bryan 0:b74591d5ab33 739 }
be_bryan 0:b74591d5ab33 740
be_bryan 0:b74591d5ab33 741 /* Entry points for the underlying stack to report events back to the user. */
be_bryan 0:b74591d5ab33 742 public:
be_bryan 0:b74591d5ab33 743 /**
be_bryan 0:b74591d5ab33 744 * Forward an attribute read event to all registered handlers.
be_bryan 0:b74591d5ab33 745 *
be_bryan 0:b74591d5ab33 746 * @important This function is meant to be called from the vendor
be_bryan 0:b74591d5ab33 747 * implementation when an attribute read event occurs.
be_bryan 0:b74591d5ab33 748 *
be_bryan 0:b74591d5ab33 749 * @param[in] params Attribute read event to pass to the registered handlers.
be_bryan 0:b74591d5ab33 750 */
be_bryan 0:b74591d5ab33 751 void processReadResponse(const GattReadCallbackParams *params)
be_bryan 0:b74591d5ab33 752 {
be_bryan 0:b74591d5ab33 753 onDataReadCallbackChain(params);
be_bryan 0:b74591d5ab33 754 }
be_bryan 0:b74591d5ab33 755
be_bryan 0:b74591d5ab33 756 /**
be_bryan 0:b74591d5ab33 757 * Forward an attribute written event to all registered handlers.
be_bryan 0:b74591d5ab33 758 *
be_bryan 0:b74591d5ab33 759 * @important This function is meant to be called from the vendor
be_bryan 0:b74591d5ab33 760 * implementation when an attribute written event occurs.
be_bryan 0:b74591d5ab33 761 *
be_bryan 0:b74591d5ab33 762 * @param[in] params Attribute written event to pass to the registered
be_bryan 0:b74591d5ab33 763 * handlers.
be_bryan 0:b74591d5ab33 764 */
be_bryan 0:b74591d5ab33 765 void processWriteResponse(const GattWriteCallbackParams *params)
be_bryan 0:b74591d5ab33 766 {
be_bryan 0:b74591d5ab33 767 onDataWriteCallbackChain(params);
be_bryan 0:b74591d5ab33 768 }
be_bryan 0:b74591d5ab33 769
be_bryan 0:b74591d5ab33 770 /**
be_bryan 0:b74591d5ab33 771 * Forward a handle value notification or indication event to all registered
be_bryan 0:b74591d5ab33 772 * handlers.
be_bryan 0:b74591d5ab33 773 *
be_bryan 0:b74591d5ab33 774 * @important This function is meant to be called from the vendor
be_bryan 0:b74591d5ab33 775 * implementation when a notification or indication event is available.
be_bryan 0:b74591d5ab33 776 *
be_bryan 0:b74591d5ab33 777 * @param[in] params Notification or Indication event to pass to the
be_bryan 0:b74591d5ab33 778 * registered handlers.
be_bryan 0:b74591d5ab33 779 */
be_bryan 0:b74591d5ab33 780 void processHVXEvent(const GattHVXCallbackParams *params)
be_bryan 0:b74591d5ab33 781 {
be_bryan 0:b74591d5ab33 782 if (onHVXCallbackChain) {
be_bryan 0:b74591d5ab33 783 onHVXCallbackChain(params);
be_bryan 0:b74591d5ab33 784 }
be_bryan 0:b74591d5ab33 785 }
be_bryan 0:b74591d5ab33 786
be_bryan 0:b74591d5ab33 787 protected:
be_bryan 0:b74591d5ab33 788 /**
be_bryan 0:b74591d5ab33 789 * Callchain containing all registered event handlers for data read
be_bryan 0:b74591d5ab33 790 * events.
be_bryan 0:b74591d5ab33 791 */
be_bryan 0:b74591d5ab33 792 ReadCallbackChain_t onDataReadCallbackChain;
be_bryan 0:b74591d5ab33 793
be_bryan 0:b74591d5ab33 794 /**
be_bryan 0:b74591d5ab33 795 * Callchain containing all registered event handlers for data write
be_bryan 0:b74591d5ab33 796 * events.
be_bryan 0:b74591d5ab33 797 */
be_bryan 0:b74591d5ab33 798 WriteCallbackChain_t onDataWriteCallbackChain;
be_bryan 0:b74591d5ab33 799
be_bryan 0:b74591d5ab33 800 /**
be_bryan 0:b74591d5ab33 801 * Callchain containing all registered event handlers for update
be_bryan 0:b74591d5ab33 802 * events.
be_bryan 0:b74591d5ab33 803 */
be_bryan 0:b74591d5ab33 804 HVXCallbackChain_t onHVXCallbackChain;
be_bryan 0:b74591d5ab33 805
be_bryan 0:b74591d5ab33 806 /**
be_bryan 0:b74591d5ab33 807 * Callchain containing all registered event handlers for shutdown
be_bryan 0:b74591d5ab33 808 * events.
be_bryan 0:b74591d5ab33 809 */
be_bryan 0:b74591d5ab33 810 GattClientShutdownCallbackChain_t shutdownCallChain;
be_bryan 0:b74591d5ab33 811
be_bryan 0:b74591d5ab33 812 private:
be_bryan 0:b74591d5ab33 813 /* Disallow copy and assignment. */
be_bryan 0:b74591d5ab33 814 GattClient(const GattClient &);
be_bryan 0:b74591d5ab33 815 GattClient& operator=(const GattClient &);
be_bryan 0:b74591d5ab33 816 };
be_bryan 0:b74591d5ab33 817
be_bryan 0:b74591d5ab33 818 /**
be_bryan 0:b74591d5ab33 819 * @}
be_bryan 0:b74591d5ab33 820 * @}
be_bryan 0:b74591d5ab33 821 * @}
be_bryan 0:b74591d5ab33 822 */
be_bryan 0:b74591d5ab33 823
be_bryan 0:b74591d5ab33 824 #endif /* ifndef MBED_GATT_CLIENT_H__ */