Mistake on this page?
Report an issue in GitHub or email us
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes
GattServer Class Reference

#include <GattServer.h>

Public Types

typedef FunctionPointerWithContext< unsigned > DataSentCallback_t
 
typedef CallChainOfFunctionPointersWithContext< unsigned > DataSentCallbackChain_t
 
typedef FunctionPointerWithContext< const GattWriteCallbackParams * > DataWrittenCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const GattWriteCallbackParams * > DataWrittenCallbackChain_t
 
typedef FunctionPointerWithContext< const GattReadCallbackParams * > DataReadCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const GattReadCallbackParams * > DataReadCallbackChain_t
 
typedef FunctionPointerWithContext< const GattServer * > GattServerShutdownCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const GattServer * > GattServerShutdownCallbackChain_t
 
typedef FunctionPointerWithContext< GattAttribute::Handle_tEventCallback_t
 

Public Member Functions

virtual ble_error_t addService (GattService &service)
 
virtual ble_error_t read (GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP)
 
virtual ble_error_t read (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
 
virtual ble_error_t write (GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
 
virtual ble_error_t write (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
 
virtual ble_error_t areUpdatesEnabled (const GattCharacteristic &characteristic, bool *enabledP)
 
virtual ble_error_t areUpdatesEnabled (Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP)
 
virtual bool isOnDataReadAvailable () const
 
void onDataSent (const DataSentCallback_t &callback)
 
template<typename T >
void onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count))
 
DataSentCallbackChain_tonDataSent ()
 
void onDataWritten (const DataWrittenCallback_t &callback)
 
template<typename T >
void onDataWritten (T *objPtr, void(T::*memberPtr)(const GattWriteCallbackParams *context))
 
DataWrittenCallbackChain_tonDataWritten ()
 
ble_error_t onDataRead (const DataReadCallback_t &callback)
 
template<typename T >
ble_error_t onDataRead (T *objPtr, void(T::*memberPtr)(const GattReadCallbackParams *context))
 
DataReadCallbackChain_tonDataRead ()
 
void onShutdown (const GattServerShutdownCallback_t &callback)
 
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const GattServer *))
 
GattServerShutdownCallbackChain_tonShutdown ()
 
void onUpdatesEnabled (EventCallback_t callback)
 
void onUpdatesDisabled (EventCallback_t callback)
 
void onConfirmationReceived (EventCallback_t callback)
 
virtual ble_error_t reset (void)
 

Protected Member Functions

 GattServer ()
 
void handleDataWrittenEvent (const GattWriteCallbackParams *params)
 
void handleDataReadEvent (const GattReadCallbackParams *params)
 
void handleEvent (GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle)
 
void handleDataSentEvent (unsigned count)
 

Protected Attributes

uint8_t serviceCount
 
uint8_t characteristicCount
 

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:

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.

Member Typedef Documentation

Event handler invoked when the client has read an attribute of the server.

See also
onDataRead().

Callchain of DataReadCallback_t.

See also
onDataRead().

Event handler invoked when the server has sent data to a client.

See also
onDataSent().

Callchain of DataSentCallback_t objects.

See also
onDataSent().

Event handler invoked when the client has written an attribute of the server.

See also
onDataWritten().

Callchain of DataWrittenCallback_t objects.

See also
onDataWritten().

Event handler that handles subscription to characteristic updates, unsubscription from characteristic updates and notification confirmation.

See also
onUpdatesEnabled() onUpdateDisabled() onConfirmationReceived()

Event handler invoked when the GattServer is reset.

See also
onShutdown() reset()

Callchain of GattServerShutdownCallback_t.

See also
onShutdown() reset()

Constructor & Destructor Documentation

GattServer::GattServer ( )
inlineprotected

Construct a GattServer instance.

Member Function Documentation

virtual ble_error_t GattServer::addService ( GattService service)
inlinevirtual

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]serviceThe 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.
virtual ble_error_t GattServer::areUpdatesEnabled ( const GattCharacteristic characteristic,
bool *  enabledP 
)
inlinevirtual

Determine if one of the connected clients has subscribed to notifications or indications of the characteristic in input.

Parameters
[in]characteristicThe characteristic.
[out]enabledPUpon 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.
virtual ble_error_t GattServer::areUpdatesEnabled ( Gap::Handle_t  connectionHandle,
const GattCharacteristic characteristic,
bool *  enabledP 
)
inlinevirtual

Determine if an identified client has subscribed to notifications or indications of a given characteristic.

Parameters
[in]connectionHandleThe connection handle.
[in]characteristicThe characteristic.
[out]enabledPUpon return, *enabledP is true if the client identified by connectionHandle has subscribed to notifications or indications of characteristic; otherwise, *enabledP is false.
Returns
BLE_ERROR_NONE if the connection and handle are found. False otherwise.
void GattServer::handleDataReadEvent ( const GattReadCallbackParams params)
inlineprotected

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]paramsThe data read parameters passed to the registered handlers.
void GattServer::handleDataSentEvent ( unsigned  count)
inlineprotected

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]countNumber of packets sent.
void GattServer::handleDataWrittenEvent ( const GattWriteCallbackParams params)
inlineprotected

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]paramsThe data written parameters passed to the registered handlers.
void GattServer::handleEvent ( GattServerEvents::gattEvent_e  type,
GattAttribute::Handle_t  attributeHandle 
)
inlineprotected

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]typeThe type of event that occurred.
[in]attributeHandleThe handle of the attribute concerned by the event.
virtual bool GattServer::isOnDataReadAvailable ( ) const
inlinevirtual

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.
void GattServer::onConfirmationReceived ( EventCallback_t  callback)
inline

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]callbackEvent handler being registered.
ble_error_t GattServer::onDataRead ( const DataReadCallback_t callback)
inline

Set an event handler that monitors attribute reads from connected clients.

Parameters
[in]callbackEvent 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.
See also
GattCharacteristic::setReadAuthorizationCallback()
isOnDataReadAvailable().
Attention
It is possible to set multiple event handlers. Registered handlers may be removed with onDataRead().detach(callback).
template<typename T >
ble_error_t GattServer::onDataRead ( T *  objPtr,
void(T::*)(const GattReadCallbackParams *context)  memberPtr 
)
inline

Set an event handler that monitors attribute reads from connected clients.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler (memberPtr).
[in]memberPtrEvent handler being registered. It is a member function.
DataReadCallbackChain_t& GattServer::onDataRead ( )
inline

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).
void GattServer::onDataSent ( const DataSentCallback_t callback)
inline

Add an event handler that monitors emission of characteristic value updates.

Parameters
[in]callbackEvent handler being registered.
Note
It is possible to chain together multiple onDataSent callbacks (potentially from different modules of an application).
template<typename T >
void GattServer::onDataSent ( T *  objPtr,
void(T::*)(unsigned count)  memberPtr 
)
inline

Add an event handler that monitors emission of characteristic value updates.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler.
[in]memberPtrEvent handler being registered. It is a member function.
DataSentCallbackChain_t& GattServer::onDataSent ( )
inline

Access the callchain of data sent event handlers.

Returns
A reference to the DATA_SENT event callback chain.
void GattServer::onDataWritten ( const DataWrittenCallback_t callback)
inline

Set an event handler that is called after a connected peer has written an attribute.

Parameters
[in]callbackThe event handler being registered.
Attention
It is possible to set multiple event handlers. Registered handlers may be removed with onDataWritten().detach(callback).
template<typename T >
void GattServer::onDataWritten ( T *  objPtr,
void(T::*)(const GattWriteCallbackParams *context)  memberPtr 
)
inline

Set an event handler that is called after a connected peer has written an attribute.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler (memberPtr).
[in]memberPtrEvent handler being registered. It is a member function.
DataWrittenCallbackChain_t& GattServer::onDataWritten ( )
inline

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).
void GattServer::onShutdown ( const GattServerShutdownCallback_t callback)
inline

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]callbackEvent 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)
template<typename T >
void GattServer::onShutdown ( T *  objPtr,
void(T::*)(const GattServer *)  memberPtr 
)
inline

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]objPtrPointer to the instance that is used to invoke the event handler (memberPtr).
[in]memberPtrEvent handler being registered. It is a member function.
GattServerShutdownCallbackChain_t& GattServer::onShutdown ( )
inline

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).
void GattServer::onUpdatesDisabled ( EventCallback_t  callback)
inline

Set up an event handler that monitors unsubscription from characteristic updates.

Parameters
[in]callbackEvent handler being registered.
void GattServer::onUpdatesEnabled ( EventCallback_t  callback)
inline

Set up an event handler that monitors subscription to characteristic updates.

Parameters
[in]callbackEvent handler being registered.
virtual ble_error_t GattServer::read ( GattAttribute::Handle_t  attributeHandle,
uint8_t  buffer[],
uint16_t *  lengthP 
)
inlinevirtual

Read the value of an attribute present in the local GATT server.

Parameters
[in]attributeHandleHandle of the attribute to read.
[out]bufferA buffer to hold the value being read.
[in,out]lengthPLength 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.
virtual ble_error_t GattServer::read ( Gap::Handle_t  connectionHandle,
GattAttribute::Handle_t  attributeHandle,
uint8_t *  buffer,
uint16_t *  lengthP 
)
inlinevirtual

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]connectionHandleConnection handle.
[in]attributeHandleAttribute handle for the value attribute of the characteristic.
[out]bufferA buffer to hold the value being read.
[in,out]lengthPLength 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.
virtual ble_error_t GattServer::reset ( void  )
inlinevirtual

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.
virtual ble_error_t GattServer::write ( GattAttribute::Handle_t  attributeHandle,
const uint8_t *  value,
uint16_t  size,
bool  localOnly = false 
)
inlinevirtual

Update the value of an attribute present in the local GATT server.

Parameters
[in]attributeHandleHandle of the attribute to write.
[in]valueA pointer to a buffer holding the new value.
[in]sizeSize in bytes of the new value (in bytes).
[in]localOnlyIf 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.
virtual ble_error_t GattServer::write ( Gap::Handle_t  connectionHandle,
GattAttribute::Handle_t  attributeHandle,
const uint8_t *  value,
uint16_t  size,
bool  localOnly = false 
)
inlinevirtual

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]connectionHandleConnection handle.
[in]attributeHandleHandle for the value attribute of the characteristic.
[in]valueA pointer to a buffer holding the new value.
[in]sizeSize of the new value (in bytes).
[in]localOnlyIf 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.

Field Documentation

uint8_t GattServer::characteristicCount
protected

The total number of characteristics added to the ATT table.

uint8_t GattServer::serviceCount
protected

The total number of services added to the ATT table.


The documentation for this class was generated from the following file:
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.