Revision 1088:709ebced28ab, committed 2016-01-11

Comitter:

vcoubard

Date:

Mon Jan 11 08:51:49 2016 +0000

Parent:

1087:4c6e11878033

Child:

1089:8e810a8e083e

Commit message:

Synchronized with git rev 0781293b
Author: Andres Amaya Garcia
Add onShutdown to register callbacks

Add an onShutdown() function to Gap, GattClient, GattServer and
SecurityManager. The callbacks are added to a private callback chain in each of
the instances. The callbacks will be executed inside each object's reset()
function BEFORE the state of the instance is cleared. The developers of the
platform-specific implementation must call the parent class' reset() function
for the callbacks to be executed.

Finally, an onShutdown() function that returns the shutdown callchain is added
to allow detaching callbacks.

Changed in this revision

--- a/ble/Gap.h	Mon Jan 11 08:51:48 2016 +0000
+++ b/ble/Gap.h	Mon Jan 11 08:51:49 2016 +0000
@@ -38,7 +38,6 @@
 public:
     /**
      * Address-type for BLEProtocol addresses.
-     *
      * @note: deprecated. Use BLEProtocol::AddressType_t instead.
      */
     typedef BLEProtocol::AddressType_t AddressType_t;
@@ -49,21 +48,6 @@
      */
     typedef BLEProtocol::AddressType_t addr_type_t;
 
-    /**
-     * Address-type for BLEProtocol addresses.
-     * @note: deprecated. Use BLEProtocol::AddressType_t instead.
-     *
-     * DEPRECATION ALERT: The following constants have been left in their
-     * deprecated state to transparenly support existing applications which may
-     * have used Gap::ADDR_TYPE_*.
-     */
-    enum {
-        ADDR_TYPE_PUBLIC                        = BLEProtocol::AddressType::PUBLIC,
-        ADDR_TYPE_RANDOM_STATIC                 = BLEProtocol::AddressType::RANDOM_STATIC,
-        ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE     = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE,
-        ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
-    };
-
     static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
     typedef BLEProtocol::Address_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_t instead. */
     typedef BLEProtocol::Address_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_t instead. */
@@ -177,6 +161,9 @@
 
     typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
 
+    typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
+
     /*
      * The following functions are meant to be overridden in the platform-specific sub-class.
      */
@@ -1009,9 +996,43 @@
         radioNotificationCallback.attach(tptr, mptr);
     }
 
+    /**
+     * Setup a callback to be invoked to notify the user application that the
+     * Gap instance is about to shutdown (possibly as a result of a call
+     * to BLE::shutdown()).
+     *
+     * @Note: It is possible to chain together multiple onShutdown callbacks
+     * (potentially from different modules of an application) to be notified
+     * before the Gap instance is shutdown.
+     *
+     * @Note: It is also possible to set up a callback into a member function of
+     * some object.
+     *
+     * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+     */
+    void onShutdown(const GapShutdownCallback_t& callback) {
+        shutdownCallChain.add(callback);
+    }
+    template <typename T>
+    void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
+        shutdownCallChain.add(objPtr, memberPtr);
+    }
+
+    /**
+     * @brief provide access to the callchain of shutdown event callbacks
+     * It is possible to register callbacks using onShutdown().add(callback);
+     * It is possible to unregister callbacks using onShutdown().detach(callback)
+     * @return The shutdown event callbacks chain
+     */
+    GapShutdownCallbackChain_t& onShutdown() {
+        return shutdownCallChain;
+    }
+
 public:
     /**
-     * Clear all Gap state of the associated object.
+     * Notify all registered onShutdown callbacks that the Gap instance is
+     * about to be shutdown and clear all Gap state of the
+     * associated object.
      *
      * This function is meant to be overridden in the platform-specific
      * sub-class. Nevertheless, the sub-class is only expected to reset its
@@ -1024,6 +1045,9 @@
      * scan parameters to default values.
      */
     virtual ble_error_t reset(void) {
+        /* Notify that the instance is about to shutdown */
+        shutdownCallChain.call(this);
+
         /* Clear Gap state */
         state.advertising = 0;
         state.connected   = 0;
@@ -1121,6 +1145,9 @@
     DisconnectionEventCallbackChain_t disconnectionCallChain;
 
 private:
+    GapShutdownCallbackChain_t shutdownCallChain;
+
+private:
     /* Disallow copy and assignment. */
     Gap(const Gap &);
     Gap& operator=(const Gap &);

--- a/ble/GattClient.h	Mon Jan 11 08:51:48 2016 +0000
+++ b/ble/GattClient.h	Mon Jan 11 08:51:49 2016 +0000
@@ -41,6 +41,9 @@
     typedef FunctionPointerWithContext<const GattHVXCallbackParams*> HVXCallback_t;
     typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> HVXCallbackChain_t;
 
+    typedef FunctionPointerWithContext<const GattClient *> GattClientShutdownCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const GattClient *> GattClientShutdownCallbackChain_t;
+
     /*
      * The following functions are meant to be overridden in the platform-specific sub-class.
      */
@@ -314,6 +317,37 @@
         onHVXCallbackChain.add(callback);
     }
 
+    /**
+     * Setup a callback to be invoked to notify the user application that the
+     * GattClient instance is about to shutdown (possibly as a result of a call
+     * to BLE::shutdown()).
+     *
+     * @Note: It is possible to chain together multiple onShutdown callbacks
+     * (potentially from different modules of an application) to be notified
+     * before the GattClient is shutdown.
+     *
+     * @Note: It is also possible to set up a callback into a member function of
+     * some object.
+     *
+     * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+     */
+    void onShutdown(const GattClientShutdownCallback_t& callback) {
+        shutdownCallChain.add(callback);
+    }
+    template <typename T>
+    void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
+        shutdownCallChain.add(objPtr, memberPtr);
+    }
+
+    /**
+     * @brief provide access to the callchain of shutdown event callbacks
+     * It is possible to register callbacks using onShutdown().add(callback);
+     * It is possible to unregister callbacks using onShutdown().detach(callback)
+     * @return The shutdown event callbacks chain
+     */
+    GattClientShutdownCallbackChain_t& onShutdown() {
+        return shutdownCallChain;
+    }
 
     /**
      * @brief provide access to the callchain of HVX callbacks
@@ -327,7 +361,9 @@
 
 public:
     /**
-     * Clear all GattClient state of the associated object.
+     * Notify all registered onShutdown callbacks that the GattClient is
+     * about to be shutdown and clear all GattClient state of the
+     * associated object.
      *
      * This function is meant to be overridden in the platform-specific
      * sub-class. Nevertheless, the sub-class is only expected to reset its
@@ -338,6 +374,9 @@
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t reset(void) {
+        /* Notify that the instance is about to shutdown */
+        shutdownCallChain.call(this);
+
         onDataReadCallbackChain.clear();
         onDataWriteCallbackChain.clear();
         onHVXCallbackChain.clear();
@@ -367,9 +406,10 @@
     }
 
 protected:
-    ReadCallbackChain_t  onDataReadCallbackChain;
-    WriteCallbackChain_t onDataWriteCallbackChain;
-    HVXCallbackChain_t   onHVXCallbackChain;
+    ReadCallbackChain_t               onDataReadCallbackChain;
+    WriteCallbackChain_t              onDataWriteCallbackChain;
+    HVXCallbackChain_t                onHVXCallbackChain;
+    GattClientShutdownCallbackChain_t shutdownCallChain;
 
 private:
     /* Disallow copy and assignment. */

--- a/ble/GattServer.h	Mon Jan 11 08:51:48 2016 +0000
+++ b/ble/GattServer.h	Mon Jan 11 08:51:49 2016 +0000
@@ -36,6 +36,9 @@
     typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t;
     typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t;
 
+    typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const GattServer *> GattServerShutdownCallbackChain_t;
+
     typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t;
 
 protected:
@@ -342,6 +345,38 @@
     }
 
     /**
+     * Setup a callback to be invoked to notify the user application that the
+     * GattServer instance is about to shutdown (possibly as a result of a call
+     * to BLE::shutdown()).
+     *
+     * @Note: It is possible to chain together multiple onShutdown callbacks
+     * (potentially from different modules of an application) to be notified
+     * before the GattServer is shutdown.
+     *
+     * @Note: It is also possible to set up a callback into a member function of
+     * some object.
+     *
+     * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+     */
+    void onShutdown(const GattServerShutdownCallback_t& callback) {
+        shutdownCallChain.add(callback);
+    }
+    template <typename T>
+    void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
+        shutdownCallChain.add(objPtr, memberPtr);
+    }
+
+    /**
+     * @brief provide access to the callchain of shutdown event callbacks
+     * It is possible to register callbacks using onShutdown().add(callback);
+     * It is possible to unregister callbacks using onShutdown().detach(callback)
+     * @return The shutdown event callbacks chain
+     */
+    GattServerShutdownCallbackChain_t& onShutdown() {
+        return shutdownCallChain;
+    }
+
+    /**
      * Set up a callback for when notifications or indications are enabled for a
      * characteristic on the local GATT server.
      */
@@ -397,7 +432,9 @@
 
 public:
     /**
-     * Clear all GattServer state of the associated object.
+     * Notify all registered onShutdown callbacks that the GattServer is
+     * about to be shutdown and clear all GattServer state of the
+     * associated object.
      *
      * This function is meant to be overridden in the platform-specific
      * sub-class. Nevertheless, the sub-class is only expected to reset its
@@ -408,7 +445,10 @@
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t reset(void) {
-        serviceCount        = 0;
+        /* Notify that the instance is about to shutdown */
+        shutdownCallChain.call(this);
+
+        serviceCount = 0;
         characteristicCount = 0;
 
         dataSentCallChain.clear();
@@ -426,12 +466,13 @@
     uint8_t characteristicCount;
 
 private:
-    DataSentCallbackChain_t    dataSentCallChain;
-    DataWrittenCallbackChain_t dataWrittenCallChain;
-    DataReadCallbackChain_t    dataReadCallChain;
-    EventCallback_t            updatesEnabledCallback;
-    EventCallback_t            updatesDisabledCallback;
-    EventCallback_t            confirmationReceivedCallback;
+    DataSentCallbackChain_t           dataSentCallChain;
+    DataWrittenCallbackChain_t        dataWrittenCallChain;
+    DataReadCallbackChain_t           dataReadCallChain;
+    GattServerShutdownCallbackChain_t shutdownCallChain;
+    EventCallback_t                   updatesEnabledCallback;
+    EventCallback_t                   updatesDisabledCallback;
+    EventCallback_t                   confirmationReceivedCallback;
 
 private:
     /* Disallow copy and assignment. */

--- a/ble/SecurityManager.h	Mon Jan 11 08:51:48 2016 +0000
+++ b/ble/SecurityManager.h	Mon Jan 11 08:51:49 2016 +0000
@@ -20,6 +20,7 @@
 #include <stdint.h>
 
 #include "Gap.h"
+#include "CallChainOfFunctionPointersWithContext.h"
 
 class SecurityManager {
 public:
@@ -82,6 +83,9 @@
     typedef void (*LinkSecuredCallback_t)(Gap::Handle_t handle, SecurityMode_t securityMode);
     typedef void (*PasskeyDisplayCallback_t)(Gap::Handle_t handle, const Passkey_t passkey);
 
+    typedef FunctionPointerWithContext<const SecurityManager *> SecurityManagerShutdownCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const SecurityManager *> SecurityManagerShutdownCallbackChain_t;
+
     /*
      * The following functions are meant to be overridden in the platform-specific sub-class.
      */
@@ -162,6 +166,38 @@
     /* Event callback handlers. */
 public:
     /**
+     * Setup a callback to be invoked to notify the user application that the
+     * SecurityManager instance is about to shutdown (possibly as a result of a call
+     * to BLE::shutdown()).
+     *
+     * @Note: It is possible to chain together multiple onShutdown callbacks
+     * (potentially from different modules of an application) to be notified
+     * before the SecurityManager is shutdown.
+     *
+     * @Note: It is also possible to set up a callback into a member function of
+     * some object.
+     *
+     * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+     */
+    void onShutdown(const SecurityManagerShutdownCallback_t& callback) {
+        shutdownCallChain.add(callback);
+    }
+    template <typename T>
+    void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
+        shutdownCallChain.add(objPtr, memberPtr);
+    }
+
+    /**
+     * @brief provide access to the callchain of shutdown event callbacks
+     * It is possible to register callbacks using onShutdown().add(callback);
+     * It is possible to unregister callbacks using onShutdown().detach(callback)
+     * @return The shutdown event callbacks chain
+     */
+    SecurityManagerShutdownCallbackChain_t& onShutdown() {
+        return shutdownCallChain;
+    }
+
+    /**
      * To indicate that a security procedure for the link has started.
      */
     virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;}
@@ -233,7 +269,9 @@
 
 public:
     /**
-     * Clear all SecurityManager state of the associated object.
+     * Notify all registered onShutdown callbacks that the SecurityManager is
+     * about to be shutdown and clear all SecurityManager state of the
+     * associated object.
      *
      * This function is meant to be overridden in the platform-specific
      * sub-class. Nevertheless, the sub-class is only expected to reset its
@@ -244,6 +282,9 @@
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t reset(void) {
+        /* Notify that the instance is about to shutdown */
+        shutdownCallChain.call(this);
+
         securitySetupInitiatedCallback = NULL;
         securitySetupCompletedCallback = NULL;
         linkSecuredCallback            = NULL;
@@ -259,6 +300,9 @@
     LinkSecuredCallback_t            linkSecuredCallback;
     HandleSpecificEvent_t            securityContextStoredCallback;
     PasskeyDisplayCallback_t         passkeyDisplayCallback;
+
+private:
+    SecurityManagerShutdownCallbackChain_t shutdownCallChain;
 };
 
 #endif /*__SECURITY_MANAGER_H__*/
\ No newline at end of file