Mbed OS 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 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_t & | onDataRead () |
Get the callchain of attribute read event handlers. More... | |
void | onDataWritten (ble::WriteCallback_t callback) |
Register an attribute write event handler. More... | |
ble::WriteCallbackChain_t & | onDataWritten () |
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_t & | onShutdown () |
Get the callchain of shutdown event handlers. More... | |
HVXCallbackChain_t & | onHVX () |
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... | |
Define procedures required for interacting with a distant GATT server.
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.
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.
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.
typedef FunctionPointerWithContext<const GattReadCallbackParams*> ReadCallback_t |
Attribute read event handler.
Definition at line 143 of file GattClient.h.
Callchain of attribute read event handlers.
Definition at line 150 of file GattClient.h.
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> WriteCallback_t |
Attribute write event handler.ble::WriteCallback_t.
Definition at line 189 of file GattClient.h.
Callchain of attribute write event handlers.
Definition at line 198 of file GattClient.h.
typedef FunctionPointerWithContext<const GattHVXCallbackParams*> HVXCallback_t |
Handle value notification/indication event handler.
Definition at line 206 of file GattClient.h.
Callchain of handle value notification/indication event handlers.
Definition at line 214 of file GattClient.h.
typedef FunctionPointerWithContext<const GattClient *> GattClientShutdownCallback_t |
Shutdown event handler.
Definition at line 222 of file GattClient.h.
typedef CallChainOfFunctionPointersWithContext<const GattClient *> GattClientShutdownCallbackChain_t |
Callchain of shutdown event handlers.
Definition at line 231 of file GattClient.h.
enum WriteOp_t |
GATT write operations.
Definition at line 155 of file GattClient.h.
void setEventHandler | ( | EventHandler * | handler | ) |
Assign the event handler implementation that will be used by the module to signal events back to the application.
handler | Application implementation of an EventHandler. |
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().
[in] | connectionHandle | Handle of the connection with the peer GATT server. |
[in] | sc | Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL. |
[in] | cc | Characteristic discovered event handler invoked when a matching characteristic has been found. This parameter may be NULL. |
[in] | matchingServiceUUID | UUID 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] | matchingCharacteristicUUIDIn | UUID 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. |
It is recommended to implement several strategies based on the combination of callbacks and filters passed in input to efficiently realize the discovery procedure:
sc
and cc
are NULL, then it is not necessay to initiate any discovery, and the termination handlers can be invoked immediately.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.cc
is NULL, then the discovery process should end after the discovery of the services.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().
[in] | connectionHandle | Handle of the connection with the peer GATT server. |
[in] | callback | Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL. |
[in] | matchingServiceUUID | UUID 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. |
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().
[in] | connectionHandle | Handle of the connection with the peer GATT server. |
[in] | callback | Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL. |
[in] | startHandle | First attribute handle of the discovery range. |
[in] | endHandle | end Lasr attribute handle of the discovery range. |
bool isServiceDiscoveryActive | ( | ) | const |
Check if the service discovery procedure is currently active.
void terminateServiceDiscovery | ( | ) |
Terminate all ongoing service discovery procedures.
It results in an invocation of the service discovery termination handler registered with onServiceDiscoveryTermination().
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.
[in] | connHandle | Handle of the connection used to send the read request. |
[in] | attributeHandle | Handle of the attribute to read data from. |
[in] | offset | The offset from the start of the attribute value to be read. |
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:
Finally, concat the last response with the value containing all the previous responses and forward that value to the event handlers.
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().
[in] | cmd | Type 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] | connHandle | Handle of the connection used to send the write request or command. |
[in] | attributeHandle | Handle of the attribute value to write. |
[in] | length | Number of bytes present in value . |
[in] | value | Data buffer to write to attributeHandle. |
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.
void onDataRead | ( | ble::ReadCallback_t | callback | ) |
Register an attribute read event handler.
[in] | callback | Event handler being registered. |
ble::ReadCallbackChain_t & onDataRead | ( | ) |
Get the callchain of attribute read event handlers.
void onDataWritten | ( | ble::WriteCallback_t | callback | ) |
Register an attribute write event handler.
[in] | callback | Event handler being registered. |
ble::WriteCallbackChain_t & onDataWritten | ( | ) |
Get the callchain of attribute write event handlers.
void onServiceDiscoveryTermination | ( | ServiceDiscovery::TerminationCallback_t | callback | ) |
Register a service discovery termination event handler.
[in] | callback | Event handler being registered. |
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().
[in] | characteristic | The characteristic owning the descriptors to discover. |
[in] | discoveryCallback | Handle descriptor discovered events for the duration of the procedure. |
[in] | terminationCallback | Handle descriptor discovery termination event of the procedure. |
bool isCharacteristicDescriptorDiscoveryActive | ( | const DiscoveredCharacteristic & | characteristic | ) | const |
Query status of the descriptor discovery procedure for a given characteristic.
[in] | characteristic | The characteristic concerned by the descriptors discovery. |
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.
[in] | characteristic | The characteristic containing the descriptors being discovered. |
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.
connection | Connection on which the MTU is to be negotiated. |
void onHVX | ( | HVXCallback_t | callback | ) |
Register an handler for Handle Value Notification/Indication events.
callback | Event handler to register. |
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.
[in] | callback | Event handler to invoke when a shutdown event is available. |
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.
[in] | objPtr | Instance that will be used to invoke memberPtr . |
[in] | memberPtr | Event handler to invoke when a shutdown event is available. |
Definition at line 630 of file GattClient.h.
GattClientShutdownCallbackChain_t & onShutdown | ( | ) |
Get the callchain of shutdown event handlers.
HVXCallbackChain_t & onHVX | ( | ) |
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.
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.
void processReadResponse | ( | const GattReadCallbackParams * | params | ) |
Forward an attribute read event to all registered handlers.
[in] | params | Attribute read event to pass to the registered handlers. |
void processWriteResponse | ( | const GattWriteCallbackParams * | params | ) |
Forward an attribute written event to all registered handlers.
[in] | params | Attribute written event to pass to the registered handlers. |
void processHVXEvent | ( | const GattHVXCallbackParams * | params | ) |
Forward a handle value notification or indication event to all registered handlers.
[in] | params | Notification or Indication event to pass to the registered handlers. |