diff --git a/connectivity/FEATURE_BLE/include/ble/GattServer.h b/connectivity/FEATURE_BLE/include/ble/GattServer.h index 6b1261f1f51..e3f2b7792ca 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 @@ class GattServer { (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 @@ -401,6 +481,8 @@ class GattServer { * @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); /** @@ -413,6 +495,8 @@ class GattServer { * 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}); @@ -423,6 +507,8 @@ class GattServer { * * @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(); /** @@ -434,6 +520,8 @@ class GattServer { * @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); /** @@ -446,6 +534,8 @@ class GattServer { * 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) @@ -465,6 +555,8 @@ class GattServer { * @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(); /** @@ -485,6 +577,8 @@ class GattServer { * @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); /** @@ -496,6 +590,8 @@ class GattServer { * 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) @@ -515,6 +611,8 @@ class GattServer { * @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(); /** @@ -530,6 +628,8 @@ class GattServer { * @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); /** @@ -544,6 +644,8 @@ class GattServer { * 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}); @@ -560,6 +662,8 @@ class GattServer { * @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(); /** @@ -568,6 +672,8 @@ class GattServer { * * @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); /** @@ -576,6 +682,8 @@ class GattServer { * * @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); /** @@ -586,6 +694,8 @@ class GattServer { * * @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/GattCallbackParamTypes.h b/connectivity/FEATURE_BLE/include/ble/gatt/GattCallbackParamTypes.h index a425c94f7c4..ee7740d15af 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 583903023e5..7e169ea6848 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 a7ca14d5674..9952c39ccb4 100644 --- a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp +++ b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.cpp @@ -878,6 +878,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(); @@ -925,7 +930,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) @@ -936,7 +941,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); } } @@ -1481,37 +1486,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(¶ms); + } + + // Execute deprecated callback if (updatesEnabledCallback) { updatesEnabledCallback(attributeHandle); } break; case GattServerEvents::GATT_EVENT_UPDATES_DISABLED: + + if(eventHandler) { + GattUpdatesDisabledCallbackParams params({ + .connHandle = connHandle, + .attHandle = attributeHandle + }); + eventHandler->onUpdatesDisabled(¶ms); + } + + // Execute deprecated callback if (updatesDisabledCallback) { updatesDisabledCallback(attributeHandle); } break; case GattServerEvents::GATT_EVENT_CONFIRMATION_RECEIVED: + + if(eventHandler) { + GattConfirmationReceivedCallbackParams params({ + .connHandle = connHandle, + .attHandle = attributeHandle + }); + eventHandler->onConfirmationReceived(¶ms); + } + + // Execute deprecated callback if (confirmationReceivedCallback) { confirmationReceivedCallback(attributeHandle); } break; case GattServerEvents::GATT_EVENT_DATA_SENT: + + if(eventHandler) { + GattDataSentCallbackParams params({ + .connHandle = connHandle, + .attHandle = attributeHandle + }); + eventHandler->onDataSent(¶ms); + } + + // 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 32d44005e8f..0d60cb6f039 100644 --- a/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h +++ b/connectivity/FEATURE_BLE/source/cordio/source/GattServerImpl.h @@ -153,6 +153,7 @@ class GattServer : public PalSigningMonitor { void handleEvent( GattServerEvents::gattEvent_e type, + ble::connection_handle_t connHandle, GattAttribute::Handle_t attributeHandle );