Merge pull request #9537 from paul-szczepanek-arm/mtu-events

BLE: Add MTU events

Author: 0xc0170

features/FEATURE_BLE/ble/GattClient.h

@@ -83,6 +83,38 @@
  */
 class GattClient {
 public:
+
+    /**
+     * Definition of the general handler of GattClient related events.
+     */
+    struct EventHandler {
+        /**
+         * Function invoked when the connections changes the ATT_MTU which controls
+         * the maximum size of an attribute that can be read in a single L2CAP packet
+         * which might be fragmented across multiple packets.
+         *
+         * @param connectionHandle The handle of the connection that changed the size.
+         * @param attMtuSize
+         */
+        virtual void onAttMtuChange(
+            ble::connection_handle_t connectionHandle,
+            uint16_t attMtuSize
+        )
+        {
+        }
+    };
+
+    /**
+     * Assign the event handler implementation that will be used by the
+     * module to signal events back to the application.
+     *
+     * @param handler Application implementation of an EventHandler.
+     */
+    void setEventHandler(EventHandler *handler)
+    {
+        eventHandler = handler;
+    }
+
     /**
      * Attribute read event handler.
      *
@@ -635,6 +667,27 @@ class GattClient {
         (void) characteristic;
     }
 
+    /**
+     * Trigger MTU negotiation. This might result in a Gap event onAttMtuChange
+     * being called if MTU changes.
+     *
+     * @note This does not guarantee a change in MTU size. If size remains
+     * unchanged no event will be generated.
+     *
+     * @param connection Connection on which the MTU is to be negotiated.
+     *
+     * @return BLE_ERROR_NONE if the procedure has been launched successfully
+     * otherwise an appropriate error.
+     */
+    virtual ble_error_t negotiateAttMtu(
+        ble::connection_handle_t connection
+    ) {
+        /* Requesting action from porter(s): override this API if this
+           capability is supported. */
+        (void) connection;
+        return BLE_ERROR_NOT_IMPLEMENTED;
+    }
+
     /**
      * Register an handler for Handle Value Notification/Indication events.
      *
@@ -742,7 +795,7 @@ class GattClient {
     }
 
 protected:
-    GattClient()
+    GattClient() : eventHandler(NULL)
     {
         /* Empty */
     }
@@ -794,6 +847,11 @@ class GattClient {
     }
 
 protected:
+    /**
+     * Event handler provided by the application.
+     */
+    EventHandler *eventHandler;
+
     /**
      * Callchain containing all registered event handlers for data read
      * events.

features/FEATURE_BLE/ble/GattServer.h

@@ -87,6 +87,38 @@
  */
 class GattServer {
 public:
+
+    /**
+     * Definition of the general handler of GattServer related events.
+     */
+    struct EventHandler {
+        /**
+         * Function invoked when the connections changes the ATT_MTU which controls
+         * the maximum size of an attribute that can be read in a single L2CAP packet
+         * which might be fragmented across multiple packets.
+         *
+         * @param connectionHandle The handle of the connection that changed the size.
+         * @param attMtuSize
+         */
+        virtual void onAttMtuChange(
+            ble::connection_handle_t connectionHandle,
+            uint16_t attMtuSize
+        )
+        {
+        }
+    };
+
+    /**
+     * Assign the event handler implementation that will be used by the
+     * module to signal events back to the application.
+     *
+     * @param handler Application implementation of an EventHandler.
+     */
+    void setEventHandler(EventHandler *handler)
+    {
+        eventHandler = handler;
+    }
+
     /**
      * Event handler invoked when the server has sent data to a client.
      *
@@ -166,6 +198,7 @@ class GattServer {
     GattServer() :
         serviceCount(0),
         characteristicCount(0),
+        eventHandler(NULL),
         dataSentCallChain(),
         dataWrittenCallChain(),
         dataReadCallChain(),
@@ -778,6 +811,11 @@ class GattServer {
     }
 
 protected:
+    /**
+     * Event handler provided by the application.
+     */
+    EventHandler *eventHandler;
+
     /**
      * The total number of services added to the ATT table.
      */

features/FEATURE_BLE/ble/gap/Gap.h

@@ -492,6 +492,26 @@ class Gap {
         {
         }
 
+        /**
+         * Function invoked when the connections changes the maximum number of octets
+         * that can be sent or received by the controller in a single packet. A single
+         * L2CAP packet can be fragmented across many such packets.
+         *
+         * @note This only triggers if controller supports data length extension and
+         * negotiated data length is longer than the default 23.
+         *
+         * @param connectionHandle The handle of the connection that changed the size.
+         * @param txSize Number of octets we can send on this connection in a single packet.
+         * @param rxSize Number of octets we can receive on this connection in a single packet.
+         */
+        virtual void onDataLengthChange(
+            connection_handle_t connectionHandle,
+            uint16_t txSize,
+            uint16_t rxSize
+        )
+        {
+        }
+
     protected:
         /**
          * Prevent polymorphic deletion and avoid unnecessary virtual destructor

features/FEATURE_BLE/ble/generic/GenericGap.h

@@ -627,6 +627,12 @@ class GenericGap :
         phy_t rx_phy
     );
 
+    virtual void on_data_length_change(
+        connection_handle_t connection_handle,
+        uint16_t tx_size,
+        uint16_t rx_size
+    );
+
     virtual void on_phy_update_complete(
         pal::hci_error_code_t hci_status,
         Handle_t connection_handle,

features/FEATURE_BLE/ble/generic/GenericGattClient.h

@@ -33,8 +33,23 @@ namespace generic {
  * @attention: Not part of the public interface of BLE API.
  */
 class GenericGattClient : public GattClient,
-                          public pal::SigningEventMonitor {
+                          public pal::SigningEventMonitor,
+                          public pal::GattClient::EventHandler {
 public:
+
+    /**
+     * @see pal::GattClient::EventHandler::on_att_mtu_change
+     */
+    virtual void on_att_mtu_change(
+        ble::connection_handle_t connection_handle,
+        uint16_t att_mtu_size
+    )
+    {
+        if (eventHandler) {
+            eventHandler->onAttMtuChange(connection_handle, att_mtu_size);
+        }
+    }
+
     /**
      * Create a GenericGattClient from a pal::GattClient
      */
@@ -111,6 +126,13 @@ class GenericGattClient : public GattClient,
         const DiscoveredCharacteristic& characteristic
     );
 
+    /**
+     * @see GattClient::negotiateAttMtu
+     */
+    virtual ble_error_t negotiateAttMtu(
+        connection_handle_t connection
+    );
+
 	/**
 	 * @see GattClient::reset
 	 */
@@ -121,6 +143,14 @@ class GenericGattClient : public GattClient,
      */
     virtual void set_signing_event_handler(pal::SigningEventMonitor::EventHandler *signing_event_handler);
 
+    /**
+     *  Return the user registered event handler.
+     * @return User registered event handler or NULL if none is present.
+     */
+    ::GattClient::EventHandler* getEventHandler() {
+        return eventHandler;
+    }
+
 private:
     struct ProcedureControlBlock;
     struct DiscoveryControlBlock;

features/FEATURE_BLE/ble/pal/PalGap.h

@@ -44,6 +44,15 @@ struct Gap {
             ble::phy_t rx_phy
         ) = 0;
 
+        /**
+         * @copydoc Gap::EventHandler::onDataLengthChange
+         */
+        virtual void on_data_length_change(
+            connection_handle_t connection_handle,
+            uint16_t tx_size,
+            uint16_t rx_size
+        ) = 0;
+
         /**
          * @copydoc Gap::EventHandler::onPhyUpdateComplete
          */

features/FEATURE_BLE/ble/pal/PalGattClient.h

@@ -55,8 +55,25 @@ namespace pal {
  * the class AttClientToGattClientAdapter
  */
 class GattClient {
-
 public:
+    /**
+     * Definition of the general handler of GattClient related events.
+     */
+    struct EventHandler {
+        /**
+         * Function invoked when the connections changes the ATT_MTU which controls
+         * the maximum size of an attribute that can be read in a single L2CAP packet
+         * which might be fragmented across multiple packets.
+         *
+         * @param connectionHandle The handle of the connection that changed the size.
+         * @param attMtuSize
+         */
+        virtual void on_att_mtu_change(
+            ble::connection_handle_t connection_handle,
+            uint16_t att_mtu_size
+        ) = 0;
+    };
+
     /**
      * Initialisation of the instance. An implementation can use this function
      * to initialise the subsystems needed to realize the operations of this
@@ -582,8 +599,27 @@ class GattClient {
          _transaction_timeout_cb = cb;
      }
 
+     /**
+      * Sets the event handler that us called by the PAL porters to notify the stack of events
+      * which will in turn be passed onto the user application when appropriate.
+      *
+      * @param event_handler The new event handler interface implementation.
+      */
+     void set_event_handler(EventHandler* event_handler) {
+         _event_handler = event_handler;
+     }
+
+     /**
+      * Get the currently registered event handler.
+      *
+      * @return Currently registered event handler. NULL if no event handler is present.
+      */
+     EventHandler* get_event_handler() {
+         return _event_handler;
+     }
+
 protected:
-    GattClient() { }
+    GattClient() : _event_handler(NULL) { }
 
     virtual ~GattClient() { }
 
@@ -621,6 +657,8 @@ class GattClient {
     }
 
 private:
+    EventHandler* _event_handler;
+
     /**
      * Callback called when the client receive a message from the server.
      */

features/FEATURE_BLE/source/generic/GenericGap.cpp

@@ -860,6 +860,17 @@ void GenericGap::on_read_phy(
     }
 }
 
+void GenericGap::on_data_length_change(
+    Handle_t connection_handle,
+    uint16_t tx_size,
+    uint16_t rx_size
+)
+{
+    if (_eventHandler) {
+        _eventHandler->onDataLengthChange(connection_handle, tx_size, rx_size);
+    }
+}
+
 void GenericGap::on_phy_update_complete(
     pal::hci_error_code_t hci_status,
     Handle_t connection_handle,

features/FEATURE_BLE/source/generic/GenericGattClient.cpp

@@ -1259,6 +1259,12 @@ void GenericGattClient::terminateCharacteristicDescriptorDiscovery(
 
 }
 
+ble_error_t GenericGattClient::negotiateAttMtu(
+    connection_handle_t connection
+) {
+    return _pal_client->exchange_mtu(connection);
+}
+
 ble_error_t GenericGattClient::reset(void) {
 
 	// _is_reseting prevent executions of new procedure while the instance resets.
@@ -1274,7 +1280,7 @@ ble_error_t GenericGattClient::reset(void) {
 }
 
 void GenericGattClient::set_signing_event_handler(
-    EventHandler *signing_event_handler
+    pal::SigningEventMonitor::EventHandler *signing_event_handler
 ) {
     _signing_event_handler = signing_event_handler;
 }

features/FEATURE_BLE/targets/TARGET_CORDIO/CordioBLE.h

@@ -107,6 +107,13 @@ class BLE : public ::BLEInstanceBase {
      */
     virtual generic::GenericGattClient &getGattClient();
 
+    /**
+     * Get the PAL Gatt Client.
+     *
+     * @return PAL Gatt Client.
+     */
+    pal::AttClientToGattClientAdapter &getPalGattClient();
+
     /**
      * @see BLEInstanceBase::getSecurityManager
      */

features/FEATURE_BLE/targets/TARGET_CORDIO/CordioGattServer.h

@@ -62,6 +62,10 @@ class GattServer : public ::GattServer,
      */
     static GattServer &getInstance();
 
+    ::GattServer::EventHandler* getEventHandler() {
+        return eventHandler;
+    }
+
     /**
      * Initialize the GattServer and add mandatory services (generic access and
      * generic attribute service).