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     /**
00122      * Attribute write event handler.
00123      *
00124      * @see GattClient::onDataWrite().
00125      */
00126     typedef FunctionPointerWithContext<const GattWriteCallbackParams*> 
00127         WriteCallback_t;
00128 
00129     /**
00130      * Callchain of attribute write event handlers.
00131      *
00132      * @see GattClient::onDataWrite().
00133      */
00134     typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> 
00135         WriteCallbackChain_t;
00136 
00137     /**
00138      * Handle value notification/indication event handler.
00139      *
00140      * @see to GattClient::onHVX().
00141      */
00142     typedef FunctionPointerWithContext<const GattHVXCallbackParams*> 
00143         HVXCallback_t;
00144 
00145     /**
00146      * Callchain of handle value notification/indication event handlers.
00147      *
00148      * @see GattClient::onHVX().
00149      */
00150     typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> 
00151         HVXCallbackChain_t;
00152 
00153     /**
00154      * Shutdown event handler.
00155      *
00156      * @see GattClient::onShutdown().
00157      */
00158     typedef FunctionPointerWithContext<const GattClient *> 
00159         GattClientShutdownCallback_t;
00160 
00161 
00162     /**
00163      * Callchain of shutdown event handlers.
00164      *
00165      * @see to GattClient::onShutown().
00166      */
00167     typedef CallChainOfFunctionPointersWithContext<const GattClient *> 
00168         GattClientShutdownCallbackChain_t;
00169 
00170     /*
00171      * The following functions are meant to be overridden in the platform
00172      * specific subclass.
00173      */
00174 public:
00175 
00176     virtual ~GattClient() { }
00177 
00178     /**
00179      * Launch the service and characteristic discovery procedure of a GATT server
00180      * peer.
00181      *
00182      * The procedure invokes application callbacks for matching services or
00183      * characteristics. The process ends after all the services and
00184      * characteristics present on the distant GATT server have been discovered.
00185      * Termination callbacks registered with onServiceDiscoveryTermination() are
00186      * invoked to notify the application of the termination of the procedure.
00187      *
00188      * Application code can track the status of the procedure by invoking the
00189      * function isServiceDiscoveryActive(), which returns true if the
00190      * procedure is ongoing.
00191      *
00192      * At any point, application code can prematurely terminate the discovery
00193      * procedure by calling terminateServiceDiscovery().
00194      *
00195      * @param[in] connectionHandle Handle of the connection with the peer GATT
00196      * server.
00197      * @param[in] sc Service discovered event handler invoked when a matching
00198      * service has been discovered. This parameter may be NULL.
00199      * @param[in] cc Characteristic discovered event handler invoked when a
00200      * matching characteristic has been found. This parameter may be NULL.
00201      * @param[in] matchingServiceUUID UUID of the service the caller is
00202      * interested in. If a service discovered matches this filter, then @p sc is
00203      * invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard,
00204      * which can be used to discover all services present on the peer GATT
00205      * server.
00206      * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the
00207      * caller is interested in. If a characteristic discovered matches this
00208      * filter, then @p cc is  invoked with it. The special value BLE_UUID_UNKNOWN
00209      * acts as a wildcard, which can be used to discover all services present on
00210      * the peer GATT server.
00211      *
00212      * @par Discovery procedure implementation detail
00213      *
00214      * It is recommended to implement several strategies based on the
00215      * combination of callbacks and filters passed in input to efficiently
00216      * realize the discovery procedure:
00217      * - If @p sc and @p cc are NULL, then it is not necessay to initiate any
00218      * discovery, and the termination handlers can be invoked immediately.
00219      * - If @p matchingServiceUUID is set, then the GATT discover services by
00220      * service UUID procedure should be used; otherwise, the GATT discover primary
00221      * services procedure should be used.
00222      * - If @p cc is NULL, then the discovery process should end after the discovery
00223      * of the services.
00224      *
00225      * @return BLE_ERROR_NONE if the discovery procedure has been successfully
00226      * started and an appropriate error otherwise.
00227      */
00228     virtual ble_error_t launchServiceDiscovery(
00229         Gap::Handle_t connectionHandle,
00230         ServiceDiscovery::ServiceCallback_t  sc = NULL,
00231         ServiceDiscovery::CharacteristicCallback_t   cc = NULL,
00232         const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
00233         const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)
00234     ) {
00235         /* Avoid compiler warnings about unused variables. */
00236         (void)connectionHandle;
00237         (void)sc;
00238         (void)cc;
00239         (void)matchingServiceUUID;
00240         (void)matchingCharacteristicUUIDIn;
00241 
00242         /* Requesting action from porters: override this API if this capability
00243            is supported. */
00244         return BLE_ERROR_NOT_IMPLEMENTED;
00245     }
00246 
00247     /**
00248      * Launch the service discovery procedure of a GATT server peer.
00249      *
00250      * The procedure invokes the application callback for matching services.
00251      * The process ends after all the services present on the distant GATT
00252      * server have been discovered.
00253      * Termination callbacks registered with onServiceDiscoveryTermination() are
00254      * invoked to notify the application of the termination of the procedure.
00255      *
00256      * Application code can track the status of the procedure by invoking the
00257      * function isServiceDiscoveryActive(), which returns true if the
00258      * procedure is ongoing.
00259      *
00260      * At any point, application code can prematurely terminate the discovery
00261      * procedure by calling terminateServiceDiscovery().
00262      *
00263      * @param[in] connectionHandle Handle of the connection with the peer GATT
00264      * server.
00265      * @param[in] callback Service discovered event handler invoked when a
00266      * matching service has been discovered. This parameter may be NULL.
00267      * @param[in] matchingServiceUUID UUID of the service the caller is
00268      * interested in. If a service discovered matches this filter, then @p sc is
00269      * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard,
00270      * which can be used to discover all services present on the peer GATT
00271      * server.
00272      *
00273      * @return BLE_ERROR_NONE if the discovery procedure has been successfully
00274      * started and an appropriate error otherwise.
00275      */
00276     virtual ble_error_t discoverServices(
00277         Gap::Handle_t connectionHandle,
00278         ServiceDiscovery::ServiceCallback_t  callback,
00279         const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)
00280     ) {
00281         /* We take advantage of the property
00282          * that providing NULL for the characteristic callback results in
00283          * characteristic discovery being skipped for each matching
00284          * service. This allows for an inexpensive method to discover only
00285          * services. Porters are free to override this. */
00286         return launchServiceDiscovery(
00287             connectionHandle, callback, NULL, matchingServiceUUID
00288         );
00289     }
00290 
00291     /**
00292      * Launch the service discovery procedure of a GATT server peer.
00293      *
00294      * The process ends after all the services present in the attribute range @p
00295      * startHandle to @p endHandle have been discovered.
00296      *
00297      * Termination callbacks registered with onServiceDiscoveryTermination() are
00298      * invoked to notify the application of the termination of the procedure.
00299      *
00300      * Application code can track the status of the procedure by invoking the
00301      * function isServiceDiscoveryActive(), which returns true if the
00302      * procedure is ongoing.
00303      *
00304      * At any point, application code can prematurely terminate the discovery
00305      * procedure by calling terminateServiceDiscovery().
00306      *
00307      * @param[in] connectionHandle Handle of the connection with the peer GATT
00308      * server.
00309      * @param[in] callback Service discovered event handler invoked when a
00310      * matching service has been discovered. This parameter may be NULL.
00311      * @param[in] startHandle First attribute handle of the discovery range.
00312      * @param[in] endHandle end Lasr attribute handle of the discovery range.
00313      *
00314      * @return BLE_ERROR_NONE if the discovery procedure has been successfully
00315      * started and an appropriate error otherwise.
00316      */
00317     virtual ble_error_t discoverServices(
00318         Gap::Handle_t connectionHandle,
00319         ServiceDiscovery::ServiceCallback_t  callback,
00320         GattAttribute::Handle_t startHandle,
00321         GattAttribute::Handle_t endHandle
00322     ) {
00323         /* Avoid compiler warnings about unused variables. */
00324         (void)connectionHandle;
00325         (void)callback;
00326         (void)startHandle;
00327         (void)endHandle;
00328 
00329         /* Requesting action from porters: override this API if this capability
00330            is supported. */
00331         return BLE_ERROR_NOT_IMPLEMENTED;
00332     }
00333 
00334     /**
00335      * Check if the service discovery procedure is currently active.
00336      *
00337      * @return true if service discovery procedure is active and false otherwise.
00338      */
00339     virtual bool isServiceDiscoveryActive(void) const
00340     {
00341         /* Requesting action from porters: override this API if this capability
00342            is supported. */
00343         return false;
00344     }
00345 
00346     /**
00347      * Terminate all ongoing service discovery procedures.
00348      *
00349      * It results in an invocation of the service discovery termination handler
00350      * registered with onServiceDiscoveryTermination().
00351      */
00352     virtual void terminateServiceDiscovery(void)
00353     {
00354         /* Requesting action from porters: override this API if this capability
00355            is supported. */
00356     }
00357 
00358     /**
00359      * Initiate the read procedure of an attribute handle.
00360      *
00361      * Once the attribute value has been read in its entirety, the process issues
00362      * an attribute read event and passes it to all events handlers registered
00363      * by onDataRead.
00364      *
00365      * @param[in] connHandle Handle of the connection used to send the read
00366      * request.
00367      * @param[in] attributeHandle Handle of the attribute to read data from.
00368      * @param[in] offset The offset from the start of the attribute value to be
00369      * read.
00370      *
00371      * @return BLE_ERROR_NONE if read procedure successfully started.
00372      *
00373      * @par Implementation notes:
00374      *
00375      * Reading the attribute value in its entirety may involve sending several
00376      * GATT requests to the peer. The following algorithm may be used to
00377      * implement the process:
00378      *
00379      * If the offset is equal to 0, then send a read request; otherwise, send a
00380      * read blob request at the specified offset.
00381      *
00382      * While the attribute data in the response are MTU - 1 long:
00383      *   - Concat the response to the value containing the previous responses.
00384      *   - Increment the value of the offset by MTU - 1.
00385      *   - Send a read blob request with the updated offset.
00386      *
00387      * Finally, concat the last response with the value containing all the
00388      * previous responses and forward that value to the event handlers.
00389      */
00390     virtual ble_error_t read(
00391         Gap::Handle_t connHandle,
00392         GattAttribute::Handle_t attributeHandle,
00393         uint16_t offset
00394     ) const {
00395         /* Avoid compiler warnings about unused variables. */
00396         (void)connHandle;
00397         (void)attributeHandle;
00398         (void)offset;
00399 
00400         /* Requesting action from porters: override this API if this capability
00401            is supported. */
00402         return BLE_ERROR_NOT_IMPLEMENTED;
00403     }
00404 
00405     /**
00406      * Initiate a write procedure on an attribute value.
00407      *
00408      * If @p cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation
00409      * is reported to the event handlers registered through onDataWritten().
00410      *
00411      * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD
00412      * is set, then value length is not greater than the size of the mtu
00413      * of connHandle minus three.
00414      * @param[in] connHandle Handle of the connection used to send the write
00415      * request or command.
00416      * @param[in] attributeHandle Handle of the attribute value to write.
00417      * @param[in] length Number of bytes present in @p value.
00418      * @param[in] value Data buffer to write to attributeHandle.
00419      *
00420      * @return BLE_ERROR_NONE if the write procedure successfully started.
00421      *
00422      * @par Implementation notes:
00423      *
00424      * If the operation is a write command, then an implementation uses the
00425      * GATT write without response procedure and an error is returned if
00426      * the data buffer to write is larger than the size of the MTU - 3.
00427      *
00428      * If the operation is a write command and the size of the data buffer to
00429      * write is less than than the size of the MTU - 3, then the ATT write request
00430      * procedure is used, and the response is reported to the handlers
00431      * listening for write response.
00432      *
00433      * Otherwise, the data buffer to write is divided in chunks with a
00434      * maximum size of MTU - 5. Those chunks are sent sequentially to the
00435      * peer in ATT prepare write requests. If an error response is received
00436      * during the process, the procedure ends immediately, the prepared
00437      * write is discarded and an error is reported to the application handlers.
00438      * Once all the chunks have been sent, the transaction is completed
00439      * by sending an execute write request to the peer. The peer response is
00440      * forwarded to the application handlers.
00441      */
00442     virtual ble_error_t write(
00443         GattClient::WriteOp_t cmd,
00444         Gap::Handle_t connHandle,
00445         GattAttribute::Handle_t attributeHandle,
00446         size_t length,
00447         const uint8_t *value
00448     ) const {
00449         /* Avoid compiler warnings about unused variables. */
00450         (void)cmd;
00451         (void)connHandle;
00452         (void)attributeHandle;
00453         (void)length;
00454         (void)value;
00455 
00456         /* Requesting action from porters: override this API if this capability
00457            is supported. */
00458         return BLE_ERROR_NOT_IMPLEMENTED;
00459     }
00460 
00461     /* Event callback handlers. */
00462 public:
00463 
00464     /**
00465      * Register an attribute read event handler.
00466      *
00467      * @note It is possible to unregister a callback using
00468      * onDataRead().detach(callbackToRemove).
00469      *
00470      * @param[in] callback Event handler being registered.
00471      */
00472     void onDataRead(ReadCallback_t  callback)
00473     {
00474         onDataReadCallbackChain.add(callback);
00475     }
00476 
00477     /**
00478      * Get the callchain of attribute read event handlers.
00479      *
00480      * @return A reference to the read event callback chain.
00481      *
00482      * @note It is possible to register new handlers using
00483      * onDataRead().add(callback).
00484      *
00485      * @note It is possible to unregister an handler by using
00486      * onDataRead().detach(callback).
00487      */
00488     ReadCallbackChain_t & onDataRead()
00489     {
00490         return onDataReadCallbackChain;
00491     }
00492 
00493     /**
00494      * Register an attribute write event handler.
00495      *
00496      * @param[in] callback Event handler being registered.
00497      *
00498      * @note It is possible to remove registered handlers using
00499      * onDataWritten().detach(callbackToRemove).
00500      *
00501      * @note Write commands (issued using writeWoResponse) don't generate a
00502      * response.
00503      */
00504     void onDataWritten(WriteCallback_t  callback)
00505     {
00506         onDataWriteCallbackChain.add(callback);
00507     }
00508 
00509     /**
00510      * Get the callchain of attribute write event handlers.
00511      *
00512      * @return A reference to the data written callbacks chain.
00513      *
00514      * @note It is possible to register new handlers by using
00515      * onDataWritten().add(callback).
00516      *
00517      * @note It is possible to unregister an handler by using
00518      * onDataWritten().detach(callback).
00519      */
00520     WriteCallbackChain_t & onDataWritten()
00521     {
00522         return onDataWriteCallbackChain;
00523     }
00524 
00525     /**
00526      * Register an attribute write event handler.
00527      *
00528      * @param[in] callback Event handler being registered.
00529      *
00530      * @note It is possible to remove registered handlers using
00531      * onDataWritten().detach(callbackToRemove).
00532      *
00533      * @note Write commands (issued using writeWoResponse) don't generate a
00534      * response.
00535      *
00536      * @deprecated Use GattServer::onDataWritten().
00537      */
00538     MBED_DEPRECATED("Use GattServer::onDataWritten()")
00539     void onDataWrite(WriteCallback_t  callback)
00540     {
00541         onDataWritten(callback);
00542     }
00543 
00544     /**
00545      * Register a service discovery termination event handler.
00546      *
00547      * @param[in] callback Event handler being registered.
00548      */
00549     virtual void onServiceDiscoveryTermination(
00550         ServiceDiscovery::TerminationCallback_t  callback
00551     ) {
00552         (void)callback; /* Avoid compiler warnings about ununsed variables. */
00553 
00554         /* Requesting action from porters: override this API if this capability
00555            is supported. */
00556     }
00557 
00558     /**
00559      * Initiate the descriptor discovery procedure for a given characteristic.
00560      *
00561      * When a descriptor is discovered the discovered descriptor is forwarded
00562      * to @p discoveryCallback. After the discovery of all the descriptors, the
00563      * procedure ends and send a descriptor discovery termination event to @p
00564      * termination callback.
00565      *
00566      * Application code may monitor the discovery process by querying its status
00567      * with isCharacteristicDescriptorDiscoveryActive(). It can also end the
00568      * discovery process by calling terminateCharacteristicDescriptorDiscovery().
00569      *
00570      * @param[in] characteristic The characteristic owning the descriptors to
00571      * discover.
00572      * @param[in] discoveryCallback Handle descriptor discovered events for the
00573      * duration of the procedure.
00574      * @param[in] terminationCallback Handle descriptor discovery termination
00575      * event of the procedure.
00576      *
00577      * @return BLE_ERROR_NONE if the characteristic descriptor discovery
00578      * procedure has been launched successfully otherwise an appropriate error.
00579      */
00580     virtual ble_error_t discoverCharacteristicDescriptors(
00581         const DiscoveredCharacteristic& characteristic,
00582         const CharacteristicDescriptorDiscovery::DiscoveryCallback_t & discoveryCallback,
00583         const CharacteristicDescriptorDiscovery::TerminationCallback_t & terminationCallback
00584     ) {
00585         (void) characteristic;
00586         (void) discoveryCallback;
00587         (void) terminationCallback;
00588         /* Requesting action from porter(s): override this API if this
00589            capability is supported. */
00590         return BLE_ERROR_NOT_IMPLEMENTED;
00591     }
00592 
00593     /**
00594      * Query status of the descriptor discovery procedure for a given
00595      * characteristic.
00596      *
00597      * @param[in] characteristic The characteristic concerned by the descriptors
00598      * discovery.
00599      *
00600      * @return true if a descriptors discovery is active for the characteristic
00601      * in input otherwise false.
00602      */
00603     virtual bool isCharacteristicDescriptorDiscoveryActive(
00604         const DiscoveredCharacteristic& characteristic
00605     ) const {
00606         (void) characteristic;
00607         /* Requesting action from porter(s): override this API if this
00608            capability is supported. */
00609         return false;
00610     }
00611 
00612     /**
00613      * @brief Terminate an ongoing characteristic descriptor discovery procedure.
00614      *
00615      * If the procedure is active, then it ends, and the termination handler
00616      * associated with the procedure is called.
00617      *
00618      * @param[in] characteristic The characteristic containing the descriptors
00619      * being discovered.
00620      */
00621     virtual void terminateCharacteristicDescriptorDiscovery(
00622         const DiscoveredCharacteristic& characteristic
00623     ) {
00624         /* Requesting action from porter(s): override this API if this
00625            capability is supported. */
00626         (void) characteristic;
00627     }
00628 
00629     /**
00630      * Register an handler for Handle Value Notification/Indication events.
00631      *
00632      * @param callback Event handler to register.
00633      *
00634      * @note It is possible to unregister a callback by using
00635      * onHVX().detach(callbackToRemove).
00636      */
00637     void onHVX(HVXCallback_t  callback)
00638     {
00639         onHVXCallbackChain.add(callback);
00640     }
00641 
00642     /**
00643      * Register a shutdown event handler.
00644      *
00645      * The registered handler is invoked when the GattClient instance is
00646      * about to be shut down.
00647      *
00648      * @param[in] callback Event handler to invoke when a shutdown event is
00649      * available.
00650      *
00651      * @note onShutdown().detach(callback) may be used to unregister a given
00652      * callback.
00653      *
00654      * @see BLE::shutdown()
00655      */
00656     void onShutdown(const GattClientShutdownCallback_t & callback)
00657     {
00658         shutdownCallChain.add(callback);
00659     }
00660 
00661     /**
00662      * Register a shutdown event handler.
00663      *
00664      * The registered handler is invoked when the GattClient instance is
00665      * about to be shut down.
00666      *
00667      * @param[in] objPtr Instance that will be used to invoke @p memberPtr.
00668      * @param[in] memberPtr Event handler to invoke when a shutdown event is
00669      * available.
00670      */
00671     template <typename T>
00672     void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *))
00673     {
00674         shutdownCallChain.add(objPtr, memberPtr);
00675     }
00676 
00677     /**
00678      * Get the callchain of shutdown event handlers.
00679      *
00680      * @return A reference to the shutdown event callbacks chain.
00681      *
00682      * @note onShutdown().add(callback) may be used to register new handlers.
00683      *
00684      * @note onShutdown().detach(callback) may be used to unregister an handler.
00685      */
00686     GattClientShutdownCallbackChain_t & onShutdown()
00687     {
00688         return shutdownCallChain;
00689     }
00690 
00691     /**
00692      * @brief provide access to the callchain of HVX callbacks.
00693      *
00694      * @return A reference to the HVX callbacks chain.
00695      *
00696      * @note It is possible to register callbacks using onHVX().add(callback).
00697      *
00698      * @note It is possible to unregister callbacks using onHVX().detach(callback).
00699      */
00700     HVXCallbackChain_t & onHVX() {
00701         return onHVXCallbackChain;
00702     }
00703 
00704 public:
00705     /**
00706      * Reset the state of the GattClient instance.
00707      *
00708      * Prior to any state modification, shutdown event handlers are notified
00709      * that the GattClient instance is about to be shut down. Then, running
00710      * procedures end. Finally, the state of the instance is reset.
00711      *
00712      * @par implementation note
00713      *
00714      * This function is meant to be overridden in the platform-specific
00715      * subclass. Nevertheless, the subclass only resets its
00716      * state and not the data held in GattClient members. This is achieved
00717      * by a call to GattClient::reset() from the subclass' reset()
00718      * implementation.
00719      *
00720      * @return BLE_ERROR_NONE on success.
00721      */
00722     virtual ble_error_t reset(void)
00723     {
00724         /* Notify that the instance is about to shut down. */
00725         shutdownCallChain.call(this);
00726         shutdownCallChain.clear();
00727 
00728         onDataReadCallbackChain.clear();
00729         onDataWriteCallbackChain.clear();
00730         onHVXCallbackChain.clear();
00731 
00732         return BLE_ERROR_NONE;
00733     }
00734 
00735 protected:
00736     GattClient()
00737     {
00738         /* Empty */
00739     }
00740 
00741     /* Entry points for the underlying stack to report events back to the user. */
00742 public:
00743     /**
00744      * Forward an attribute read event to all registered handlers.
00745      *
00746      * @attention This function is meant to be called from the vendor
00747      * implementation when an attribute read event occurs.
00748      *
00749      * @param[in] params Attribute read event to pass to the registered handlers.
00750      */
00751     void processReadResponse(const GattReadCallbackParams *params)
00752     {
00753         onDataReadCallbackChain(params);
00754     }
00755 
00756     /**
00757      * Forward an attribute written event to all registered handlers.
00758      *
00759      * @attention This function is meant to be called from the vendor
00760      * implementation when an attribute written event occurs.
00761      *
00762      * @param[in] params Attribute written event to pass to the registered
00763      * handlers.
00764      */
00765     void processWriteResponse(const GattWriteCallbackParams *params)
00766     {
00767         onDataWriteCallbackChain(params);
00768     }
00769 
00770     /**
00771      * Forward a handle value notification or indication event to all registered
00772      * handlers.
00773      *
00774      * @attention This function is meant to be called from the vendor
00775      * implementation when a notification or indication event is available.
00776      *
00777      * @param[in] params Notification or Indication event to pass to the
00778      * registered handlers.
00779      */
00780     void processHVXEvent(const GattHVXCallbackParams *params)
00781     {
00782         if (onHVXCallbackChain) {
00783             onHVXCallbackChain(params);
00784         }
00785     }
00786 
00787 protected:
00788     /**
00789      * Callchain containing all registered event handlers for data read
00790      * events.
00791      */
00792     ReadCallbackChain_t  onDataReadCallbackChain;
00793 
00794     /**
00795      * Callchain containing all registered event handlers for data write
00796      * events.
00797      */
00798     WriteCallbackChain_t  onDataWriteCallbackChain;
00799 
00800     /**
00801      * Callchain containing all registered event handlers for update
00802      * events.
00803      */
00804     HVXCallbackChain_t  onHVXCallbackChain;
00805 
00806     /**
00807      * Callchain containing all registered event handlers for shutdown
00808      * events.
00809      */
00810     GattClientShutdownCallbackChain_t  shutdownCallChain;
00811 
00812 private:
00813     /* Disallow copy and assignment. */
00814     GattClient(const GattClient &);
00815     GattClient& operator=(const GattClient &);
00816 };
00817 
00818 /**
00819  * @}
00820  * @}
00821  * @}
00822  */
00823 
00824 #endif /* ifndef MBED_GATT_CLIENT_H__ */