Improve API to facilitate full shutdown procedure

ble/Gap.h

@@ -983,6 +983,54 @@ class Gap {
         radioNotificationCallback.attach(tptr, mptr);
     }
 
+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(),
@@ -1051,6 +1099,10 @@ class Gap {
     GapState_t                       state;
     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;

ble/GattClient.h

@@ -325,6 +325,46 @@ class GattClient {
         return onHVXCallbackChain;
     }
 
+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 @@ class GattClient {
     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 &);

ble/GattServer.h

@@ -396,10 +396,60 @@ class GattServer {
         dataSentCallChain.call(count);
     }
 
+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;

ble/SecurityManager.h

@@ -231,6 +231,53 @@ class SecurityManager {
         /* empty */
     }
 
+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;

ble/ServiceDiscovery.h

@@ -132,6 +132,27 @@ class ServiceDiscovery {
      */
     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;

source/Gap.cpp

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

source/GattClient.cpp

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

source/GattServer.cpp

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

source/SecurityManager.cpp

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