diff --git a/connectivity/FEATURE_BLE/include/ble/GattServer.h b/connectivity/FEATURE_BLE/include/ble/GattServer.h index a2f0a9d737..f14126bc02 100644 --- a/connectivity/FEATURE_BLE/include/ble/GattServer.h +++ b/connectivity/FEATURE_BLE/include/ble/GattServer.h @@ -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 ¶ms) { + (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 ¶ms) { + (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 ¶ms) { + (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 ¶ms) { + (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 ¶ms) { + (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 ¶ms) { + (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 + 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 + 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 + 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 + 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) diff --git a/connectivity/FEATURE_BLE/include/ble/gatt/ChainableGattServerEventHandler.h b/connectivity/FEATURE_BLE/include/ble/gatt/ChainableGattServerEventHandler.h index 75bde43bc7..1c9b8a38a2 100644 --- a/connectivity/FEATURE_BLE/include/ble/gatt/ChainableGattServerEventHandler.h +++ b/connectivity/FEATURE_BLE/include/ble/gatt/ChainableGattServerEventHandler.h @@ -42,31 +42,31 @@ public: connectionHandle, attMtuSize); } - void onDataSent(const GattDataSentCallbackParams* params) override { + void onDataSent(const GattDataSentCallbackParams ¶ms) override { execute_on_all(&ble::GattServer::EventHandler::onDataSent, params); } - void onDataWritten(const GattWriteCallbackParams *params) override { + void onDataWritten(const GattWriteCallbackParams ¶ms) override { execute_on_all(&ble::GattServer::EventHandler::onDataWritten, params); } - void onDataRead(const GattReadCallbackParams *params) override { + void onDataRead(const GattReadCallbackParams ¶ms) 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 ¶ms) override { execute_on_all(&ble::GattServer::EventHandler::onUpdatesEnabled, params); } - void onUpdatesDisabled(const GattUpdatesDisabledCallbackParams* params) override { + void onUpdatesDisabled(const GattUpdatesDisabledCallbackParams ¶ms) override { execute_on_all(&ble::GattServer::EventHandler::onUpdatesDisabled, params); } - void onConfirmationReceived(const GattConfirmationReceivedCallbackParams* params) override { + void onConfirmationReceived(const GattConfirmationReceivedCallbackParams ¶ms) override { execute_on_all(&ble::GattServer::EventHandler::onConfirmationReceived, params); } diff --git a/connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h b/connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h index a425c94f7c..ee7740d15a 100644 --- a/connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h +++ b/connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h @@ -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 { /** diff --git a/connectivity/FEATURE_BLE/source/GattServer.cpp b/connectivity/FEATURE_BLE/source/GattServer.cpp index 583903023e..7e169ea684 100644 --- a/connectivity/FEATURE_BLE/source/GattServer.cpp +++ b/connectivity/FEATURE_BLE/source/GattServer.cpp @@ -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 \ No newline at end of file +} // ble diff --git a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp index 8cfd97f64a..d171bb0512 100644 --- a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp +++ b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp @@ -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; diff --git a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h index 32d44005e8..0d60cb6f03 100644 --- a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h +++ b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h @@ -153,6 +153,7 @@ public: void handleEvent( GattServerEvents::gattEvent_e type, + ble::connection_handle_t connHandle, GattAttribute::Handle_t attributeHandle );