ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update GattServer Callback API 

Update parameters passed to onDataSent, onUpdatesEnabled/Disabled, and onConfirmationReceived callbacks.

Deprecate single-callback-registering functions for event handling in lieu of the new EventHandler-based API.

Introduce new GattServer::EventHandler callback functions to replace the deprecated versions.
pull/13734/head
George Beckstein 2020-10-06 16:48:19 -04:00
parent cda2c8bb8d
commit 9a6d207585
6 changed files with 203 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
connectivity/FEATURE_BLE/include/ble/GattServer.h
View File

@ -20,6 +20,8 @@
#ifndef MBED_GATT_SERVER_H__
#define MBED_GATT_SERVER_H__
#include "platform/mbed_toolchain.h"
#include "ble/common/CallChainOfFunctionPointersWithContext.h"
#include "ble/common/blecommon.h"
@ -118,6 +120,84 @@ public:
(void)connectionHandle;
(void)attMtuSize;
}
/**
* Function invoked when the server has sent data to a client as
* part of a notification/indication.
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*/
virtual void onDataSent(const GattDataSentCallbackParams &params) {
(void)params;
}
/**
* Function invoked when a client writes an attribute
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*/
virtual void onDataWritten(const GattWriteCallbackParams &params) {
(void)params;
}
/**
* Function invoked when a client reads an attribute
*
* @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.
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*
* @see GattCharacteristic::setReadAuthorizationCallback()
* @see isOnDataReadAvailable().
*/
virtual void onDataRead(const GattReadCallbackParams &params) {
(void)params;
}
/**
* Function invoked when the GattServer instance is about
* to be shut down. This can result in a call to reset() or BLE::reset().
*/
virtual void onShutdown(const GattServer &server) {
(void)server;
}
/**
* Function invoked when the client has subscribed to characteristic updates
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*/
virtual void onUpdatesEnabled(const GattUpdatesEnabledCallbackParams &params) {
(void)params;
}
/**
* Function invoked when the client has unsubscribed to characteristic updates
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*/
virtual void onUpdatesDisabled(const GattUpdatesDisabledCallbackParams &params) {
(void)params;
}
/**
* Function invoked when an ACK has been received for an
* indication sent to the client.
*
* @note params has a temporary scope and should be copied by the
* application if needed later
*/
virtual void onConfirmationReceived(const GattConfirmationReceivedCallbackParams &params) {
(void)params;
}
protected:
/**
* Prevent polymorphic deletion and avoid unnecessary virtual destructor
@ -407,6 +487,8 @@ public:
* @note It is possible to chain together multiple onDataSent callbacks
* (potentially from different modules of an application).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onDataSent(const DataSentCallback_t &callback);
/**
@ -419,6 +501,8 @@ public:
* function.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count))
{
onDataSent({objPtr, memberPtr});
@ -429,6 +513,8 @@ public:
*
* @return A reference to the DATA_SENT event callback chain.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
DataSentCallbackChain_t &onDataSent();
/**
@ -440,6 +526,8 @@ public:
* @attention It is possible to set multiple event handlers. Registered
* handlers may be removed with onDataWritten().detach(callback).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onDataWritten(const DataWrittenCallback_t &callback);
/**
@ -452,6 +540,8 @@ public:
* function.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onDataWritten(
T *objPtr,
void (T::*memberPtr)(const GattWriteCallbackParams *context)
@ -471,6 +561,8 @@ public:
* @note It is possible to unregister callbacks using
* onDataWritten().detach(callback).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
DataWrittenCallbackChain_t &onDataWritten();
/**
@ -491,6 +583,8 @@ public:
* @attention It is possible to set multiple event handlers. Registered
* handlers may be removed with onDataRead().detach(callback).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
ble_error_t onDataRead(const DataReadCallback_t &callback);
/**
@ -502,6 +596,8 @@ public:
* function.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
ble_error_t onDataRead(
T *objPtr,
void (T::*memberPtr)(const GattReadCallbackParams *context)
@ -521,6 +617,8 @@ public:
* @note It is possible to unregister callbacks using
* onDataRead().detach(callback).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
DataReadCallbackChain_t &onDataRead();
/**
@ -536,6 +634,8 @@ public:
* @note It is possible to unregister a callback using
* onShutdown().detach(callback)
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onShutdown(const GattServerShutdownCallback_t &callback);
/**
@ -550,6 +650,8 @@ public:
* function.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onShutdown(T *objPtr, void (T::*memberPtr)(const GattServer *))
{
onShutdown({objPtr, memberPtr});
@ -566,6 +668,8 @@ public:
* @note It is possible to unregister callbacks using
* onShutdown().detach(callback).
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
GattServerShutdownCallbackChain_t& onShutdown();
/**
@ -574,6 +678,8 @@ public:
*
* @param[in] callback Event handler being registered.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onUpdatesEnabled(EventCallback_t callback);
/**
@ -582,6 +688,8 @@ public:
*
* @param[in] callback Event handler being registered.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onUpdatesDisabled(EventCallback_t callback);
/**
@ -592,6 +700,8 @@ public:
*
* @param[in] callback Event handler being registered.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Individual callback-registering functions have"
"been replaced by GattServer::setEventHandler. Use that function instead.")
void onConfirmationReceived(EventCallback_t callback);
#if !defined(DOXYGEN_ONLY)

14
connectivity/FEATURE_BLE/include/ble/gatt/ChainableGattServerEventHandler.h
View File

@ -42,31 +42,31 @@ public:
connectionHandle, attMtuSize);
}
void onDataSent(const GattDataSentCallbackParams* params) override {
void onDataSent(const GattDataSentCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onDataSent, params);
}
void onDataWritten(const GattWriteCallbackParams *params) override {
void onDataWritten(const GattWriteCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onDataWritten, params);
}
void onDataRead(const GattReadCallbackParams *params) override {
void onDataRead(const GattReadCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onDataRead, params);
}
void onShutdown(const GattServer *server) override {
void onShutdown(const GattServer &server) override {
execute_on_all(&ble::GattServer::EventHandler::onShutdown, server);
}
void onUpdatesEnabled(const GattUpdatesEnabledCallbackParams* params) override {
void onUpdatesEnabled(const GattUpdatesEnabledCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onUpdatesEnabled, params);
}
void onUpdatesDisabled(const GattUpdatesDisabledCallbackParams* params) override {
void onUpdatesDisabled(const GattUpdatesDisabledCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onUpdatesDisabled, params);
}
void onConfirmationReceived(const GattConfirmationReceivedCallbackParams* params) override {
void onConfirmationReceived(const GattConfirmationReceivedCallbackParams &params) override {
execute_on_all(&ble::GattServer::EventHandler::onConfirmationReceived, params);
}

23
connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h
View File

@ -384,6 +384,29 @@ struct GattHVXCallbackParams {
};
/**
* Gatt Data Sent Attribute related events
*
* Used by `onDataSent`
*/
struct GattDataSentCallbackParams {
/**
* The handle of the connection that triggered the event.
*/
ble::connection_handle_t connHandle;
/**
* Attribute Handle to which the event applies
*/
GattAttribute::Handle_t attHandle;
};
using GattUpdatesEnabledCallbackParams = GattDataSentCallbackParams;
using GattUpdatesDisabledCallbackParams = GattDataSentCallbackParams;
using GattConfirmationReceivedCallbackParams = GattDataSentCallbackParams;
namespace ble {
/**

8
connectivity/FEATURE_BLE/source/GattServer.cpp
View File

@ -139,17 +139,17 @@ GattServer::GattServerShutdownCallbackChain_t& GattServer::onShutdown()
void GattServer::onUpdatesEnabled(EventCallback_t callback)
{
return impl->onUpdatesEnabled(callback);
impl->onUpdatesEnabled(callback);
}
void GattServer::onUpdatesDisabled(EventCallback_t callback)
{
return impl->onUpdatesDisabled(callback);
impl->onUpdatesDisabled(callback);
}
void GattServer::onConfirmationReceived(EventCallback_t callback)
{
return impl->onConfirmationReceived(callback);
impl->onConfirmationReceived(callback);
}
} // ble
} // ble

60
connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp
View File

@ -902,6 +902,11 @@ GapAdvertisingData::Appearance GattServer::getAppearance()
ble_error_t GattServer::reset(ble::GattServer* server)
{
/* Notify that the instance is about to shutdown */
if(eventHandler) {
eventHandler->onShutdown(*server);
}
// Execute callbacks added with deprecated API
shutdownCallChain.call(server);
shutdownCallChain.clear();
@ -950,7 +955,7 @@ void GattServer::cccd_cb(attsCccEvt_t *evt)
GattServerEvents::GATT_EVENT_UPDATES_ENABLED :
GattServerEvents::GATT_EVENT_UPDATES_DISABLED;
getInstance().handleEvent(evt_type, evt->handle);
getInstance().handleEvent(evt_type, evt->hdr.param, evt->handle);
}
void GattServer::att_cb(const attEvt_t *evt)
@ -961,7 +966,7 @@ void GattServer::att_cb(const attEvt_t *evt)
handler->onAttMtuChange(evt->hdr.param, evt->mtu);
}
} else if (evt->hdr.status == ATT_SUCCESS && evt->hdr.event == ATTS_HANDLE_VALUE_CNF) {
getInstance().handleEvent(GattServerEvents::GATT_EVENT_DATA_SENT, evt->handle);
getInstance().handleEvent(GattServerEvents::GATT_EVENT_DATA_SENT, evt->hdr.param, evt->handle);
}
}
@ -1506,37 +1511,88 @@ GattServer::EventHandler *GattServer::getEventHandler()
void GattServer::handleDataWrittenEvent(const GattWriteCallbackParams *params)
{
if(eventHandler) {
eventHandler->onDataWritten(*params);
}
// Execute callbacks added with deprecated API
dataWrittenCallChain.call(params);
}
void GattServer::handleDataReadEvent(const GattReadCallbackParams *params)
{
if(eventHandler) {
eventHandler->onDataRead(*params);
}
// Execute callbacks added with deprecated API
dataReadCallChain.call(params);
}
void GattServer::handleEvent(
GattServerEvents::gattEvent_e type,
ble::connection_handle_t connHandle,
GattAttribute::Handle_t attributeHandle
)
{
switch (type) {
case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
if(eventHandler) {
GattUpdatesEnabledCallbackParams params({
.connHandle = connHandle,
.attHandle = attributeHandle
});
eventHandler->onUpdatesEnabled(params);
}
// Execute deprecated callback
if (updatesEnabledCallback) {
updatesEnabledCallback(attributeHandle);
}
break;
case GattServerEvents::GATT_EVENT_UPDATES_DISABLED:
if(eventHandler) {
GattUpdatesDisabledCallbackParams params({
.connHandle = connHandle,
.attHandle = attributeHandle
});
eventHandler->onUpdatesDisabled(params);
}
// Execute deprecated callback
if (updatesDisabledCallback) {
updatesDisabledCallback(attributeHandle);
}
break;
case GattServerEvents::GATT_EVENT_CONFIRMATION_RECEIVED:
if(eventHandler) {
GattConfirmationReceivedCallbackParams params({
.connHandle = connHandle,
.attHandle = attributeHandle
});
eventHandler->onConfirmationReceived(params);
}
// Execute deprecated callback
if (confirmationReceivedCallback) {
confirmationReceivedCallback(attributeHandle);
}
break;
case GattServerEvents::GATT_EVENT_DATA_SENT:
if(eventHandler) {
GattDataSentCallbackParams params({
.connHandle = connHandle,
.attHandle = attributeHandle
});
eventHandler->onDataSent(params);
}
// Execute deprecated callback
// Called every time a notification or indication has been sent
handleDataSentEvent(1);
break;

1
connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h
View File

@ -153,6 +153,7 @@ public:
void handleEvent(
GattServerEvents::gattEvent_e type,
ble::connection_handle_t connHandle,
GattAttribute::Handle_t attributeHandle
);