Rtos API example

Embed: (wiki syntax)

« Back to documentation index

GattClient Class Reference

Define procedures required for interacting with a distant GATT server. More...

#include <GattClient.h>

Inherited by GenericGattClient.

Public Types

enum  WriteOp_t { GATT_OP_WRITE_REQ = 0x01, GATT_OP_WRITE_CMD = 0x02 }
 

GATT write operations.

More...
typedef
FunctionPointerWithContext
< const GattReadCallbackParams * > 
ReadCallback_t
 Attribute read event handler.
typedef
CallChainOfFunctionPointersWithContext
< const GattReadCallbackParams * > 
ReadCallbackChain_t
 Callchain of attribute read event handlers.
typedef
FunctionPointerWithContext
< const
GattWriteCallbackParams * > 
WriteCallback_t
 Attribute write event handler.
typedef
CallChainOfFunctionPointersWithContext
< const
GattWriteCallbackParams * > 
WriteCallbackChain_t
 Callchain of attribute write event handlers.
typedef
FunctionPointerWithContext
< const GattHVXCallbackParams * > 
HVXCallback_t
 Handle value notification/indication event handler.
typedef
CallChainOfFunctionPointersWithContext
< const GattHVXCallbackParams * > 
HVXCallbackChain_t
 Callchain of handle value notification/indication event handlers.
typedef
FunctionPointerWithContext
< const GattClient * > 
GattClientShutdownCallback_t
 Shutdown event handler.
typedef
CallChainOfFunctionPointersWithContext
< const GattClient * > 
GattClientShutdownCallbackChain_t
 Callchain of shutdown event handlers.

Public Member Functions

virtual ble_error_t launchServiceDiscovery (Gap::Handle_t connectionHandle, ServiceDiscovery::ServiceCallback_t sc=NULL, ServiceDiscovery::CharacteristicCallback_t cc=NULL, const UUID &matchingServiceUUID=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), const UUID &matchingCharacteristicUUIDIn=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN))
 Launch the service and characteristic discovery procedure of a GATT server peer.
virtual ble_error_t discoverServices (Gap::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.
virtual ble_error_t discoverServices (Gap::Handle_t connectionHandle, ServiceDiscovery::ServiceCallback_t callback, GattAttribute::Handle_t startHandle, GattAttribute::Handle_t endHandle)
 Launch the service discovery procedure of a GATT server peer.
virtual bool isServiceDiscoveryActive (void) const
 Check if the service discovery procedure is currently active.
virtual void terminateServiceDiscovery (void)
 Terminate all ongoing service discovery procedures.
virtual ble_error_t read (Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const
 Initiate the read procedure of an attribute handle.
virtual ble_error_t write (GattClient::WriteOp_t cmd, Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, size_t length, const uint8_t *value) const
 Initiate a write procedure on an attribute value.
void onDataRead (ReadCallback_t callback)
 Register an attribute read event handler.
ReadCallbackChain_tonDataRead ()
 Get the callchain of attribute read event handlers.
void onDataWritten (WriteCallback_t callback)
 Register an attribute write event handler.
WriteCallbackChain_tonDataWritten ()
 Get the callchain of attribute write event handlers.
 MBED_DEPRECATED ("Use GattServer::onDataWritten()") void onDataWrite(WriteCallback_t callback)
 Register an attribute write event handler.
virtual void onServiceDiscoveryTermination (ServiceDiscovery::TerminationCallback_t callback)
 Register a service discovery termination event handler.
virtual ble_error_t discoverCharacteristicDescriptors (const DiscoveredCharacteristic &characteristic, const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &discoveryCallback, const CharacteristicDescriptorDiscovery::TerminationCallback_t &terminationCallback)
 Initiate the descriptor discovery procedure for a given characteristic.
virtual bool isCharacteristicDescriptorDiscoveryActive (const DiscoveredCharacteristic &characteristic) const
 Query status of the descriptor discovery procedure for a given characteristic.
virtual void terminateCharacteristicDescriptorDiscovery (const DiscoveredCharacteristic &characteristic)
 Terminate an ongoing characteristic descriptor discovery procedure.
void onHVX (HVXCallback_t callback)
 Register an handler for Handle Value Notification/Indication events.
void onShutdown (const GattClientShutdownCallback_t &callback)
 Register a shutdown event handler.
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const GattClient *))
 Register a shutdown event handler.
GattClientShutdownCallbackChain_tonShutdown ()
 Get the callchain of shutdown event handlers.
HVXCallbackChain_tonHVX ()
 provide access to the callchain of HVX callbacks.
virtual ble_error_t reset (void)
 Reset the state of the GattClient instance.
void processReadResponse (const GattReadCallbackParams *params)
 Forward an attribute read event to all registered handlers.
void processWriteResponse (const GattWriteCallbackParams *params)
 Forward an attribute written event to all registered handlers.
void processHVXEvent (const GattHVXCallbackParams *params)
 Forward a handle value notification or indication event to all registered handlers.

Protected Attributes

ReadCallbackChain_t onDataReadCallbackChain
 Callchain containing all registered event handlers for data read events.
WriteCallbackChain_t onDataWriteCallbackChain
 Callchain containing all registered event handlers for data write events.
HVXCallbackChain_t onHVXCallbackChain
 Callchain containing all registered event handlers for update events.
GattClientShutdownCallbackChain_t shutdownCallChain
 Callchain containing all registered event handlers for shutdown events.

Detailed Description

Define procedures required for interacting with a distant GATT server.

Discovery procedures

A GATT server hosts a fixed set of services. These services are a logical composition of characteristics that may be discovered, read, written or also broadcast their state to a connected client. These characteristics may also contain metainformation named characteristic descriptors. A characteristic descriptor may be used to indicate the unit used for a characteristic value, describe in a textual form the characterisic purpose or allow a client to register for notification of updates of the characteristic value.

Prior to any interaction with server characteristic, a GATT client discovers the layout of the services and characteristics present on the server.

The layout of the descriptors of a characteristic may also be issued to as an extra discovery step.

Attribute manipulation

As a result of the discovery process, the client can start interacting with the characteristic discovered. Depending on the characteristic properties (acquired during discovery), a client can read or write the value of a given characteristic.

Mbed BLE abstracts most read and write operations to offer a single API that can be used to read or write characteristics values. Application code does not have to handle the fragmentation/reassembly process necessary if the attribute value to transported cannot fit in a single data packet.

Server Initiated events

If a characteristic has to notify or indicate a property set; then, a client may register to a notification or indication from the characteristic. When the server updates the characteristic value, the server can forward the new value to the registered clients. The notification/indication mechanism prevents polling from the client and therefore minimize the transactions involved between a client and a server.

Registration is made by writing the Client Characteristic Configuration Descriptor, which is present in the characteristic if the notify or indicate properties are set. The client discovers that descriptor if it intends to register to server initiated events.

Definition at line 84 of file GattClient.h.


Member Typedef Documentation

Shutdown event handler.

See also:
GattClient::onShutdown().

Definition at line 159 of file GattClient.h.

Callchain of shutdown event handlers.

See also:
to GattClient::onShutown().

Definition at line 168 of file GattClient.h.

Handle value notification/indication event handler.

See also:
to GattClient::onHVX().

Definition at line 143 of file GattClient.h.

Callchain of handle value notification/indication event handlers.

See also:
GattClient::onHVX().

Definition at line 151 of file GattClient.h.

Attribute read event handler.

See also:
GattClient::onDataRead().

Definition at line 92 of file GattClient.h.

Callchain of attribute read event handlers.

Definition at line 98 of file GattClient.h.

Attribute write event handler.

See also:
GattClient::onDataWrite().

Definition at line 127 of file GattClient.h.

Callchain of attribute write event handlers.

See also:
GattClient::onDataWrite().

Definition at line 135 of file GattClient.h.


Member Enumeration Documentation

enum WriteOp_t

GATT write operations.

Enumerator:
GATT_OP_WRITE_REQ 

Write request.

It is used to request the server to write the value of an attribute and acknowledge that this has been achieved in a Write Response.

GATT_OP_WRITE_CMD 

Write command.

It is used to request the server to write the value of an attribute. The server does not acknowledge the status of the operation.

Definition at line 103 of file GattClient.h.


Member Function Documentation

virtual ble_error_t discoverCharacteristicDescriptors ( const DiscoveredCharacteristic characteristic,
const CharacteristicDescriptorDiscovery::DiscoveryCallback_t discoveryCallback,
const CharacteristicDescriptorDiscovery::TerminationCallback_t terminationCallback 
) [virtual]

Initiate the descriptor discovery procedure for a given characteristic.

When a descriptor is discovered the discovered descriptor is forwarded to discoveryCallback. After the discovery of all the descriptors, the procedure ends and send a descriptor discovery termination event to termination callback.

Application code may monitor the discovery process by querying its status with isCharacteristicDescriptorDiscoveryActive(). It can also end the discovery process by calling terminateCharacteristicDescriptorDiscovery().

Parameters:
[in]characteristicThe characteristic owning the descriptors to discover.
[in]discoveryCallbackHandle descriptor discovered events for the duration of the procedure.
[in]terminationCallbackHandle descriptor discovery termination event of the procedure.
Returns:
BLE_ERROR_NONE if the characteristic descriptor discovery procedure has been launched successfully otherwise an appropriate error.

Reimplemented in GenericGattClient.

Definition at line 580 of file GattClient.h.

virtual ble_error_t discoverServices ( Gap::Handle_t  connectionHandle,
ServiceDiscovery::ServiceCallback_t  callback,
const UUID matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) 
) [virtual]

Launch the service discovery procedure of a GATT server peer.

The procedure invokes the application callback for matching services. The process ends after all the services present on the distant GATT server have been discovered. Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters:
[in]connectionHandleHandle of the connection with the peer GATT server.
[in]callbackService discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]matchingServiceUUIDUUID of the service the caller is interested in. If a service discovered matches this filter, then sc is invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard, which can be used to discover all services present on the peer GATT server.
Returns:
BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Definition at line 276 of file GattClient.h.

virtual ble_error_t discoverServices ( Gap::Handle_t  connectionHandle,
ServiceDiscovery::ServiceCallback_t  callback,
GattAttribute::Handle_t  startHandle,
GattAttribute::Handle_t  endHandle 
) [virtual]

Launch the service discovery procedure of a GATT server peer.

The process ends after all the services present in the attribute range startHandle to endHandle have been discovered.

Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters:
[in]connectionHandleHandle of the connection with the peer GATT server.
[in]callbackService discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]startHandleFirst attribute handle of the discovery range.
[in]endHandleend Lasr attribute handle of the discovery range.
Returns:
BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Definition at line 317 of file GattClient.h.

virtual bool isCharacteristicDescriptorDiscoveryActive ( const DiscoveredCharacteristic characteristic ) const [virtual]

Query status of the descriptor discovery procedure for a given characteristic.

Parameters:
[in]characteristicThe characteristic concerned by the descriptors discovery.
Returns:
true if a descriptors discovery is active for the characteristic in input otherwise false.

Reimplemented in GenericGattClient.

Definition at line 603 of file GattClient.h.

virtual bool isServiceDiscoveryActive ( void   ) const [virtual]

Check if the service discovery procedure is currently active.

Returns:
true if service discovery procedure is active and false otherwise.

Reimplemented in GenericGattClient.

Definition at line 339 of file GattClient.h.

virtual ble_error_t launchServiceDiscovery ( Gap::Handle_t  connectionHandle,
ServiceDiscovery::ServiceCallback_t  sc = NULL,
ServiceDiscovery::CharacteristicCallback_t  cc = NULL,
const UUID matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
const UUID matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) 
) [virtual]

Launch the service and characteristic discovery procedure of a GATT server peer.

The procedure invokes application callbacks for matching services or characteristics. The process ends after all the services and characteristics present on the distant GATT server have been discovered. Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters:
[in]connectionHandleHandle of the connection with the peer GATT server.
[in]scService discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]ccCharacteristic discovered event handler invoked when a matching characteristic has been found. This parameter may be NULL.
[in]matchingServiceUUIDUUID of the service the caller is interested in. If a service discovered matches this filter, then sc is invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, which can be used to discover all services present on the peer GATT server.
[in]matchingCharacteristicUUIDInUUID of the characteristic the caller is interested in. If a characteristic discovered matches this filter, then cc is invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, which can be used to discover all services present on the peer GATT server.
Discovery procedure implementation detail

It is recommended to implement several strategies based on the combination of callbacks and filters passed in input to efficiently realize the discovery procedure:

  • If sc and cc are NULL, then it is not necessay to initiate any discovery, and the termination handlers can be invoked immediately.
  • If matchingServiceUUID is set, then the GATT discover services by service UUID procedure should be used; otherwise, the GATT discover primary services procedure should be used.
  • If cc is NULL, then the discovery process should end after the discovery of the services.
Returns:
BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Reimplemented in GenericGattClient.

Definition at line 228 of file GattClient.h.

MBED_DEPRECATED ( "Use GattServer::onDataWritten()"   )

Register an attribute write event handler.

Parameters:
[in]callbackEvent handler being registered.
Note:
It is possible to remove registered handlers using onDataWritten().detach(callbackToRemove).
Write commands (issued using writeWoResponse) don't generate a response.

Definition at line 538 of file GattClient.h.

void onDataRead ( ReadCallback_t  callback )

Register an attribute read event handler.

Note:
It is possible to unregister a callback using onDataRead().detach(callbackToRemove).
Parameters:
[in]callbackEvent handler being registered.

Definition at line 472 of file GattClient.h.

ReadCallbackChain_t& onDataRead (  )

Get the callchain of attribute read event handlers.

Returns:
A reference to the read event callback chain.
Note:
It is possible to register new handlers using onDataRead().add(callback).
It is possible to unregister an handler by using onDataRead().detach(callback).

Definition at line 488 of file GattClient.h.

void onDataWritten ( WriteCallback_t  callback )

Register an attribute write event handler.

Parameters:
[in]callbackEvent handler being registered.
Note:
It is possible to remove registered handlers using onDataWritten().detach(callbackToRemove).
Write commands (issued using writeWoResponse) don't generate a response.

Definition at line 504 of file GattClient.h.

WriteCallbackChain_t& onDataWritten (  )

Get the callchain of attribute write event handlers.

Returns:
A reference to the data written callbacks chain.
Note:
It is possible to register new handlers by using onDataWritten().add(callback).
It is possible to unregister an handler by using onDataWritten().detach(callback).

Definition at line 520 of file GattClient.h.

void onHVX ( HVXCallback_t  callback )

Register an handler for Handle Value Notification/Indication events.

Parameters:
callbackEvent handler to register.
Note:
It is possible to unregister a callback by using onHVX().detach(callbackToRemove).

Definition at line 637 of file GattClient.h.

HVXCallbackChain_t& onHVX (  )

provide access to the callchain of HVX callbacks.

Returns:
A reference to the HVX callbacks chain.
Note:
It is possible to register callbacks using onHVX().add(callback).
It is possible to unregister callbacks using onHVX().detach(callback).

Definition at line 700 of file GattClient.h.

virtual void onServiceDiscoveryTermination ( ServiceDiscovery::TerminationCallback_t  callback ) [virtual]

Register a service discovery termination event handler.

Parameters:
[in]callbackEvent handler being registered.

Reimplemented in GenericGattClient.

Definition at line 549 of file GattClient.h.

void onShutdown ( T *  objPtr,
void(T::*)(const GattClient *)  memberPtr 
)

Register a shutdown event handler.

The registered handler is invoked when the GattClient instance is about to be shut down.

Parameters:
[in]objPtrInstance that will be used to invoke memberPtr.
[in]memberPtrEvent handler to invoke when a shutdown event is available.

Definition at line 672 of file GattClient.h.

Get the callchain of shutdown event handlers.

Returns:
A reference to the shutdown event callbacks chain.
Note:
onShutdown().add(callback) may be used to register new handlers.
onShutdown().detach(callback) may be used to unregister an handler.

Definition at line 686 of file GattClient.h.

void onShutdown ( const GattClientShutdownCallback_t callback )

Register a shutdown event handler.

The registered handler is invoked when the GattClient instance is about to be shut down.

Parameters:
[in]callbackEvent handler to invoke when a shutdown event is available.
Note:
onShutdown().detach(callback) may be used to unregister a given callback.
See also:
BLE::shutdown()

Definition at line 656 of file GattClient.h.

void processHVXEvent ( const GattHVXCallbackParams params )

Forward a handle value notification or indication event to all registered handlers.

This function is meant to be called from the vendor implementation when a notification or indication event is available.

Parameters:
[in]paramsNotification or Indication event to pass to the registered handlers.

Definition at line 780 of file GattClient.h.

void processReadResponse ( const GattReadCallbackParams params )

Forward an attribute read event to all registered handlers.

This function is meant to be called from the vendor implementation when an attribute read event occurs.

Parameters:
[in]paramsAttribute read event to pass to the registered handlers.

Definition at line 751 of file GattClient.h.

void processWriteResponse ( const GattWriteCallbackParams params )

Forward an attribute written event to all registered handlers.

This function is meant to be called from the vendor implementation when an attribute written event occurs.

Parameters:
[in]paramsAttribute written event to pass to the registered handlers.

Definition at line 765 of file GattClient.h.

virtual ble_error_t read ( Gap::Handle_t  connHandle,
GattAttribute::Handle_t  attributeHandle,
uint16_t  offset 
) const [virtual]

Initiate the read procedure of an attribute handle.

Once the attribute value has been read in its entirety, the process issues an attribute read event and passes it to all events handlers registered by onDataRead.

Parameters:
[in]connHandleHandle of the connection used to send the read request.
[in]attributeHandleHandle of the attribute to read data from.
[in]offsetThe offset from the start of the attribute value to be read.
Returns:
BLE_ERROR_NONE if read procedure successfully started.
Implementation notes:

Reading the attribute value in its entirety may involve sending several GATT requests to the peer. The following algorithm may be used to implement the process:

If the offset is equal to 0, then send a read request; otherwise, send a read blob request at the specified offset.

While the attribute data in the response are MTU - 1 long:

  • Concat the response to the value containing the previous responses.
  • Increment the value of the offset by MTU - 1.
  • Send a read blob request with the updated offset.

Finally, concat the last response with the value containing all the previous responses and forward that value to the event handlers.

Reimplemented in GenericGattClient.

Definition at line 390 of file GattClient.h.

virtual ble_error_t reset ( void   ) [virtual]

Reset the state of the GattClient instance.

Prior to any state modification, shutdown event handlers are notified that the GattClient instance is about to be shut down. Then, running procedures end. Finally, the state of the instance is reset.

implementation note

This function is meant to be overridden in the platform-specific subclass. Nevertheless, the subclass only resets its state and not the data held in GattClient members. This is achieved by a call to GattClient::reset() from the subclass' reset() implementation.

Returns:
BLE_ERROR_NONE on success.

Reimplemented in GenericGattClient.

Definition at line 722 of file GattClient.h.

virtual void terminateCharacteristicDescriptorDiscovery ( const DiscoveredCharacteristic characteristic ) [virtual]

Terminate an ongoing characteristic descriptor discovery procedure.

If the procedure is active, then it ends, and the termination handler associated with the procedure is called.

Parameters:
[in]characteristicThe characteristic containing the descriptors being discovered.

Reimplemented in GenericGattClient.

Definition at line 621 of file GattClient.h.

virtual void terminateServiceDiscovery ( void   ) [virtual]

Terminate all ongoing service discovery procedures.

It results in an invocation of the service discovery termination handler registered with onServiceDiscoveryTermination().

Reimplemented in GenericGattClient.

Definition at line 352 of file GattClient.h.

virtual ble_error_t write ( GattClient::WriteOp_t  cmd,
Gap::Handle_t  connHandle,
GattAttribute::Handle_t  attributeHandle,
size_t  length,
const uint8_t *  value 
) const [virtual]

Initiate a write procedure on an attribute value.

If cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation is reported to the event handlers registered through onDataWritten().

Parameters:
[in]cmdType of the write procedure used. If GATT_OP_WRITE_CMD is set, then value length is not greater than the size of the mtu of connHandle minus three.
[in]connHandleHandle of the connection used to send the write request or command.
[in]attributeHandleHandle of the attribute value to write.
[in]lengthNumber of bytes present in value.
[in]valueData buffer to write to attributeHandle.
Returns:
BLE_ERROR_NONE if the write procedure successfully started.
Implementation notes:

If the operation is a write command, then an implementation uses the GATT write without response procedure and an error is returned if the data buffer to write is larger than the size of the MTU - 3.

If the operation is a write command and the size of the data buffer to write is less than than the size of the MTU - 3, then the ATT write request procedure is used, and the response is reported to the handlers listening for write response.

Otherwise, the data buffer to write is divided in chunks with a maximum size of MTU - 5. Those chunks are sent sequentially to the peer in ATT prepare write requests. If an error response is received during the process, the procedure ends immediately, the prepared write is discarded and an error is reported to the application handlers. Once all the chunks have been sent, the transaction is completed by sending an execute write request to the peer. The peer response is forwarded to the application handlers.

Reimplemented in GenericGattClient.

Definition at line 442 of file GattClient.h.


Field Documentation

Callchain containing all registered event handlers for data read events.

Definition at line 792 of file GattClient.h.

Callchain containing all registered event handlers for data write events.

Definition at line 798 of file GattClient.h.

Callchain containing all registered event handlers for update events.

Definition at line 804 of file GattClient.h.

Callchain containing all registered event handlers for shutdown events.

Definition at line 810 of file GattClient.h.