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 a service discovery termination event handler.
530  *
531  * @param[in] callback Event handler being registered.
532  */
533  void onServiceDiscoveryTermination(
535  );
536 
537  /**
538  * Initiate the descriptor discovery procedure for a given characteristic.
539  *
540  * When a descriptor is discovered the discovered descriptor is forwarded
541  * to @p discoveryCallback. After the discovery of all the descriptors, the
542  * procedure ends and send a descriptor discovery termination event to @p
543  * termination callback.
544  *
545  * Application code may monitor the discovery process by querying its status
546  * with isCharacteristicDescriptorDiscoveryActive(). It can also end the
547  * discovery process by calling terminateCharacteristicDescriptorDiscovery().
548  *
549  * @param[in] characteristic The characteristic owning the descriptors to
550  * discover.
551  * @param[in] discoveryCallback Handle descriptor discovered events for the
552  * duration of the procedure.
553  * @param[in] terminationCallback Handle descriptor discovery termination
554  * event of the procedure.
555  *
556  * @return BLE_ERROR_NONE if the characteristic descriptor discovery
557  * procedure has been launched successfully otherwise an appropriate error.
558  */
559  ble_error_t discoverCharacteristicDescriptors(
560  const DiscoveredCharacteristic& characteristic,
563  );
564 
565  /**
566  * Query status of the descriptor discovery procedure for a given
567  * characteristic.
568  *
569  * @param[in] characteristic The characteristic concerned by the descriptors
570  * discovery.
571  *
572  * @return true if a descriptors discovery is active for the characteristic
573  * in input otherwise false.
574  */
575  bool isCharacteristicDescriptorDiscoveryActive(
576  const DiscoveredCharacteristic& characteristic
577  ) const;
578 
579  /**
580  * @brief Terminate an ongoing characteristic descriptor discovery procedure.
581  *
582  * If the procedure is active, then it ends, and the termination handler
583  * associated with the procedure is called.
584  *
585  * @param[in] characteristic The characteristic containing the descriptors
586  * being discovered.
587  */
588  void terminateCharacteristicDescriptorDiscovery(
589  const DiscoveredCharacteristic& characteristic
590  );
591 
592  /**
593  * Trigger MTU negotiation. This might result in a Gap event onAttMtuChange
594  * being called if MTU changes.
595  *
596  * @note This does not guarantee a change in MTU size. If size remains
597  * unchanged no event will be generated.
598  *
599  * @param connection Connection on which the MTU is to be negotiated.
600  *
601  * @return BLE_ERROR_NONE if the procedure has been launched successfully
602  * otherwise an appropriate error.
603  */
604  ble_error_t negotiateAttMtu(ble::connection_handle_t connection);
605 
606  /**
607  * Register an handler for Handle Value Notification/Indication events.
608  *
609  * @param callback Event handler to register.
610  *
611  * @note It is possible to unregister a callback by using
612  * onHVX().detach(callbackToRemove).
613  */
614  void onHVX(HVXCallback_t callback)
615  {
616  onHVXCallbackChain.add(callback);
617  }
618 
619  /**
620  * Register a shutdown event handler.
621  *
622  * The registered handler is invoked when the GattClient instance is
623  * about to be shut down.
624  *
625  * @param[in] callback Event handler to invoke when a shutdown event is
626  * available.
627  *
628  * @note onShutdown().detach(callback) may be used to unregister a given
629  * callback.
630  *
631  * @see BLE::shutdown()
632  */
634  {
635  shutdownCallChain.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] objPtr Instance that will be used to invoke @p memberPtr.
645  * @param[in] memberPtr Event handler to invoke when a shutdown event is
646  * available.
647  */
648  template <typename T>
649  void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *))
650  {
651  shutdownCallChain.add(objPtr, memberPtr);
652  }
653 
654  /**
655  * Get the callchain of shutdown event handlers.
656  *
657  * @return A reference to the shutdown event callbacks chain.
658  *
659  * @note onShutdown().add(callback) may be used to register new handlers.
660  *
661  * @note onShutdown().detach(callback) may be used to unregister an handler.
662  */
664  {
665  return shutdownCallChain;
666  }
667 
668  /**
669  * @brief provide access to the callchain of HVX callbacks.
670  *
671  * @return A reference to the HVX callbacks chain.
672  *
673  * @note It is possible to register callbacks using onHVX().add(callback).
674  *
675  * @note It is possible to unregister callbacks using onHVX().detach(callback).
676  */
678  return onHVXCallbackChain;
679  }
680 
681 public:
682  /**
683  * Reset the state of the GattClient instance.
684  *
685  * Prior to any state modification, shutdown event handlers are notified
686  * that the GattClient instance is about to be shut down. Then, running
687  * procedures end. Finally, the state of the instance is reset.
688  *
689  * @par implementation note
690  *
691  * This function is meant to be overridden in the platform-specific
692  * subclass. Nevertheless, the subclass only resets its
693  * state and not the data held in GattClient members. This is achieved
694  * by a call to GattClient::reset() from the subclass' reset()
695  * implementation.
696  *
697  * @return BLE_ERROR_NONE on success.
698  */
699  ble_error_t reset(void);
700 
701 protected:
702 
703  /* --- Abstract calls to override --- */
704 
705  /* Derived implementation must call the base class implementation */
706  ble_error_t reset_(void);
707 
708  ble_error_t discoverServices_(
709  ble::connection_handle_t connectionHandle,
711  GattAttribute::Handle_t startHandle,
712  GattAttribute::Handle_t endHandle
713  );
714 
715  ble_error_t launchServiceDiscovery_(
716  ble::connection_handle_t connectionHandle,
719  const UUID &matchingServiceUUID,
720  const UUID &matchingCharacteristicUUIDIn
721  );
722 
723  bool isServiceDiscoveryActive_(void) const;
724 
725  void terminateServiceDiscovery_(void);
726 
727  ble_error_t negotiateAttMtu_(ble::connection_handle_t connection);
728 
729  ble_error_t read_(
730  ble::connection_handle_t connHandle,
731  GattAttribute::Handle_t attributeHandle,
732  uint16_t offset
733  ) const;
734 
735  ble_error_t write_(
737  ble::connection_handle_t connHandle,
738  GattAttribute::Handle_t attributeHandle,
739  size_t length,
740  const uint8_t *value
741  ) const;
742 
743  void onServiceDiscoveryTermination_(
745  );
746 
747  ble_error_t discoverCharacteristicDescriptors_(
748  const DiscoveredCharacteristic& characteristic,
751  );
752 
753  bool isCharacteristicDescriptorDiscoveryActive_(
754  const DiscoveredCharacteristic& characteristic
755  ) const;
756 
757  void terminateCharacteristicDescriptorDiscovery_(
758  const DiscoveredCharacteristic& characteristic
759  );
760 
761 protected:
762  GattClient() : eventHandler(NULL)
763  {
764  /* Empty */
765  }
766 
767  /* Entry points for the underlying stack to report events back to the user. */
768 public:
769  /**
770  * Forward an attribute read event to all registered handlers.
771  *
772  * @attention This function is meant to be called from the vendor
773  * implementation when an attribute read event occurs.
774  *
775  * @param[in] params Attribute read event to pass to the registered handlers.
776  */
778  {
779  onDataReadCallbackChain(params);
780  }
781 
782  /**
783  * Forward an attribute written event to all registered handlers.
784  *
785  * @attention This function is meant to be called from the vendor
786  * implementation when an attribute written event occurs.
787  *
788  * @param[in] params Attribute written event to pass to the registered
789  * handlers.
790  */
792  {
793  onDataWriteCallbackChain(params);
794  }
795 
796  /**
797  * Forward a handle value notification or indication event to all registered
798  * handlers.
799  *
800  * @attention This function is meant to be called from the vendor
801  * implementation when a notification or indication event is available.
802  *
803  * @param[in] params Notification or Indication event to pass to the
804  * registered handlers.
805  */
807  {
808  if (onHVXCallbackChain) {
809  onHVXCallbackChain(params);
810  }
811  }
812 
813 protected:
814  /**
815  * Event handler provided by the application.
816  */
818 
819  /**
820  * Callchain containing all registered event handlers for data read
821  * events.
822  */
824 
825  /**
826  * Callchain containing all registered event handlers for data write
827  * events.
828  */
830 
831  /**
832  * Callchain containing all registered event handlers for update
833  * events.
834  */
836 
837  /**
838  * Callchain containing all registered event handlers for shutdown
839  * events.
840  */
842 
843 private:
844  /* Disallow copy and assignment. */
845  GattClient(const GattClient &);
846  GattClient& operator=(const GattClient &);
847 };
848 
849 /**
850  * @}
851  * @}
852  * @}
853  */
854 
855 #if !defined(DOXYGEN_ONLY)
856 } // namespace interface
857 } // namespace ble
858 
859 using ble::impl::GattClient;
860 #endif
861 
862 #endif /* ifndef MBED_GATT_CLIENT_H__ */
EventHandler * eventHandler
Event handler provided by the application.
Definition: GattClient.h:817
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:677
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:663
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:614
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:835
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
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
WriteCallbackChain_t & onDataWritten()
Get the callchain of attribute write event handlers.
Definition: GattClient.h:523
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:633
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:841
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
Reserved UUID.
Definition: blecommon.h:38
void onShutdown(T *objPtr, void(T::*memberPtr)(const GattClient *))
Register a shutdown event handler.
Definition: GattClient.h:649
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:791
ReadCallbackChain_t onDataReadCallbackChain
Callchain containing all registered event handlers for data read events.
Definition: GattClient.h:823
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:829
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:806
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:777
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.