Revision 1062:a3fd424b73ca, committed 2016-01-11

Comitter:

vcoubard

Date:

Mon Jan 11 08:51:37 2016 +0000

Parent:

1061:9142ffdf0d9e

Child:

1063:187f9929cb60

Commit message:

Synchronized with git rev b817cf3e
Author: Andres Amaya Garcia
Improve API to facilitate full shutdown procedure

The BLE API exposes a shutdown() function in BLE.h. This function is meant to
be overwridden by platform-specific sub-classes to clear all GAP and GATT
state. However, from the platform-specific implementation it is dificult to
achieve this because the Gap, GattClient, GattServer and SecurityManager
components of the API do not expose any functionality to shutdown.

This commit introduces the following changes:

* Add a static member pointer to Gap, GattClient, GattServer and
SecurityManager that is used to keep track of the initialized objects.
* Add a function member cleanup() to Gap, GattClient, GattServer and
SecurityManager to allow easy reset of the instance's state. This function
is meant to be overriden and called from the derived classes to fully clear the
state of the BLE API and the platform-specific implementation.
* Add a static member function shutdown() to Gap, GattClient, GattServer and
SecurityManager. This function shall be called from the shutdown()
overriding BLE::shutdown() for Gap, GattClient, GattServer and SecurityManager
that will in-turn clear the state of each of the components.

**NOTE:** Platform-specific implementations of this API must be modified to
this changes into account.

Changed in this revision

--- a/ble/Gap.h	Mon Jan 11 08:51:36 2016 +0000
+++ b/ble/Gap.h	Mon Jan 11 08:51:37 2016 +0000
@@ -984,6 +984,54 @@
     }
 
 protected:
+    /**
+     * 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 clean up its
+     * state and not the data held in Gap members. This shall be achieved by a
+     * call to Gap::cleanup() from the sub-class' cleanup() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: Currently a call to cleanup() does not reset the advertising and
+     * scan parameters to default values.
+     */
+    virtual ble_error_t cleanup(void) {
+        /* Clear Gap state */
+        state.advertising = 0;
+        state.connected = 0;
+
+        /* Clear scanning state */
+        scanningActive = false;
+
+        /* Clear advertising and scanning data */
+        _advPayload.clear();
+        _scanResponse.clear();
+
+        return BLE_ERROR_NONE;
+    }
+
+public:
+    /**
+     * Clear all Gap state of the object pointed to by gapInstance.
+     *
+     * This function is meant to be called by the overridden BLE::shutdown()
+     * in the platform-specific sub-class.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: If gapInstance is NULL then it is assumed that Gap has not been
+     * instantiated and a call to Gap::shutdown() will succeed.
+     */
+    static ble_error_t shutdown(void) {
+        if (gapInstance) {
+            return gapInstance->cleanup();
+        }
+        return BLE_ERROR_NONE;
+    }
+
+protected:
     Gap() :
         _advParams(),
         _advPayload(),
@@ -1052,6 +1100,10 @@
     bool                             scanningActive;
 
 protected:
+    static Gap *gapInstance;    /**< Pointer to the Gap object instance.
+                                 *   If NULL, then Gap has not been initialized. */
+
+protected:
     TimeoutEventCallbackChain_t       timeoutCallbackChain;
     RadioNotificationEventCallback_t  radioNotificationCallback;
     AdvertisementReportCallback_t     onAdvertisementReport;

--- a/ble/GattClient.h	Mon Jan 11 08:51:36 2016 +0000
+++ b/ble/GattClient.h	Mon Jan 11 08:51:37 2016 +0000
@@ -326,6 +326,46 @@
     }
 
 protected:
+    /**
+     * 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 clean up its
+     * state and not the data held in GattClient members. This shall be achieved
+     * by a call to GattClient::cleanup() from the sub-class' cleanup()
+     * implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t cleanup(void) {
+        onDataReadCallbackChain.clear();
+        onDataWriteCallbackChain.clear();
+        onHVXCallbackChain.clear();
+
+        return BLE_ERROR_NONE;
+    }
+
+public:
+    /**
+     * Clear all GattClient state of the object pointed to by
+     * gattClientInstance.
+     *
+     * This function is meant to be called by the overridden BLE::shutdown()
+     * in the platform-specific sub-class.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: If gattClientInstance is NULL then it is assumed that Gap has not
+     * been instantiated and a call to GattClient::shutdown() will succeed.
+     */
+    static ble_error_t shutdown(void) {
+        if (gattClientInstance) {
+            return gattClientInstance->cleanup();
+        }
+        return BLE_ERROR_NONE;
+    }
+
+protected:
     GattClient() {
         /* Empty */
     }
@@ -351,6 +391,10 @@
     WriteCallbackChain_t onDataWriteCallbackChain;
     HVXCallbackChain_t   onHVXCallbackChain;
 
+protected:
+    static GattClient *gattClientInstance;      /**< Pointer to the GattClient object instance.
+                                                 *   If NULL, then GattClient has not been initialized. */
+
 private:
     /* Disallow copy and assignment. */
     GattClient(const GattClient &);

--- a/ble/GattServer.h	Mon Jan 11 08:51:36 2016 +0000
+++ b/ble/GattServer.h	Mon Jan 11 08:51:37 2016 +0000
@@ -397,9 +397,59 @@
     }
 
 protected:
+    /**
+     * 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 clean up its
+     * state and not the data held in GattServer members. This shall be achieved
+     * by a call to GattServer::cleanup() from the sub-class' cleanup()
+     * implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t cleanup(void) {
+        serviceCount = 0;
+        characteristicCount = 0;
+
+        dataSentCallChain.clear();
+        dataWrittenCallChain.clear();
+        dataReadCallChain.clear();
+        updatesEnabledCallback = NULL;
+        updatesDisabledCallback = NULL;
+        confirmationReceivedCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
+public:
+    /**
+     * Clear all GattServer state of the object pointed to by
+     * gattServerInstance.
+     *
+     * This function is meant to be called by the overridden BLE::shutdown()
+     * in the platform-specific sub-class.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: If gattServerInstance is NULL then it is assumed that Gap has not
+     * been instantiated and a call to GattServer::shutdown() will succeed.
+     */
+    static ble_error_t shutdown(void) {
+        if (gattServerInstance) {
+            return gattServerInstance->cleanup();
+        }
+        return BLE_ERROR_NONE;
+    }
+
+protected:
     uint8_t serviceCount;
     uint8_t characteristicCount;
 
+protected:
+    static GattServer *gattServerInstance;      /**< Pointer to the GattServer object instance.
+                                                 *   If NULL, then GattServer has not been initialized. */
+
 private:
     DataSentCallbackChain_t    dataSentCallChain;
     DataWrittenCallbackChain_t dataWrittenCallChain;

--- a/ble/SecurityManager.h	Mon Jan 11 08:51:36 2016 +0000
+++ b/ble/SecurityManager.h	Mon Jan 11 08:51:37 2016 +0000
@@ -232,6 +232,53 @@
     }
 
 protected:
+    /**
+     * 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 clean up its
+     * state and not the data held in SecurityManager members. This shall be
+     * achieved by a call to SecurityManager::cleanup() from the sub-class'
+     * cleanup() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t cleanup(void) {
+        securitySetupInitiatedCallback = NULL;
+        securitySetupCompletedCallback = NULL;
+        linkSecuredCallback = NULL;
+        securityContextStoredCallback = NULL;
+        passkeyDisplayCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
+public:
+    /**
+     * Clear all SecurityManager state of the object pointed to by
+     * securityManagerInstance.
+     *
+     * This function is meant to be called by the overridden BLE::shutdown()
+     * in the platform-specific sub-class.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: If securityManagerInstance is NULL then it is assumed that Gap has
+     * not been instantiated and a call to SecurityManager::shutdown() will
+     * succeed.
+     */
+    static ble_error_t shutdown(void) {
+        if (securityManagerInstance) {
+            return securityManagerInstance->cleanup();
+        }
+        return BLE_ERROR_NONE;
+    }
+
+protected:
+    static SecurityManager *securityManagerInstance;    /**< Pointer to the SecurityManager object instance.
+                                                         *   If NULL, then SecurityManager has not been initialized. */
+
+protected:
     SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
     SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
     LinkSecuredCallback_t            linkSecuredCallback;

--- a/ble/ServiceDiscovery.h	Mon Jan 11 08:51:36 2016 +0000
+++ b/ble/ServiceDiscovery.h	Mon Jan 11 08:51:37 2016 +0000
@@ -132,6 +132,27 @@
      */
     virtual void        onTermination(TerminationCallback_t callback) = 0;
 
+    /**
+     * Clear all ServiceDiscovery 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 clean up its
+     * state and not the data held in ServiceDiscovery members. This shall be
+     * achieved by a call to ServiceDiscovery::cleanup() from the sub-class'
+     * cleanup() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t cleanup(void) {
+        connHandle = 0;
+        matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
+        serviceCallback = NULL;
+        matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
+        characteristicCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
 protected:
     Gap::Handle_t            connHandle; /**< Connection handle as provided by the SoftDevice. */
     UUID                     matchingServiceUUID;

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/Gap.cpp	Mon Jan 11 08:51:37 2016 +0000
@@ -0,0 +1,19 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "ble/Gap.h"
+
+Gap *Gap::gapInstance = NULL;
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/GattClient.cpp	Mon Jan 11 08:51:37 2016 +0000
@@ -0,0 +1,19 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "ble/GattClient.h"
+
+GattClient *GattClient::gattClientInstance = NULL;
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/GattServer.cpp	Mon Jan 11 08:51:37 2016 +0000
@@ -0,0 +1,19 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "ble/GattServer.h"
+
+GattServer *GattServer::gattServerInstance = NULL;
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/SecurityManager.cpp	Mon Jan 11 08:51:37 2016 +0000
@@ -0,0 +1,19 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "ble/SecurityManager.h"
+
+SecurityManager *SecurityManager::securityManagerInstance = NULL;
\ No newline at end of file