Construct and operates a GATT server. More...
#include <GattServer.h>
Data Structures | |
struct | EventHandler |
Definition of the general handler of GattServer related events. More... | |
Public Types | |
typedef FunctionPointerWithContext< unsigned > | DataSentCallback_t |
Event handler invoked when the server has sent data to a client. More... | |
typedef CallChainOfFunctionPointersWithContext< unsigned > | DataSentCallbackChain_t |
Callchain of DataSentCallback_t objects. More... | |
typedef FunctionPointerWithContext< const GattWriteCallbackParams * > | DataWrittenCallback_t |
Event handler invoked when the client has written an attribute of the server. More... | |
typedef CallChainOfFunctionPointersWithContext< const GattWriteCallbackParams * > | DataWrittenCallbackChain_t |
Callchain of DataWrittenCallback_t objects. More... | |
typedef FunctionPointerWithContext< const GattReadCallbackParams * > | DataReadCallback_t |
Event handler invoked when the client has read an attribute of the server. More... | |
typedef CallChainOfFunctionPointersWithContext< const GattReadCallbackParams * > | DataReadCallbackChain_t |
Callchain of DataReadCallback_t. More... | |
typedef FunctionPointerWithContext< const GattServer * > | GattServerShutdownCallback_t |
Event handler invoked when the GattServer is reset. More... | |
typedef CallChainOfFunctionPointersWithContext< const GattServer * > | GattServerShutdownCallbackChain_t |
Callchain of GattServerShutdownCallback_t. More... | |
typedef FunctionPointerWithContext< GattAttribute::Handle_t > | EventCallback_t |
Event handler that handles subscription to characteristic updates, unsubscription from characteristic updates and notification confirmation. 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 | reset () |
Shut down the GattServer instance. More... | |
ble_error_t | addService (GattService &service) |
Add a service declaration to the local attribute server table. More... | |
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. More... | |
ble_error_t | read (ble::connection_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. More... | |
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. More... | |
ble_error_t | write (ble::connection_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. More... | |
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. More... | |
ble_error_t | areUpdatesEnabled (ble::connection_handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) |
Determine if an identified client has subscribed to notifications or indications of a given characteristic. More... | |
bool | isOnDataReadAvailable () const |
Indicate if the underlying stack emit events when an attribute is read by a client. More... | |
void | onDataSent (const DataSentCallback_t &callback) |
Add an event handler that monitors emission of characteristic value updates. More... | |
template<typename T > | |
void | onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count)) |
Add an event handler that monitors emission of characteristic value updates. More... | |
DataSentCallbackChain_t & | onDataSent () |
Access the callchain of data sent event handlers. More... | |
void | onDataWritten (const DataWrittenCallback_t &callback) |
Set an event handler that is called after a connected peer has written an attribute. More... | |
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. More... | |
DataWrittenCallbackChain_t & | onDataWritten () |
Access the callchain of data written event handlers. More... | |
ble_error_t | onDataRead (const DataReadCallback_t &callback) |
Set an event handler that monitors attribute reads from connected clients. More... | |
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. More... | |
DataReadCallbackChain_t & | onDataRead () |
Access the callchain of data read event handlers. More... | |
void | onShutdown (const GattServerShutdownCallback_t &callback) |
Set an event handler that monitors shutdown or reset of the GattServer. More... | |
template<typename T > | |
void | onShutdown (T *objPtr, void(T::*memberPtr)(const GattServer *)) |
Set an event handler that monitors shutdown or reset of the GattServer. More... | |
GattServerShutdownCallbackChain_t & | onShutdown () |
Access the callchain of shutdown event handlers. More... | |
void | onUpdatesEnabled (EventCallback_t callback) |
Set up an event handler that monitors subscription to characteristic updates. More... | |
void | onUpdatesDisabled (EventCallback_t callback) |
Set up an event handler that monitors unsubscription from characteristic updates. More... | |
void | onConfirmationReceived (EventCallback_t callback) |
Set up an event handler that monitors notification acknowledgment. More... | |
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:
Definition at line 102 of file GattServer.h.
typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t |
Event handler invoked when the client has read an attribute of the server.
Definition at line 247 of file GattServer.h.
typedef FunctionPointerWithContext<unsigned> DataSentCallback_t |
Event handler invoked when the server has sent data to a client.
Definition at line 214 of file GattServer.h.
typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t |
Callchain of DataSentCallback_t objects.
Definition at line 222 of file GattServer.h.
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t |
Event handler invoked when the client has written an attribute of the server.
Definition at line 231 of file GattServer.h.
typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t |
Callchain of DataWrittenCallback_t objects.
Definition at line 239 of file GattServer.h.
Event handler that handles subscription to characteristic updates, unsubscription from characteristic updates and notification confirmation.
Definition at line 279 of file GattServer.h.
typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t |
Event handler invoked when the GattServer is reset.
Definition at line 263 of file GattServer.h.
Callchain of GattServerShutdownCallback_t.
Definition at line 271 of file GattServer.h.
ble_error_t addService | ( | GattService & | service | ) |
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.
[in] | service | The service to be added; attribute handle of services, characteristic and characteristic descriptors are updated by the process. |
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.
[in] | characteristic | The characteristic. |
[out] | enabledP | Upon return, *enabledP is true if updates are enabled for a connected client; otherwise, *enabledP is false. |
ble_error_t areUpdatesEnabled | ( | ble::connection_handle_t | connectionHandle, |
const GattCharacteristic & | characteristic, | ||
bool * | enabledP | ||
) |
Determine if an identified client has subscribed to notifications or indications of a given characteristic.
[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 of characteristic ; otherwise, *enabledP is false. |
bool isOnDataReadAvailable | ( | ) | const |
Indicate if the underlying stack emit events when an attribute is read by a client.
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.
[in] | callback | Event handler being registered. |
ble_error_t onDataRead | ( | const DataReadCallback_t & | callback | ) |
Set an event handler that monitors attribute reads from connected clients.
[in] | callback | Event handler being registered. |
ble_error_t onDataRead | ( | T * | objPtr, |
void(T::*)(const GattReadCallbackParams *context) | memberPtr | ||
) |
Set an event handler that monitors attribute reads from connected clients.
[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 601 of file GattServer.h.
DataReadCallbackChain_t& onDataRead | ( | ) |
Access the callchain of data read event handlers.
void onDataSent | ( | const DataSentCallback_t & | callback | ) |
Add an event handler that monitors emission of characteristic value updates.
[in] | callback | Event handler being registered. |
void onDataSent | ( | T * | objPtr, |
void(T::*)(unsigned count) | memberPtr | ||
) |
Add an event handler that monitors emission of characteristic value updates.
[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 506 of file GattServer.h.
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.
[in] | callback | The event handler being registered. |
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.
[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 545 of file GattServer.h.
DataWrittenCallbackChain_t& onDataWritten | ( | ) |
Access the callchain of data written event handlers.
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().
[in] | callback | Event handler being registered. |
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().
[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 655 of file GattServer.h.
GattServerShutdownCallbackChain_t& onShutdown | ( | ) |
Access the callchain of shutdown event handlers.
void onUpdatesDisabled | ( | EventCallback_t | callback | ) |
Set up an event handler that monitors unsubscription from characteristic updates.
[in] | callback | Event handler being registered. |
void onUpdatesEnabled | ( | EventCallback_t | callback | ) |
Set up an event handler that monitors subscription to characteristic updates.
[in] | callback | Event handler being registered. |
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.
[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. |
ble_error_t read | ( | ble::connection_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.
The connection handle allows application code to read the value of a Client Characteristic Configuration Descriptor for a given connection.
[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. |
ble_error_t reset | ( | ) |
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.
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 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.
[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. |
ble_error_t write | ( | ble::connection_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.
The connection handle parameter allows application code to direct notification or indication resulting from the update to a specific client.
[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. |