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.

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 &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)

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 &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);
     }
 

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 {
 
 /**

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
+} // ble

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;

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
     );