Mbed OS Reference
Loading...
Searching...
No Matches
GattClient Class Reference

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

#include <GattClient.h>

Data Structures

struct  EventHandler
 Definition of the general handler of GattClient related events. More...
 

Public Types

enum  WriteOp_t { GATT_OP_WRITE_REQ = 0x01 , GATT_OP_WRITE_CMD = 0x02 , GATT_OP_SIGNED_WRITE_CMD = 0x03 }
 GATT write operations. More...
 
typedef FunctionPointerWithContext< const GattReadCallbackParams * > ReadCallback_t
 Attribute read event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const GattReadCallbackParams * > ReadCallbackChain_t
 Callchain of attribute read event handlers. More...
 
typedef FunctionPointerWithContext< const GattWriteCallbackParams * > WriteCallback_t
 Attribute write event handler.ble::WriteCallback_t. More...
 
typedef CallChainOfFunctionPointersWithContext< const GattWriteCallbackParams * > WriteCallbackChain_t
 Callchain of attribute write event handlers. More...
 
typedef FunctionPointerWithContext< const GattHVXCallbackParams * > HVXCallback_t
 Handle value notification/indication event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const GattHVXCallbackParams * > HVXCallbackChain_t
 Callchain of handle value notification/indication event handlers. More...
 
typedef FunctionPointerWithContext< const GattClient * > GattClientShutdownCallback_t
 Shutdown event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const GattClient * > GattClientShutdownCallbackChain_t
 Callchain of shutdown event handlers. More...
 

Public Member Functions

void setEventHandler (EventHandler *handler)
 Assign the event handler implementation that will be used by the module to signal events back to the application. More...
 
ble_error_t launchServiceDiscovery (ble::connection_handle_t connectionHandle, ServiceDiscovery::ServiceCallback_t sc=nullptr, ServiceDiscovery::CharacteristicCallback_t cc=nullptr, 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. More...
 
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. More...
 
ble_error_t discoverServices (ble::connection_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. More...
 
bool isServiceDiscoveryActive () const
 Check if the service discovery procedure is currently active. More...
 
void terminateServiceDiscovery ()
 Terminate all ongoing service discovery procedures. More...
 
ble_error_t read (ble::connection_handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const
 Initiate the read procedure of an attribute handle. More...
 
ble_error_t write (GattClient::WriteOp_t cmd, ble::connection_handle_t connHandle, GattAttribute::Handle_t attributeHandle, size_t length, const uint8_t *value) const
 Initiate a write procedure on an attribute value. More...
 
void onDataRead (ble::ReadCallback_t callback)
 Register an attribute read event handler. More...
 
ble::ReadCallbackChain_tonDataRead ()
 Get the callchain of attribute read event handlers. More...
 
void onDataWritten (ble::WriteCallback_t callback)
 Register an attribute write event handler. More...
 
ble::WriteCallbackChain_tonDataWritten ()
 Get the callchain of attribute write event handlers. More...
 
void onServiceDiscoveryTermination (ServiceDiscovery::TerminationCallback_t callback)
 Register a service discovery termination event handler. More...
 
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. More...
 
bool isCharacteristicDescriptorDiscoveryActive (const DiscoveredCharacteristic &characteristic) const
 Query status of the descriptor discovery procedure for a given characteristic. More...
 
void terminateCharacteristicDescriptorDiscovery (const DiscoveredCharacteristic &characteristic)
 Terminate an ongoing characteristic descriptor discovery procedure. More...
 
ble_error_t negotiateAttMtu (ble::connection_handle_t connection)
 Trigger MTU negotiation. More...
 
void onHVX (HVXCallback_t callback)
 Register an handler for Handle Value Notification/Indication events. More...
 
void onShutdown (const GattClientShutdownCallback_t &callback)
 Register a shutdown event handler. More...
 
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const GattClient *))
 Register a shutdown event handler. More...
 
GattClientShutdownCallbackChain_tonShutdown ()
 Get the callchain of shutdown event handlers. More...
 
HVXCallbackChain_tonHVX ()
 provide access to the callchain of HVX callbacks. More...
 
ble_error_t reset ()
 Reset the state of the GattClient instance. More...
 
void processReadResponse (const GattReadCallbackParams *params)
 Forward an attribute read event to all registered handlers. More...
 
void processWriteResponse (const GattWriteCallbackParams *params)
 Forward an attribute written event to all registered handlers. More...
 
void processHVXEvent (const GattHVXCallbackParams *params)
 Forward a handle value notification or indication event to all registered handlers. More...
 

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 97 of file GattClient.h.

Member Typedef Documentation

◆ ReadCallback_t

Attribute read event handler.

See also
GattClient::onDataRead().
Deprecated:
Use the version in global ble namespace.

Definition at line 143 of file GattClient.h.

◆ ReadCallbackChain_t

Callchain of attribute read event handlers.

Deprecated:
Use the version in global ble namespace.

Definition at line 150 of file GattClient.h.

◆ WriteCallback_t

Attribute write event handler.ble::WriteCallback_t.

See also
GattClient::onDataWrite().
Deprecated:
Use the version in global ble namespace.

Definition at line 189 of file GattClient.h.

◆ WriteCallbackChain_t

Callchain of attribute write event handlers.

See also
GattClient::onDataWrite().
Deprecated:
Use the version in global ble namespace.

Definition at line 198 of file GattClient.h.

◆ HVXCallback_t

Handle value notification/indication event handler.

See also
to GattClient::onHVX().

Definition at line 206 of file GattClient.h.

◆ HVXCallbackChain_t

Callchain of handle value notification/indication event handlers.

See also
GattClient::onHVX().

Definition at line 214 of file GattClient.h.

◆ GattClientShutdownCallback_t

Shutdown event handler.

See also
GattClient::onShutdown().

Definition at line 222 of file GattClient.h.

◆ GattClientShutdownCallbackChain_t

Callchain of shutdown event handlers.

See also
to GattClient::onShutown().

Definition at line 231 of file GattClient.h.

Member Enumeration Documentation

◆ WriteOp_t

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.

GATT_OP_SIGNED_WRITE_CMD 

Signed Write command.

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

Definition at line 155 of file GattClient.h.

Member Function Documentation

◆ setEventHandler()

void setEventHandler ( EventHandler handler)

Assign the event handler implementation that will be used by the module to signal events back to the application.

Parameters
handlerApplication implementation of an EventHandler.

◆ launchServiceDiscovery()

ble_error_t launchServiceDiscovery ( ble::connection_handle_t  connectionHandle,
ServiceDiscovery::ServiceCallback_t  sc = nullptr,
ServiceDiscovery::CharacteristicCallback_t  cc = nullptr,
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.

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.

◆ discoverServices() [1/2]

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.

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.

◆ discoverServices() [2/2]

ble_error_t discoverServices ( ble::connection_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.

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.

◆ isServiceDiscoveryActive()

bool isServiceDiscoveryActive ( ) const

Check if the service discovery procedure is currently active.

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

◆ terminateServiceDiscovery()

void terminateServiceDiscovery ( )

Terminate all ongoing service discovery procedures.

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

◆ read()

ble_error_t read ( ble::connection_handle_t  connHandle,
GattAttribute::Handle_t  attributeHandle,
uint16_t  offset 
) const

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.

◆ write()

ble_error_t write ( GattClient::WriteOp_t  cmd,
ble::connection_handle_t  connHandle,
GattAttribute::Handle_t  attributeHandle,
size_t  length,
const uint8_t *  value 
) const

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.

◆ onDataRead() [1/2]

void onDataRead ( ble::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.

◆ onDataRead() [2/2]

ble::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).

◆ onDataWritten() [1/2]

void onDataWritten ( ble::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.

◆ onDataWritten() [2/2]

ble::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).

◆ onServiceDiscoveryTermination()

void onServiceDiscoveryTermination ( ServiceDiscovery::TerminationCallback_t  callback)

Register a service discovery termination event handler.

Parameters
[in]callbackEvent handler being registered.

◆ discoverCharacteristicDescriptors()

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.

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.

◆ isCharacteristicDescriptorDiscoveryActive()

bool isCharacteristicDescriptorDiscoveryActive ( const DiscoveredCharacteristic characteristic) const

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.

◆ terminateCharacteristicDescriptorDiscovery()

void terminateCharacteristicDescriptorDiscovery ( const DiscoveredCharacteristic characteristic)

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.

◆ negotiateAttMtu()

ble_error_t negotiateAttMtu ( ble::connection_handle_t  connection)

Trigger MTU negotiation.

This might result in a Gap event onAttMtuChange being called if MTU changes.

Note
This does not guarantee a change in MTU size. If size remains unchanged no event will be generated.
Parameters
connectionConnection on which the MTU is to be negotiated.
Returns
BLE_ERROR_NONE if the procedure has been launched successfully otherwise an appropriate error.

◆ onHVX() [1/2]

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).

◆ onShutdown() [1/3]

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()

◆ onShutdown() [2/3]

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 630 of file GattClient.h.

◆ onShutdown() [3/3]

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.

◆ onHVX() [2/2]

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).

◆ reset()

ble_error_t reset ( )

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.

◆ processReadResponse()

void processReadResponse ( const GattReadCallbackParams params)

Forward an attribute read event to all registered handlers.

Attention
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.

◆ processWriteResponse()

void processWriteResponse ( const GattWriteCallbackParams params)

Forward an attribute written event to all registered handlers.

Attention
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.

◆ processHVXEvent()

void processHVXEvent ( const GattHVXCallbackParams params)

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

Attention
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.