Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
GattClient.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef MBED_GATT_CLIENT_H__ 00018 #define MBED_GATT_CLIENT_H__ 00019 00020 #include "Gap.h" 00021 #include "GattAttribute.h" 00022 #include "ServiceDiscovery.h" 00023 #include "CharacteristicDescriptorDiscovery.h" 00024 00025 #include "GattCallbackParamTypes.h" 00026 00027 #include "CallChainOfFunctionPointersWithContext.h" 00028 00029 /** 00030 * @addtogroup ble 00031 * @{ 00032 * @addtogroup gatt 00033 * @{ 00034 * @addtogroup client 00035 * @{ 00036 */ 00037 00038 /** 00039 * Define procedures required for interacting with a distant GATT server. 00040 * 00041 * @par Discovery procedures 00042 * 00043 * A GATT server hosts a fixed set of services. These services are a logical 00044 * composition of characteristics that may be discovered, read, written or also 00045 * broadcast their state to a connected client. These characteristics may also 00046 * contain metainformation named characteristic descriptors. A characteristic 00047 * descriptor may be used to indicate the unit used for a characteristic value, 00048 * describe in a textual form the characterisic purpose or allow a client to 00049 * register for notification of updates of the characteristic value. 00050 * 00051 * Prior to any interaction with server characteristic, a GATT client 00052 * discovers the layout of the services and characteristics present on the 00053 * server. 00054 * 00055 * The layout of the descriptors of a characteristic may also be issued to 00056 * as an extra discovery step. 00057 * 00058 * @par Attribute manipulation 00059 * 00060 * As a result of the discovery process, the client can start interacting with 00061 * the characteristic discovered. Depending on the characteristic properties 00062 * (acquired during discovery), a client can read or write the value of a given 00063 * characteristic. 00064 * 00065 * Mbed BLE abstracts most read and write operations to offer a single API that 00066 * can be used to read or write characteristics values. Application code does not 00067 * have to handle the fragmentation/reassembly process necessary if the attribute 00068 * value to transported cannot fit in a single data packet. 00069 * 00070 * @par Server Initiated events 00071 * 00072 * If a characteristic has to notify or indicate a property set; then, a client may 00073 * register to a notification or indication from the characteristic. When the 00074 * server updates the characteristic value, the server can forward the 00075 * new value to the registered clients. The notification/indication mechanism 00076 * prevents polling from the client and therefore minimize the transactions 00077 * involved between a client and a server. 00078 * 00079 * Registration is made by writing the Client Characteristic Configuration 00080 * Descriptor, which is present in the characteristic if the notify or 00081 * indicate properties are set. The client discovers that descriptor 00082 * if it intends to register to server initiated events. 00083 */ 00084 class GattClient { 00085 public: 00086 /** 00087 * Attribute read event handler. 00088 * 00089 * @see GattClient::onDataRead(). 00090 */ 00091 typedef FunctionPointerWithContext<const GattReadCallbackParams*> 00092 ReadCallback_t; 00093 00094 /** 00095 * Callchain of attribute read event handlers. 00096 */ 00097 typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams*> 00098 ReadCallbackChain_t; 00099 00100 /** 00101 * GATT write operations. 00102 */ 00103 enum WriteOp_t { 00104 /** 00105 * Write request. 00106 * 00107 * It is used to request the server to write the value of an attribute 00108 * and acknowledge that this has been achieved in a Write Response. 00109 */ 00110 GATT_OP_WRITE_REQ = 0x01, 00111 00112 /** 00113 * Write command. 00114 * 00115 * It is used to request the server to write the value of an attribute. 00116 * The server does not acknowledge the status of the operation. 00117 */ 00118 GATT_OP_WRITE_CMD = 0x02, 00119 00120 /** 00121 * Signed Write command. 00122 * 00123 * It is used to request the server to write the value of an attribute 00124 * using a signed packet. The server does not acknowledge the status 00125 * of the operation. 00126 */ 00127 GATT_OP_SIGNED_WRITE_CMD = 0x03 00128 }; 00129 00130 /** 00131 * Attribute write event handler. 00132 * 00133 * @see GattClient::onDataWrite(). 00134 */ 00135 typedef FunctionPointerWithContext<const GattWriteCallbackParams*> 00136 WriteCallback_t; 00137 00138 /** 00139 * Callchain of attribute write event handlers. 00140 * 00141 * @see GattClient::onDataWrite(). 00142 */ 00143 typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> 00144 WriteCallbackChain_t; 00145 00146 /** 00147 * Handle value notification/indication event handler. 00148 * 00149 * @see to GattClient::onHVX(). 00150 */ 00151 typedef FunctionPointerWithContext<const GattHVXCallbackParams*> 00152 HVXCallback_t; 00153 00154 /** 00155 * Callchain of handle value notification/indication event handlers. 00156 * 00157 * @see GattClient::onHVX(). 00158 */ 00159 typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> 00160 HVXCallbackChain_t; 00161 00162 /** 00163 * Shutdown event handler. 00164 * 00165 * @see GattClient::onShutdown(). 00166 */ 00167 typedef FunctionPointerWithContext<const GattClient *> 00168 GattClientShutdownCallback_t; 00169 00170 00171 /** 00172 * Callchain of shutdown event handlers. 00173 * 00174 * @see to GattClient::onShutown(). 00175 */ 00176 typedef CallChainOfFunctionPointersWithContext<const GattClient *> 00177 GattClientShutdownCallbackChain_t; 00178 00179 /* 00180 * The following functions are meant to be overridden in the platform 00181 * specific subclass. 00182 */ 00183 public: 00184 00185 virtual ~GattClient() { } 00186 00187 /** 00188 * Launch the service and characteristic discovery procedure of a GATT server 00189 * peer. 00190 * 00191 * The procedure invokes application callbacks for matching services or 00192 * characteristics. The process ends after all the services and 00193 * characteristics present on the distant GATT server have been discovered. 00194 * Termination callbacks registered with onServiceDiscoveryTermination() are 00195 * invoked to notify the application of the termination of the procedure. 00196 * 00197 * Application code can track the status of the procedure by invoking the 00198 * function isServiceDiscoveryActive(), which returns true if the 00199 * procedure is ongoing. 00200 * 00201 * At any point, application code can prematurely terminate the discovery 00202 * procedure by calling terminateServiceDiscovery(). 00203 * 00204 * @param[in] connectionHandle Handle of the connection with the peer GATT 00205 * server. 00206 * @param[in] sc Service discovered event handler invoked when a matching 00207 * service has been discovered. This parameter may be NULL. 00208 * @param[in] cc Characteristic discovered event handler invoked when a 00209 * matching characteristic has been found. This parameter may be NULL. 00210 * @param[in] matchingServiceUUID UUID of the service the caller is 00211 * interested in. If a service discovered matches this filter, then @p sc is 00212 * invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, 00213 * which can be used to discover all services present on the peer GATT 00214 * server. 00215 * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the 00216 * caller is interested in. If a characteristic discovered matches this 00217 * filter, then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN 00218 * acts as a wildcard, which can be used to discover all services present on 00219 * the peer GATT server. 00220 * 00221 * @par Discovery procedure implementation detail 00222 * 00223 * It is recommended to implement several strategies based on the 00224 * combination of callbacks and filters passed in input to efficiently 00225 * realize the discovery procedure: 00226 * - If @p sc and @p cc are NULL, then it is not necessay to initiate any 00227 * discovery, and the termination handlers can be invoked immediately. 00228 * - If @p matchingServiceUUID is set, then the GATT discover services by 00229 * service UUID procedure should be used; otherwise, the GATT discover primary 00230 * services procedure should be used. 00231 * - If @p cc is NULL, then the discovery process should end after the discovery 00232 * of the services. 00233 * 00234 * @return BLE_ERROR_NONE if the discovery procedure has been successfully 00235 * started and an appropriate error otherwise. 00236 */ 00237 virtual ble_error_t launchServiceDiscovery( 00238 Gap::Handle_t connectionHandle, 00239 ServiceDiscovery::ServiceCallback_t sc = NULL, 00240 ServiceDiscovery::CharacteristicCallback_t cc = NULL, 00241 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), 00242 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) 00243 ) { 00244 /* Avoid compiler warnings about unused variables. */ 00245 (void)connectionHandle; 00246 (void)sc; 00247 (void)cc; 00248 (void)matchingServiceUUID; 00249 (void)matchingCharacteristicUUIDIn; 00250 00251 /* Requesting action from porters: override this API if this capability 00252 is supported. */ 00253 return BLE_ERROR_NOT_IMPLEMENTED; 00254 } 00255 00256 /** 00257 * Launch the service discovery procedure of a GATT server peer. 00258 * 00259 * The procedure invokes the application callback for matching services. 00260 * The process ends after all the services present on the distant GATT 00261 * server have been discovered. 00262 * Termination callbacks registered with onServiceDiscoveryTermination() are 00263 * invoked to notify the application of the termination of the procedure. 00264 * 00265 * Application code can track the status of the procedure by invoking the 00266 * function isServiceDiscoveryActive(), which returns true if the 00267 * procedure is ongoing. 00268 * 00269 * At any point, application code can prematurely terminate the discovery 00270 * procedure by calling terminateServiceDiscovery(). 00271 * 00272 * @param[in] connectionHandle Handle of the connection with the peer GATT 00273 * server. 00274 * @param[in] callback Service discovered event handler invoked when a 00275 * matching service has been discovered. This parameter may be NULL. 00276 * @param[in] matchingServiceUUID UUID of the service the caller is 00277 * interested in. If a service discovered matches this filter, then @p sc is 00278 * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard, 00279 * which can be used to discover all services present on the peer GATT 00280 * server. 00281 * 00282 * @return BLE_ERROR_NONE if the discovery procedure has been successfully 00283 * started and an appropriate error otherwise. 00284 */ 00285 virtual ble_error_t discoverServices( 00286 Gap::Handle_t connectionHandle, 00287 ServiceDiscovery::ServiceCallback_t callback, 00288 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) 00289 ) { 00290 /* We take advantage of the property 00291 * that providing NULL for the characteristic callback results in 00292 * characteristic discovery being skipped for each matching 00293 * service. This allows for an inexpensive method to discover only 00294 * services. Porters are free to override this. */ 00295 return launchServiceDiscovery( 00296 connectionHandle, callback, NULL, matchingServiceUUID 00297 ); 00298 } 00299 00300 /** 00301 * Launch the service discovery procedure of a GATT server peer. 00302 * 00303 * The process ends after all the services present in the attribute range @p 00304 * startHandle to @p endHandle have been discovered. 00305 * 00306 * Termination callbacks registered with onServiceDiscoveryTermination() are 00307 * invoked to notify the application of the termination of the procedure. 00308 * 00309 * Application code can track the status of the procedure by invoking the 00310 * function isServiceDiscoveryActive(), which returns true if the 00311 * procedure is ongoing. 00312 * 00313 * At any point, application code can prematurely terminate the discovery 00314 * procedure by calling terminateServiceDiscovery(). 00315 * 00316 * @param[in] connectionHandle Handle of the connection with the peer GATT 00317 * server. 00318 * @param[in] callback Service discovered event handler invoked when a 00319 * matching service has been discovered. This parameter may be NULL. 00320 * @param[in] startHandle First attribute handle of the discovery range. 00321 * @param[in] endHandle end Lasr attribute handle of the discovery range. 00322 * 00323 * @return BLE_ERROR_NONE if the discovery procedure has been successfully 00324 * started and an appropriate error otherwise. 00325 */ 00326 virtual ble_error_t discoverServices( 00327 Gap::Handle_t connectionHandle, 00328 ServiceDiscovery::ServiceCallback_t callback, 00329 GattAttribute::Handle_t startHandle, 00330 GattAttribute::Handle_t endHandle 00331 ) { 00332 /* Avoid compiler warnings about unused variables. */ 00333 (void)connectionHandle; 00334 (void)callback; 00335 (void)startHandle; 00336 (void)endHandle; 00337 00338 /* Requesting action from porters: override this API if this capability 00339 is supported. */ 00340 return BLE_ERROR_NOT_IMPLEMENTED; 00341 } 00342 00343 /** 00344 * Check if the service discovery procedure is currently active. 00345 * 00346 * @return true if service discovery procedure is active and false otherwise. 00347 */ 00348 virtual bool isServiceDiscoveryActive(void) const 00349 { 00350 /* Requesting action from porters: override this API if this capability 00351 is supported. */ 00352 return false; 00353 } 00354 00355 /** 00356 * Terminate all ongoing service discovery procedures. 00357 * 00358 * It results in an invocation of the service discovery termination handler 00359 * registered with onServiceDiscoveryTermination(). 00360 */ 00361 virtual void terminateServiceDiscovery(void) 00362 { 00363 /* Requesting action from porters: override this API if this capability 00364 is supported. */ 00365 } 00366 00367 /** 00368 * Initiate the read procedure of an attribute handle. 00369 * 00370 * Once the attribute value has been read in its entirety, the process issues 00371 * an attribute read event and passes it to all events handlers registered 00372 * by onDataRead. 00373 * 00374 * @param[in] connHandle Handle of the connection used to send the read 00375 * request. 00376 * @param[in] attributeHandle Handle of the attribute to read data from. 00377 * @param[in] offset The offset from the start of the attribute value to be 00378 * read. 00379 * 00380 * @return BLE_ERROR_NONE if read procedure successfully started. 00381 * 00382 * @par Implementation notes: 00383 * 00384 * Reading the attribute value in its entirety may involve sending several 00385 * GATT requests to the peer. The following algorithm may be used to 00386 * implement the process: 00387 * 00388 * If the offset is equal to 0, then send a read request; otherwise, send a 00389 * read blob request at the specified offset. 00390 * 00391 * While the attribute data in the response are MTU - 1 long: 00392 * - Concat the response to the value containing the previous responses. 00393 * - Increment the value of the offset by MTU - 1. 00394 * - Send a read blob request with the updated offset. 00395 * 00396 * Finally, concat the last response with the value containing all the 00397 * previous responses and forward that value to the event handlers. 00398 */ 00399 virtual ble_error_t read( 00400 Gap::Handle_t connHandle, 00401 GattAttribute::Handle_t attributeHandle, 00402 uint16_t offset 00403 ) const { 00404 /* Avoid compiler warnings about unused variables. */ 00405 (void)connHandle; 00406 (void)attributeHandle; 00407 (void)offset; 00408 00409 /* Requesting action from porters: override this API if this capability 00410 is supported. */ 00411 return BLE_ERROR_NOT_IMPLEMENTED; 00412 } 00413 00414 /** 00415 * Initiate a write procedure on an attribute value. 00416 * 00417 * If @p cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation 00418 * is reported to the event handlers registered through onDataWritten(). 00419 * 00420 * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD 00421 * is set, then value length is not greater than the size of the mtu 00422 * of connHandle minus three. 00423 * @param[in] connHandle Handle of the connection used to send the write 00424 * request or command. 00425 * @param[in] attributeHandle Handle of the attribute value to write. 00426 * @param[in] length Number of bytes present in @p value. 00427 * @param[in] value Data buffer to write to attributeHandle. 00428 * 00429 * @return BLE_ERROR_NONE if the write procedure successfully started. 00430 * 00431 * @par Implementation notes: 00432 * 00433 * If the operation is a write command, then an implementation uses the 00434 * GATT write without response procedure and an error is returned if 00435 * the data buffer to write is larger than the size of the MTU - 3. 00436 * 00437 * If the operation is a write command and the size of the data buffer to 00438 * write is less than than the size of the MTU - 3, then the ATT write request 00439 * procedure is used, and the response is reported to the handlers 00440 * listening for write response. 00441 * 00442 * Otherwise, the data buffer to write is divided in chunks with a 00443 * maximum size of MTU - 5. Those chunks are sent sequentially to the 00444 * peer in ATT prepare write requests. If an error response is received 00445 * during the process, the procedure ends immediately, the prepared 00446 * write is discarded and an error is reported to the application handlers. 00447 * Once all the chunks have been sent, the transaction is completed 00448 * by sending an execute write request to the peer. The peer response is 00449 * forwarded to the application handlers. 00450 */ 00451 virtual ble_error_t write( 00452 GattClient::WriteOp_t cmd, 00453 Gap::Handle_t connHandle, 00454 GattAttribute::Handle_t attributeHandle, 00455 size_t length, 00456 const uint8_t *value 00457 ) const { 00458 /* Avoid compiler warnings about unused variables. */ 00459 (void)cmd; 00460 (void)connHandle; 00461 (void)attributeHandle; 00462 (void)length; 00463 (void)value; 00464 00465 /* Requesting action from porters: override this API if this capability 00466 is supported. */ 00467 return BLE_ERROR_NOT_IMPLEMENTED; 00468 } 00469 00470 /* Event callback handlers. */ 00471 public: 00472 00473 /** 00474 * Register an attribute read event handler. 00475 * 00476 * @note It is possible to unregister a callback using 00477 * onDataRead().detach(callbackToRemove). 00478 * 00479 * @param[in] callback Event handler being registered. 00480 */ 00481 void onDataRead(ReadCallback_t callback) 00482 { 00483 onDataReadCallbackChain.add(callback); 00484 } 00485 00486 /** 00487 * Get the callchain of attribute read event handlers. 00488 * 00489 * @return A reference to the read event callback chain. 00490 * 00491 * @note It is possible to register new handlers using 00492 * onDataRead().add(callback). 00493 * 00494 * @note It is possible to unregister an handler by using 00495 * onDataRead().detach(callback). 00496 */ 00497 ReadCallbackChain_t & onDataRead() 00498 { 00499 return onDataReadCallbackChain; 00500 } 00501 00502 /** 00503 * Register an attribute write event handler. 00504 * 00505 * @param[in] callback Event handler being registered. 00506 * 00507 * @note It is possible to remove registered handlers using 00508 * onDataWritten().detach(callbackToRemove). 00509 * 00510 * @note Write commands (issued using writeWoResponse) don't generate a 00511 * response. 00512 */ 00513 void onDataWritten(WriteCallback_t callback) 00514 { 00515 onDataWriteCallbackChain.add(callback); 00516 } 00517 00518 /** 00519 * Get the callchain of attribute write event handlers. 00520 * 00521 * @return A reference to the data written callbacks chain. 00522 * 00523 * @note It is possible to register new handlers by using 00524 * onDataWritten().add(callback). 00525 * 00526 * @note It is possible to unregister an handler by using 00527 * onDataWritten().detach(callback). 00528 */ 00529 WriteCallbackChain_t & onDataWritten() 00530 { 00531 return onDataWriteCallbackChain; 00532 } 00533 00534 /** 00535 * Register an attribute write event handler. 00536 * 00537 * @param[in] callback Event handler being registered. 00538 * 00539 * @note It is possible to remove registered handlers using 00540 * onDataWritten().detach(callbackToRemove). 00541 * 00542 * @note Write commands (issued using writeWoResponse) don't generate a 00543 * response. 00544 * 00545 * @deprecated Use GattServer::onDataWritten(). 00546 */ 00547 MBED_DEPRECATED("Use GattServer::onDataWritten()") 00548 void onDataWrite(WriteCallback_t callback) 00549 { 00550 onDataWritten(callback); 00551 } 00552 00553 /** 00554 * Register a service discovery termination event handler. 00555 * 00556 * @param[in] callback Event handler being registered. 00557 */ 00558 virtual void onServiceDiscoveryTermination( 00559 ServiceDiscovery::TerminationCallback_t callback 00560 ) { 00561 (void)callback; /* Avoid compiler warnings about ununsed variables. */ 00562 00563 /* Requesting action from porters: override this API if this capability 00564 is supported. */ 00565 } 00566 00567 /** 00568 * Initiate the descriptor discovery procedure for a given characteristic. 00569 * 00570 * When a descriptor is discovered the discovered descriptor is forwarded 00571 * to @p discoveryCallback. After the discovery of all the descriptors, the 00572 * procedure ends and send a descriptor discovery termination event to @p 00573 * termination callback. 00574 * 00575 * Application code may monitor the discovery process by querying its status 00576 * with isCharacteristicDescriptorDiscoveryActive(). It can also end the 00577 * discovery process by calling terminateCharacteristicDescriptorDiscovery(). 00578 * 00579 * @param[in] characteristic The characteristic owning the descriptors to 00580 * discover. 00581 * @param[in] discoveryCallback Handle descriptor discovered events for the 00582 * duration of the procedure. 00583 * @param[in] terminationCallback Handle descriptor discovery termination 00584 * event of the procedure. 00585 * 00586 * @return BLE_ERROR_NONE if the characteristic descriptor discovery 00587 * procedure has been launched successfully otherwise an appropriate error. 00588 */ 00589 virtual ble_error_t discoverCharacteristicDescriptors( 00590 const DiscoveredCharacteristic& characteristic, 00591 const CharacteristicDescriptorDiscovery::DiscoveryCallback_t & discoveryCallback, 00592 const CharacteristicDescriptorDiscovery::TerminationCallback_t & terminationCallback 00593 ) { 00594 (void) characteristic; 00595 (void) discoveryCallback; 00596 (void) terminationCallback; 00597 /* Requesting action from porter(s): override this API if this 00598 capability is supported. */ 00599 return BLE_ERROR_NOT_IMPLEMENTED; 00600 } 00601 00602 /** 00603 * Query status of the descriptor discovery procedure for a given 00604 * characteristic. 00605 * 00606 * @param[in] characteristic The characteristic concerned by the descriptors 00607 * discovery. 00608 * 00609 * @return true if a descriptors discovery is active for the characteristic 00610 * in input otherwise false. 00611 */ 00612 virtual bool isCharacteristicDescriptorDiscoveryActive( 00613 const DiscoveredCharacteristic& characteristic 00614 ) const { 00615 (void) characteristic; 00616 /* Requesting action from porter(s): override this API if this 00617 capability is supported. */ 00618 return false; 00619 } 00620 00621 /** 00622 * @brief Terminate an ongoing characteristic descriptor discovery procedure. 00623 * 00624 * If the procedure is active, then it ends, and the termination handler 00625 * associated with the procedure is called. 00626 * 00627 * @param[in] characteristic The characteristic containing the descriptors 00628 * being discovered. 00629 */ 00630 virtual void terminateCharacteristicDescriptorDiscovery( 00631 const DiscoveredCharacteristic& characteristic 00632 ) { 00633 /* Requesting action from porter(s): override this API if this 00634 capability is supported. */ 00635 (void) characteristic; 00636 } 00637 00638 /** 00639 * Register an handler for Handle Value Notification/Indication events. 00640 * 00641 * @param callback Event handler to register. 00642 * 00643 * @note It is possible to unregister a callback by using 00644 * onHVX().detach(callbackToRemove). 00645 */ 00646 void onHVX(HVXCallback_t callback) 00647 { 00648 onHVXCallbackChain.add(callback); 00649 } 00650 00651 /** 00652 * Register a shutdown event handler. 00653 * 00654 * The registered handler is invoked when the GattClient instance is 00655 * about to be shut down. 00656 * 00657 * @param[in] callback Event handler to invoke when a shutdown event is 00658 * available. 00659 * 00660 * @note onShutdown().detach(callback) may be used to unregister a given 00661 * callback. 00662 * 00663 * @see BLE::shutdown() 00664 */ 00665 void onShutdown(const GattClientShutdownCallback_t & callback) 00666 { 00667 shutdownCallChain.add(callback); 00668 } 00669 00670 /** 00671 * Register a shutdown event handler. 00672 * 00673 * The registered handler is invoked when the GattClient instance is 00674 * about to be shut down. 00675 * 00676 * @param[in] objPtr Instance that will be used to invoke @p memberPtr. 00677 * @param[in] memberPtr Event handler to invoke when a shutdown event is 00678 * available. 00679 */ 00680 template <typename T> 00681 void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *)) 00682 { 00683 shutdownCallChain.add(objPtr, memberPtr); 00684 } 00685 00686 /** 00687 * Get the callchain of shutdown event handlers. 00688 * 00689 * @return A reference to the shutdown event callbacks chain. 00690 * 00691 * @note onShutdown().add(callback) may be used to register new handlers. 00692 * 00693 * @note onShutdown().detach(callback) may be used to unregister an handler. 00694 */ 00695 GattClientShutdownCallbackChain_t & onShutdown() 00696 { 00697 return shutdownCallChain; 00698 } 00699 00700 /** 00701 * @brief provide access to the callchain of HVX callbacks. 00702 * 00703 * @return A reference to the HVX callbacks chain. 00704 * 00705 * @note It is possible to register callbacks using onHVX().add(callback). 00706 * 00707 * @note It is possible to unregister callbacks using onHVX().detach(callback). 00708 */ 00709 HVXCallbackChain_t & onHVX() { 00710 return onHVXCallbackChain; 00711 } 00712 00713 public: 00714 /** 00715 * Reset the state of the GattClient instance. 00716 * 00717 * Prior to any state modification, shutdown event handlers are notified 00718 * that the GattClient instance is about to be shut down. Then, running 00719 * procedures end. Finally, the state of the instance is reset. 00720 * 00721 * @par implementation note 00722 * 00723 * This function is meant to be overridden in the platform-specific 00724 * subclass. Nevertheless, the subclass only resets its 00725 * state and not the data held in GattClient members. This is achieved 00726 * by a call to GattClient::reset() from the subclass' reset() 00727 * implementation. 00728 * 00729 * @return BLE_ERROR_NONE on success. 00730 */ 00731 virtual ble_error_t reset(void) 00732 { 00733 /* Notify that the instance is about to shut down. */ 00734 shutdownCallChain.call(this); 00735 shutdownCallChain.clear(); 00736 00737 onDataReadCallbackChain.clear(); 00738 onDataWriteCallbackChain.clear(); 00739 onHVXCallbackChain.clear(); 00740 00741 return BLE_ERROR_NONE; 00742 } 00743 00744 protected: 00745 GattClient() 00746 { 00747 /* Empty */ 00748 } 00749 00750 /* Entry points for the underlying stack to report events back to the user. */ 00751 public: 00752 /** 00753 * Forward an attribute read event to all registered handlers. 00754 * 00755 * @attention This function is meant to be called from the vendor 00756 * implementation when an attribute read event occurs. 00757 * 00758 * @param[in] params Attribute read event to pass to the registered handlers. 00759 */ 00760 void processReadResponse(const GattReadCallbackParams *params) 00761 { 00762 onDataReadCallbackChain(params); 00763 } 00764 00765 /** 00766 * Forward an attribute written event to all registered handlers. 00767 * 00768 * @attention This function is meant to be called from the vendor 00769 * implementation when an attribute written event occurs. 00770 * 00771 * @param[in] params Attribute written event to pass to the registered 00772 * handlers. 00773 */ 00774 void processWriteResponse(const GattWriteCallbackParams *params) 00775 { 00776 onDataWriteCallbackChain(params); 00777 } 00778 00779 /** 00780 * Forward a handle value notification or indication event to all registered 00781 * handlers. 00782 * 00783 * @attention This function is meant to be called from the vendor 00784 * implementation when a notification or indication event is available. 00785 * 00786 * @param[in] params Notification or Indication event to pass to the 00787 * registered handlers. 00788 */ 00789 void processHVXEvent(const GattHVXCallbackParams *params) 00790 { 00791 if (onHVXCallbackChain) { 00792 onHVXCallbackChain(params); 00793 } 00794 } 00795 00796 protected: 00797 /** 00798 * Callchain containing all registered event handlers for data read 00799 * events. 00800 */ 00801 ReadCallbackChain_t onDataReadCallbackChain; 00802 00803 /** 00804 * Callchain containing all registered event handlers for data write 00805 * events. 00806 */ 00807 WriteCallbackChain_t onDataWriteCallbackChain; 00808 00809 /** 00810 * Callchain containing all registered event handlers for update 00811 * events. 00812 */ 00813 HVXCallbackChain_t onHVXCallbackChain; 00814 00815 /** 00816 * Callchain containing all registered event handlers for shutdown 00817 * events. 00818 */ 00819 GattClientShutdownCallbackChain_t shutdownCallChain; 00820 00821 private: 00822 /* Disallow copy and assignment. */ 00823 GattClient(const GattClient &); 00824 GattClient& operator=(const GattClient &); 00825 }; 00826 00827 /** 00828 * @} 00829 * @} 00830 * @} 00831 */ 00832 00833 #endif /* ifndef MBED_GATT_CLIENT_H__ */
Generated on Tue Aug 9 2022 00:37:08 by
