Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
GattServer Class Reference
[Server]
Construct and operates a GATT server. More...
#include <GattServer.h>
Public Types | |
typedef FunctionPointerWithContext < unsigned > | DataSentCallback_t |
Event handler invoked when the server has sent data to a client. | |
typedef CallChainOfFunctionPointersWithContext < unsigned > | DataSentCallbackChain_t |
Callchain of DataSentCallback_t objects. | |
typedef FunctionPointerWithContext < const GattWriteCallbackParams * > | DataWrittenCallback_t |
Event handler invoked when the client has written an attribute of the server. | |
typedef CallChainOfFunctionPointersWithContext < const GattWriteCallbackParams * > | DataWrittenCallbackChain_t |
Callchain of DataWrittenCallback_t objects. | |
typedef FunctionPointerWithContext < const GattReadCallbackParams * > | DataReadCallback_t |
Event handler invoked when the client has read an attribute of the server. | |
typedef CallChainOfFunctionPointersWithContext < const GattReadCallbackParams * > | DataReadCallbackChain_t |
Callchain of DataReadCallback_t. | |
typedef FunctionPointerWithContext < const GattServer * > | GattServerShutdownCallback_t |
Event handler invoked when the GattServer is reset. | |
typedef CallChainOfFunctionPointersWithContext < const GattServer * > | GattServerShutdownCallbackChain_t |
Callchain of GattServerShutdownCallback_t. | |
typedef FunctionPointerWithContext < GattAttribute::Handle_t > | EventCallback_t |
Event handler that handles subscription to characteristic updates, unsubscription from characteristic updates and notification confirmation. | |
Public Member Functions | |
virtual ble_error_t | addService (GattService &service) |
Add a service declaration to the local attribute server table. | |
virtual ble_error_t | read (GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) |
Read the value of an attribute present in the local GATT server. | |
virtual ble_error_t | read (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) |
Read the value of an attribute present in the local GATT server. | |
virtual ble_error_t | write (GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false) |
Update the value of an attribute present in the local GATT server. | |
virtual ble_error_t | write (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false) |
Update the value of an attribute present in the local GATT server. | |
virtual ble_error_t | areUpdatesEnabled (const GattCharacteristic &characteristic, bool *enabledP) |
Determine if one of the connected clients has subscribed to notifications or indications of the characteristic in input. | |
virtual ble_error_t | areUpdatesEnabled (Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) |
Determine if an identified client has subscribed to notifications or indications of a given characteristic. | |
virtual bool | isOnDataReadAvailable () const |
Indicate if the underlying stack emit events when an attribute is read by a client. | |
void | onDataSent (const DataSentCallback_t &callback) |
Add an event handler that monitors emission of characteristic value updates. | |
template<typename T > | |
void | onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count)) |
Add an event handler that monitors emission of characteristic value updates. | |
DataSentCallbackChain_t & | onDataSent () |
Access the callchain of data sent event handlers. | |
void | onDataWritten (const DataWrittenCallback_t &callback) |
Set an event handler that is called after a connected peer has written an attribute. | |
template<typename T > | |
void | onDataWritten (T *objPtr, void(T::*memberPtr)(const GattWriteCallbackParams *context)) |
Set an event handler that is called after a connected peer has written an attribute. | |
DataWrittenCallbackChain_t & | onDataWritten () |
Access the callchain of data written event handlers. | |
ble_error_t | onDataRead (const DataReadCallback_t &callback) |
Set an event handler that monitors attribute reads from connected clients. | |
template<typename T > | |
ble_error_t | onDataRead (T *objPtr, void(T::*memberPtr)(const GattReadCallbackParams *context)) |
Set an event handler that monitors attribute reads from connected clients. | |
DataReadCallbackChain_t & | onDataRead () |
Access the callchain of data read event handlers. | |
void | onShutdown (const GattServerShutdownCallback_t &callback) |
Set an event handler that monitors shutdown or reset of the GattServer. | |
template<typename T > | |
void | onShutdown (T *objPtr, void(T::*memberPtr)(const GattServer *)) |
Set an event handler that monitors shutdown or reset of the GattServer. | |
GattServerShutdownCallbackChain_t & | onShutdown () |
Access the callchain of shutdown event handlers. | |
void | onUpdatesEnabled (EventCallback_t callback) |
Set up an event handler that monitors subscription to characteristic updates. | |
void | onUpdatesDisabled (EventCallback_t callback) |
Set up an event handler that monitors unsubscription from characteristic updates. | |
void | onConfirmationReceived (EventCallback_t callback) |
Set up an event handler that monitors notification acknowledgment. | |
virtual ble_error_t | reset (void) |
Shut down the GattServer instance. | |
Protected Member Functions | |
GattServer () | |
Construct a GattServer instance. | |
void | handleDataWrittenEvent (const GattWriteCallbackParams *params) |
Helper function that notifies all registered handlers of an occurrence of a data written event. | |
void | handleDataReadEvent (const GattReadCallbackParams *params) |
Helper function that notifies all registered handlers of an occurrence of a data read event. | |
void | handleEvent (GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) |
Helper function that notifies the registered handler of an occurrence of updates enabled, updates disabled or confirmation received events. | |
void | handleDataSentEvent (unsigned count) |
Helper function that notifies all registered handlers of an occurrence of a data sent event. | |
Protected Attributes | |
uint8_t | serviceCount |
The total number of services added to the ATT table. | |
uint8_t | characteristicCount |
The total number of characteristics added to the ATT table. |
Detailed Description
Construct and operates a GATT server.
A Gatt server is a collection of GattService; these services contain characteristics that a peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
Server
Layout
Application code can add a GattService object to the server with the help of the function addService(). That function registers all the GattCharacteristic enclosed in the service, as well as all the characteristics descriptors (see GattAttribute) these characteristics contain. Service registration assigns a unique handle to the various attributes being part of the service; this handle should be used for subsequent read or write of these components.
There are no primitives defined to remove a single service; however, a call to the function reset() removes all services previously registered in the GattServer.
Characteristic
and attributes access
Values of the characteristic and the characteristic descriptor present in the GattServer must be accessed through the handle assigned to them when the service has been registered; the GattServer class offers several flavors of read() and write() functions that retrieve or mutate an attribute value.
Application code can query if a client has subscribed to a given characteristic's value update by invoking the function areUpdatesEnabled().
Events
The GattServer allows application code to register several event handlers that can be used to monitor client and server activities:
- onDataSent(): Register an event handler that is called when a characteristic value update has been sent to a client.
- onDataWriten(): Register an event handler that is called when a client has written an attribute of the server.
- onDataRead(): Register an event handler that is called when a client has read an attribute of the server.
- onUpdatesEnabled: Register an event handler that is called when a client subscribes to updates of a characteristic.
- onUpdatesDisabled: Register an event handler that is called when a client unsubscribes from updates of a characteristic.
- onConfimationReceived: Register an event handler that is called when a client acknowledges a characteristic value notification.
- Note:
- The term characteristic value update is used to represent Characteristic Value Notification and Characteristic Value Indication when the nature of the server initiated is not relevant.
Definition at line 88 of file GattServer.h.
Member Typedef Documentation
typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t |
Event handler invoked when the client has read an attribute of the server.
- See also:
- onDataRead().
Definition at line 128 of file GattServer.h.
typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams*> DataReadCallbackChain_t |
Callchain of DataReadCallback_t.
- See also:
- onDataRead().
Definition at line 136 of file GattServer.h.
typedef FunctionPointerWithContext<unsigned> DataSentCallback_t |
Event handler invoked when the server has sent data to a client.
- See also:
- onDataSent().
Definition at line 95 of file GattServer.h.
typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t |
Callchain of DataSentCallback_t objects.
- See also:
- onDataSent().
Definition at line 103 of file GattServer.h.
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t |
Event handler invoked when the client has written an attribute of the server.
- See also:
- onDataWritten().
Definition at line 112 of file GattServer.h.
typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t |
Callchain of DataWrittenCallback_t objects.
- See also:
- onDataWritten().
Definition at line 120 of file GattServer.h.
Event handler that handles subscription to characteristic updates, unsubscription from characteristic updates and notification confirmation.
- See also:
- onUpdatesEnabled() onUpdateDisabled() onConfirmationReceived()
Definition at line 160 of file GattServer.h.
typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t |
Event handler invoked when the GattServer is reset.
- See also:
- onShutdown() reset()
Definition at line 144 of file GattServer.h.
Callchain of GattServerShutdownCallback_t.
- See also:
- onShutdown() reset()
Definition at line 152 of file GattServer.h.
Constructor & Destructor Documentation
GattServer | ( | ) | [protected] |
Construct a GattServer instance.
Definition at line 166 of file GattServer.h.
Member Function Documentation
virtual ble_error_t addService | ( | GattService & | service ) | [virtual] |
Add a service declaration to the local attribute server table.
This functions inserts a service declaration in the attribute table followed by the characteristic declarations (including characteristic descriptors) present in service
.
The process assigns a unique attribute handle to all the elements added into the attribute table. This handle is an ID that must be used for subsequent interractions with the elements.
- Note:
- There is no mirror function that removes a single service. Application code can remove all the registered services by calling reset().
- Attention:
- Service, characteristics and descriptors objects registered within the GattServer must remain reachable until reset() is called.
- Parameters:
-
[in] service The service to be added; attribute handle of services, characteristic and characteristic descriptors are updated by the process.
- Returns:
- BLE_ERROR_NONE if the service was successfully added.
Definition at line 207 of file GattServer.h.
virtual ble_error_t areUpdatesEnabled | ( | const GattCharacteristic & | characteristic, |
bool * | enabledP | ||
) | [virtual] |
Determine if one of the connected clients has subscribed to notifications or indications of the characteristic in input.
- Parameters:
-
[in] characteristic The characteristic. [out] enabledP Upon return, *enabledP is true if updates are enabled for a connected client; otherwise, *enabledP is false.
- Returns:
- BLE_ERROR_NONE if the connection and handle are found. False otherwise.
Definition at line 367 of file GattServer.h.
virtual ble_error_t areUpdatesEnabled | ( | Gap::Handle_t | connectionHandle, |
const GattCharacteristic & | characteristic, | ||
bool * | enabledP | ||
) | [virtual] |
Determine if an identified client has subscribed to notifications or indications of a given characteristic.
- Parameters:
-
[in] connectionHandle The connection handle. [in] characteristic The characteristic. [out] enabledP Upon return, *enabledP is true if the client identified by connectionHandle
has subscribed to notifications or indications ofcharacteristic
; otherwise, *enabledP is false.
- Returns:
- BLE_ERROR_NONE if the connection and handle are found. False otherwise.
Definition at line 393 of file GattServer.h.
void handleDataReadEvent | ( | const GattReadCallbackParams * | params ) | [protected] |
Helper function that notifies all registered handlers of an occurrence of a data read event.
- Attention:
- Vendor implementation must invoke this function after one of the GattServer attributes has been read.
- Parameters:
-
[in] params The data read parameters passed to the registered handlers.
Definition at line 692 of file GattServer.h.
void handleDataSentEvent | ( | unsigned | count ) | [protected] |
Helper function that notifies all registered handlers of an occurrence of a data sent event.
- Attention:
- Vendor implementation must invoke this function after the emission of a notification or an indication.
- Parameters:
-
[in] count Number of packets sent.
Definition at line 743 of file GattServer.h.
void handleDataWrittenEvent | ( | const GattWriteCallbackParams * | params ) | [protected] |
Helper function that notifies all registered handlers of an occurrence of a data written event.
- Attention:
- Vendor implementation must invoke this function after one of the GattServer attributes has been written.
- Parameters:
-
[in] params The data written parameters passed to the registered handlers.
Definition at line 677 of file GattServer.h.
void handleEvent | ( | GattServerEvents::gattEvent_e | type, |
GattAttribute::Handle_t | attributeHandle | ||
) | [protected] |
Helper function that notifies the registered handler of an occurrence of updates enabled, updates disabled or confirmation received events.
- Attention:
- Vendor implementation must invoke this function when a client subscribes to characteristic updates, unsubscribes from characteristic updates or a notification confirmation has been received.
- Parameters:
-
[in] type The type of event that occurred. [in] attributeHandle The handle of the attribute concerned by the event.
Definition at line 709 of file GattServer.h.
virtual bool isOnDataReadAvailable | ( | ) | const [virtual] |
Indicate if the underlying stack emit events when an attribute is read by a client.
- Attention:
- This function should be overridden to return true if applicable.
- Returns:
- true if onDataRead is supported; false otherwise.
Definition at line 417 of file GattServer.h.
void onConfirmationReceived | ( | EventCallback_t | callback ) |
Set up an event handler that monitors notification acknowledgment.
The event handler is called when a client sends a confirmation that it has correctly received a notification from the server.
- Parameters:
-
[in] callback Event handler being registered.
Definition at line 660 of file GattServer.h.
ble_error_t onDataRead | ( | T * | objPtr, |
void(T::*)(const GattReadCallbackParams *context) | memberPtr | ||
) |
Set an event handler that monitors attribute reads from connected clients.
- Parameters:
-
[in] objPtr Pointer to the instance that is used to invoke the event handler ( memberPtr
).[in] memberPtr Event handler being registered. It is a member function.
Definition at line 551 of file GattServer.h.
DataReadCallbackChain_t& onDataRead | ( | ) |
Access the callchain of data read event handlers.
- Returns:
- A reference to the data read event callbacks chain.
- Note:
- It is possible to register callbacks using onDataRead().add(callback).
- It is possible to unregister callbacks using onDataRead().detach(callback).
Definition at line 574 of file GattServer.h.
ble_error_t onDataRead | ( | const DataReadCallback_t & | callback ) |
Set an event handler that monitors attribute reads from connected clients.
- Parameters:
-
[in] callback Event handler being registered.
- Returns:
- BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; else BLE_ERROR_NONE.
- Note:
- This functionality may not be available on all underlying stacks. Application code may work around that limitation by monitoring read requests instead of read events.
- Attention:
- It is possible to set multiple event handlers. Registered handlers may be removed with onDataRead().detach(callback).
Definition at line 532 of file GattServer.h.
void onDataSent | ( | const DataSentCallback_t & | callback ) |
Add an event handler that monitors emission of characteristic value updates.
- Parameters:
-
[in] callback Event handler being registered.
- Note:
- It is possible to chain together multiple onDataSent callbacks (potentially from different modules of an application).
Definition at line 437 of file GattServer.h.
void onDataSent | ( | T * | objPtr, |
void(T::*)(unsigned count) | memberPtr | ||
) |
Add an event handler that monitors emission of characteristic value updates.
- Parameters:
-
[in] objPtr Pointer to the instance that is used to invoke the event handler. [in] memberPtr Event handler being registered. It is a member function.
Definition at line 452 of file GattServer.h.
DataSentCallbackChain_t& onDataSent | ( | ) |
Access the callchain of data sent event handlers.
- Returns:
- A reference to the DATA_SENT event callback chain.
Definition at line 462 of file GattServer.h.
void onDataWritten | ( | T * | objPtr, |
void(T::*)(const GattWriteCallbackParams *context) | memberPtr | ||
) |
Set an event handler that is called after a connected peer has written an attribute.
- Parameters:
-
[in] objPtr Pointer to the instance that is used to invoke the event handler ( memberPtr
).[in] memberPtr Event handler being registered. It is a member function.
Definition at line 491 of file GattServer.h.
void onDataWritten | ( | const DataWrittenCallback_t & | callback ) |
Set an event handler that is called after a connected peer has written an attribute.
- Parameters:
-
[in] callback The event handler being registered.
- Attention:
- It is possible to set multiple event handlers. Registered handlers may be removed with onDataWritten().detach(callback).
Definition at line 476 of file GattServer.h.
DataWrittenCallbackChain_t& onDataWritten | ( | ) |
Access the callchain of data written event handlers.
- Returns:
- A reference to the data written event callbacks chain.
- Note:
- It is possible to register callbacks using onDataWritten().add(callback).
- It is possible to unregister callbacks using onDataWritten().detach(callback).
Definition at line 509 of file GattServer.h.
void onShutdown | ( | T * | objPtr, |
void(T::*)(const GattServer *) | memberPtr | ||
) |
Set an event handler that monitors shutdown or reset of the GattServer.
The event handler is invoked when the GattServer instance is about to be shut down. This can result of a call to reset() or BLE::reset().
- Parameters:
-
[in] objPtr Pointer to the instance that is used to invoke the event handler ( memberPtr
).[in] memberPtr Event handler being registered. It is a member function.
Definition at line 609 of file GattServer.h.
void onShutdown | ( | const GattServerShutdownCallback_t & | callback ) |
Set an event handler that monitors shutdown or reset of the GattServer.
The event handler is invoked when the GattServer instance is about to be shut down. This can result in a call to reset() or BLE::reset().
- Parameters:
-
[in] callback Event handler being registered.
- Note:
- It is possible to set up multiple shutdown event handlers.
- It is possible to unregister a callback using onShutdown().detach(callback)
Definition at line 592 of file GattServer.h.
GattServerShutdownCallbackChain_t& onShutdown | ( | ) |
Access the callchain of shutdown event handlers.
- Returns:
- A reference to the shutdown event callbacks chain.
- Note:
- It is possible to register callbacks using onShutdown().add(callback).
- It is possible to unregister callbacks using onShutdown().detach(callback).
Definition at line 625 of file GattServer.h.
void onUpdatesDisabled | ( | EventCallback_t | callback ) |
Set up an event handler that monitors unsubscription from characteristic updates.
- Parameters:
-
[in] callback Event handler being registered.
Definition at line 647 of file GattServer.h.
void onUpdatesEnabled | ( | EventCallback_t | callback ) |
Set up an event handler that monitors subscription to characteristic updates.
- Parameters:
-
[in] callback Event handler being registered.
Definition at line 636 of file GattServer.h.
virtual ble_error_t read | ( | GattAttribute::Handle_t | attributeHandle, |
uint8_t | buffer[], | ||
uint16_t * | lengthP | ||
) | [virtual] |
Read the value of an attribute present in the local GATT server.
- Parameters:
-
[in] attributeHandle Handle of the attribute to read. [out] buffer A buffer to hold the value being read. [in,out] lengthP Length of the buffer being supplied. If the attribute value is longer than the size of the supplied buffer, this variable holds upon return the total attribute value length (excluding offset). The application may use this information to allocate a suitable buffer size.
- Returns:
- BLE_ERROR_NONE if a value was read successfully into the buffer.
- Attention:
- read(Gap::Handle_t, GattAttribute::Handle_t, uint8_t *, uint16_t *) must be used to read Client Characteristic Configuration Descriptor (CCCD) because the value of this type of attribute depends on the connection.
Definition at line 234 of file GattServer.h.
virtual ble_error_t read | ( | Gap::Handle_t | connectionHandle, |
GattAttribute::Handle_t | attributeHandle, | ||
uint8_t * | buffer, | ||
uint16_t * | lengthP | ||
) | [virtual] |
Read the value of an attribute present in the local GATT server.
The connection handle allows application code to read the value of a Client Characteristic Configuration Descriptor for a given connection.
- Parameters:
-
[in] connectionHandle Connection handle. [in] attributeHandle Attribute handle for the value attribute of the characteristic. [out] buffer A buffer to hold the value being read. [in,out] lengthP Length of the buffer being supplied. If the attribute value is longer than the size of the supplied buffer, this variable holds upon return the total attribute value length (excluding offset). The application may use this information to allocate a suitable buffer size.
- Returns:
- BLE_ERROR_NONE if a value was read successfully into the buffer.
Definition at line 267 of file GattServer.h.
virtual ble_error_t reset | ( | void | ) | [virtual] |
Shut down the GattServer instance.
This function notifies all event handlers listening for shutdown events that the GattServer is about to be shut down; then it clears all GattServer state.
- Note:
- This function is meant to be overridden in the platform-specific subclass. Overides must call the parent function before any cleanup.
- Returns:
- BLE_ERROR_NONE on success.
Definition at line 761 of file GattServer.h.
virtual ble_error_t write | ( | Gap::Handle_t | connectionHandle, |
GattAttribute::Handle_t | attributeHandle, | ||
const uint8_t * | value, | ||
uint16_t | size, | ||
bool | localOnly = false |
||
) | [virtual] |
Update the value of an attribute present in the local GATT server.
The connection handle parameter allows application code to direct notification or indication resulting from the update to a specific client.
- Parameters:
-
[in] connectionHandle Connection handle. [in] attributeHandle Handle for the value attribute of the characteristic. [in] value A pointer to a buffer holding the new value. [in] size Size of the new value (in bytes). [in] localOnly If this flag is false and the attribute handle written is a characteristic value, then the server sends an update containing the new value to the client identified by the parameter connectionHandle
if it is subscribed to the characteristic's notifications or indications. Otherwise, the update does not generate a single server initiated event.
- Returns:
- BLE_ERROR_NONE if the attribute value has been successfully updated.
Definition at line 337 of file GattServer.h.
virtual ble_error_t write | ( | GattAttribute::Handle_t | attributeHandle, |
const uint8_t * | value, | ||
uint16_t | size, | ||
bool | localOnly = false |
||
) | [virtual] |
Update the value of an attribute present in the local GATT server.
- Parameters:
-
[in] attributeHandle Handle of the attribute to write. [in] value A pointer to a buffer holding the new value. [in] size Size in bytes of the new value (in bytes). [in] localOnly If this flag is false and the attribute handle written is a characteristic value, then the server sends an update containing the new value to all clients that have subscribed to the characteristic's notifications or indications. Otherwise, the update does not generate a single server initiated event.
- Returns:
- BLE_ERROR_NONE if the attribute value has been successfully updated.
Definition at line 299 of file GattServer.h.
Field Documentation
uint8_t characteristicCount [protected] |
The total number of characteristics added to the ATT table.
Definition at line 789 of file GattServer.h.
uint8_t serviceCount [protected] |
The total number of services added to the ATT table.
Definition at line 784 of file GattServer.h.
Generated on Tue Jul 12 2022 12:46:57 by
