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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.