Revision 1074:1fedc77d9add, committed 2016-01-11

Comitter:

vcoubard

Date:

Mon Jan 11 08:51:42 2016 +0000

Parent:

1073:edd717e9f799

Child:

1075:0d0dafb54bc9

Commit message:

Synchronized with git rev cd809e2a
Author: Andres Amaya Garcia
Modify shutdown API and functionality

Modify the shutdown API to remove the static shutdown function in Gap,
SecurityManager, GattClient and GattServer. Futhermore, remove the static
references to Gap, SecurityManager, GattClient and GattServer objects inside
their own classes. The cleanup method is renamed to `reset()` and made public.
Finally, additional functionality is added to the reset implementation in
Gap.

Changed in this revision

--- a/ble/CharacteristicDescriptorDiscovery.h	Mon Jan 11 08:51:41 2016 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,99 +0,0 @@
-/* mbed Microcontroller Library
- * Copyright (c) 2006-2015 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.
- */
-
-#ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
-#define __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
-
-#include "FunctionPointerWithContext.h"
-
-class DiscoveredCharacteristic;                         // forward declaration
-class DiscoveredCharacteristicDescriptor;               // forward declaration
-
-/**
- * @brief Contain all definitions of callbacks and callbacks parameters types
- * related to characteristic descriptor discovery.
- *
- * @details This class act like a namespace for characteristic descriptor discovery
- * types. It act like ServiceDiscovery by providing callbacks and callbacks
- * parameters types related to the characteristic descriptor discovery process but
- * contrary to ServiceDiscovery class, it does not force the porter to use a
- * specific interface for the characteristic descriptor discovery process.
- */
-class CharacteristicDescriptorDiscovery {
-public:
-    /**
-     * @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
-     * @detail Every time a characteristic descriptor has been discovered, the callback
-     * registered for the discovery operation through GattClient::discoverCharacteristicDescriptors
-     * or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter.
-     *
-     */
-    struct DiscoveryCallbackParams_t {
-        /**
-         * The characteristic owning the DiscoveredCharacteristicDescriptor
-         */
-        const DiscoveredCharacteristic& characteristic;
-
-        /**
-         * The characteristic descriptor discovered
-         */
-        const DiscoveredCharacteristicDescriptor& descriptor;
-    };
-
-    /**
-     * @brief Parameter type of CharacteristicDescriptorDiscovery::TerminationCallback_t.
-     * @details Once a characteristic descriptor discovery process terminate, the termination
-     * callback registered for the discovery operation through
-     * GattClient::discoverCharacteristicDescriptors or DiscoveredCharacteristic::discoverDescriptors
-     * will be called with this parameter.
-     */
-    struct TerminationCallbackParams_t {
-        /**
-         * The characteristic for which the descriptors has been discovered
-         */
-        const DiscoveredCharacteristic& characteristic;
-
-        /**
-         * status of the discovery operation
-         */
-        ble_error_t status;
-    };
-
-    /**
-     * @brief Callback type for when a matching characteristic descriptor is found during
-     * characteristic descriptor discovery.
-     *
-     * @param param A pointer to a DiscoveryCallbackParams_t object which will remain
-     * valid for the lifetime of the callback. Memory for this object is owned by
-     * the BLE_API eventing framework. The application can safely make a persistent
-     * shallow-copy of this object in order to work with the service beyond the
-     * callback.
-     */
-    typedef FunctionPointerWithContext<const DiscoveryCallbackParams_t*> DiscoveryCallback_t;
-
-    /**
-     * @brief Callback type for when characteristic descriptor discovery terminates.
-     *
-     * @param param A pointer to a TerminationCallbackParams_t object which will remain
-     * valid for the lifetime of the callback. Memory for this object is owned by
-     * the BLE_API eventing framework. The application can safely make a persistent
-     * shallow-copy of this object in order to work with the service beyond the
-     * callback.
-     */
-    typedef FunctionPointerWithContext<const TerminationCallbackParams_t*> TerminationCallback_t;
-};
-
-#endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
\ No newline at end of file

--- a/ble/DiscoveredCharacteristic.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/DiscoveredCharacteristic.h	Mon Jan 11 08:51:42 2016 +0000
@@ -21,24 +21,10 @@
 #include "Gap.h"
 #include "GattAttribute.h"
 #include "GattClient.h"
-#include "CharacteristicDescriptorDiscovery.h"
-#include "ble/DiscoveredCharacteristicDescriptor.h"
 
 /**
- * @brief Representation of a characteristic discovered during a GattClient
- * discovery procedure (see GattClient::launchServiceDiscovery ).
- *
- * @detail Provide detailed informations about a discovered characteristic like:
- *     - Its UUID (see #getUUID).
- *     - The most important handles of the characteristic definition
- *       (see #getDeclHandle, #getValueHandle, #getLastHandle )
- *     - Its properties (see #getProperties).
- * This class also provide functions to operate on the characteristic:
- *     - Read the characteristic value (see #read)
- *     - Writing a characteristic value (see #write or #writeWoResponse)
- *     - Discover descriptors inside the characteristic definition. These descriptors
- *       extends the characteristic. More information about descriptor usage is
- *       available in DiscoveredCharacteristicDescriptor class.
+ * Structure for holding information about the service and the characteristics
+ * found during the discovery process.
  */
 class DiscoveredCharacteristic {
 public:
@@ -47,7 +33,7 @@
         uint8_t _read            :1; /**< Reading the value permitted. */
         uint8_t _writeWoResp     :1; /**< Writing the value with Write Command permitted. */
         uint8_t _write           :1; /**< Writing the value with Write Request permitted. */
-        uint8_t _notify          :1; /**< Notifications of the value permitted. */
+        uint8_t _notify          :1; /**< Notications of the value permitted. */
         uint8_t _indicate        :1; /**< Indications of the value permitted. */
         uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
 
@@ -60,50 +46,36 @@
         bool indicate(void)        const {return _indicate;       }
         bool authSignedWrite(void) const {return _authSignedWrite;}
 
-        /**
-         * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
-         *
-         * @param lhs[in] The left hand side of the equality expression
-         * @param rhs[in] The right hand side of the equality expression
-         *
-         * @return true if operands are equals, false otherwise.
-         */
-        friend bool operator==(Properties_t lhs, Properties_t rhs) {
-            return lhs._broadcast == rhs._broadcast &&
-                   lhs._read == rhs._read &&
-                   lhs._writeWoResp == rhs._writeWoResp &&
-                   lhs._write == rhs._write &&
-                   lhs._notify == rhs._notify &&
-                   lhs._indicate == rhs._indicate &&
-                   lhs._authSignedWrite == rhs._authSignedWrite;
-        }
-
-        /**
-         * @brief "Not equal to" operator for DiscoveredCharacteristic::Properties_t
-         *
-         * @param lhs The right hand side of the expression
-         * @param rhs The left hand side of the expression
-         *
-         * @return true if operands are not equals, false otherwise.
-         */
-        friend bool operator!=(Properties_t lhs, Properties_t rhs) {
-            return !(lhs == rhs);
-        }
-
     private:
         operator uint8_t()  const; /* Disallow implicit conversion into an integer. */
         operator unsigned() const; /* Disallow implicit conversion into an integer. */
     };
 
     /**
+     * Structure for holding information about the service and the characteristics
+     * found during the discovery process.
+     */
+    struct DiscoveredDescriptor {
+        GattAttribute::Handle_t handle; /**< Descriptor Handle. */
+        UUID                    uuid;   /**< Descriptor UUID. */
+    };
+
+    /**
+     * Callback type for when a characteristic descriptor is found during descriptor-
+     * discovery. The receiving function is passed in a pointer to a
+     * DiscoveredDescriptor object which will remain valid for the lifetime
+     * of the callback. Memory for this object is owned by the BLE_API eventing
+     * framework. The application can safely make a persistent shallow-copy of
+     * this object in order to work with the characteristic beyond the callback.
+     */
+    typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
+
+    /**
      * Initiate (or continue) a read for the value attribute, optionally at a
      * given offset. If the characteristic or descriptor to be read is longer
      * than ATT_MTU - 1, this function must be called multiple times with
      * appropriate offset to read the complete value.
      *
-     * @param offset[in] The position - in the characteristic value bytes stream - where
-     * the read operation begin.
-     *
      * @return BLE_ERROR_NONE if a read has been initiated, or
      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
      *         BLE_STACK_BUSY if some client procedure is already in progress, or
@@ -111,22 +83,14 @@
      */
     ble_error_t read(uint16_t offset = 0) const;
 
-    /**
-     * @brief Same as #read(uint16_t) const but allow the user to register a callback
-     * which will be fired once the read is done.
-     *
-     * @param offset[in] The position - in the characteristic value bytes stream - where
-     * the read operation begin.
-     * @param onRead[in] Continuation of the read operation
-     */
     ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
 
     /**
      * Perform a write without response procedure.
      *
-     * @param[in]  length
+     * @param  length
      *           The amount of data being written.
-     * @param[in]  value
+     * @param  value
      *           The bytes being written.
      *
      * @note   It is important to note that a write without response will generate
@@ -146,20 +110,20 @@
     /**
      * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
      *
-     * @param[in] onDescriptorDiscovered This callback will be called every time a descriptor is discovered
-     * @param[in] onTermination This callback will be called when the discovery process is over.
+     * @param  callback
+     * @param  matchingUUID
+     *           Filter for descriptors. Defaults to wildcard which will discover all descriptors.
      *
-     * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
+     * @return  BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
      */
-    ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered,
-                                    const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const;
+    ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
 
     /**
      * Perform a write procedure.
      *
-     * @param[in]  length
+     * @param  length
      *           The amount of data being written.
-     * @param[in]  value
+     * @param  value
      *           The bytes being written.
      *
      * @note   It is important to note that a write will generate
@@ -174,142 +138,36 @@
     ble_error_t write(uint16_t length, const uint8_t *value) const;
 
     /**
-     * Same as #write(uint16_t, const uint8_t *) const but register a callback
-     * which will be called once the data has been written.
-     *
-     * @param[in] length The amount of bytes to write.
-     * @param[in] value The bytes to write.
-     * @param[in] onRead Continuation callback for the write operation
+     * Same as above but register the callback wich will be called once the data has been written
      */
-    ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
+    ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
 
     void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
         uuid.setupLong(longUUID, order);
     }
 
 public:
-    /**
-     * @brief Get the UUID of the discovered characteristic
-     * @return the UUID of this characteristic
-     */
     const UUID& getUUID(void) const {
         return uuid;
     }
 
-    /**
-     * @brief Get the properties of this characteristic
-     * @return the set of properties of this characteristic
-     */
     const Properties_t& getProperties(void) const {
         return props;
     }
 
-    /**
-     * @brief Get the declaration handle of this characteristic.
-     * @detail The declaration handle is the first handle of a characteristic
-     * definition. The value accessible at this handle contains the following
-     * informations:
-     *    - The characteristics properties (see Properties_t). This value can
-     *      be accessed by using #getProperties .
-     *    - The characteristic value attribute handle. This field can be accessed
-     *      by using #getValueHandle .
-     *    - The characteristic UUID, this value can be accessed by using the
-     *      function #getUUID .
-     * @return the declaration handle of this characteristic.
-     */
-    GattAttribute::Handle_t getDeclHandle(void) const {
+    const GattAttribute::Handle_t& getDeclHandle(void) const {
         return declHandle;
     }
-
-    /**
-     * @brief Return the handle used to access the value of this characteristic.
-     * @details This handle is the one provided in the characteristic declaration
-     * value. Usually, it is equal to #getDeclHandle() + 1. But it is not always
-     * the case. Anyway, users are allowed to use #getDeclHandle() + 1 to access
-     * the value of a characteristic.
-     * @return The handle to access the value of this characteristic.
-     */
-    GattAttribute::Handle_t getValueHandle(void) const {
+    const GattAttribute::Handle_t& getValueHandle(void) const {
         return valueHandle;
     }
 
-    /**
-     * @brief Return the last handle of the characteristic definition.
-     * @details A Characteristic definition can contain a lot of handles:
-     *     - one for the declaration (see #getDeclHandle)
-     *     - one for the value (see #getValueHandle)
-     *     - zero of more for the characteristic descriptors.
-     * This handle is the last handle of the characteristic definition.
-     * @return The last handle of this characteristic definition.
-     */
-    GattAttribute::Handle_t getLastHandle(void) const {
-        return lastHandle;
-    }
-
-    /**
-     * @brief Return the GattClient which can operate on this characteristic.
-     * @return The GattClient which can operate on this characteristic.
-     */
-    GattClient* getGattClient() {
-        return gattc;
-    }
-
-    /**
-     * @brief Return the GattClient which can operate on this characteristic.
-     * @return The GattClient which can operate on this characteristic.
-     */
-    const GattClient* getGattClient() const {
-        return gattc;
-    }
-
-    /**
-     * @brief Return the connection handle to the GattServer which contain
-     * this characteristic.
-     * @return the connection handle to the GattServer which contain
-     * this characteristic.
-     */
-    Gap::Handle_t getConnectionHandle() const {
-        return connHandle;
-    }
-
-    /**
-     * @brief "Equal to" operator for DiscoveredCharacteristic
-     *
-     * @param lhs[in] The left hand side of the equality expression
-     * @param rhs[in] The right hand side of the equality expression
-     *
-     * @return true if operands are equals, false otherwise.
-     */
-    friend bool operator==(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
-        return lhs.gattc == rhs.gattc &&
-               lhs.uuid == rhs.uuid &&
-               lhs.props == rhs.props &&
-               lhs.declHandle == rhs.declHandle &&
-               lhs.valueHandle == rhs.valueHandle &&
-               lhs.lastHandle == rhs.lastHandle &&
-               lhs.connHandle == rhs.connHandle;
-    }
-
-    /**
-     * @brief "Not equal to" operator for DiscoveredCharacteristic
-     *
-     * @param lhs[in] The right hand side of the expression
-     * @param rhs[in] The left hand side of the expression
-     *
-     * @return true if operands are not equals, false otherwise.
-     */
-    friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
-        return !(lhs == rhs);
-    }
-
 public:
     DiscoveredCharacteristic() : gattc(NULL),
                                  uuid(UUID::ShortUUIDBytes_t(0)),
                                  props(),
                                  declHandle(GattAttribute::INVALID_HANDLE),
-                                 valueHandle(GattAttribute::INVALID_HANDLE),
-                                 lastHandle(GattAttribute::INVALID_HANDLE),
-                                 connHandle() {
+                                 valueHandle(GattAttribute::INVALID_HANDLE) {
         /* empty */
     }
 
@@ -321,7 +179,6 @@
     Properties_t             props;
     GattAttribute::Handle_t  declHandle;
     GattAttribute::Handle_t  valueHandle;
-    GattAttribute::Handle_t  lastHandle;
 
     Gap::Handle_t            connHandle;
 };

--- a/ble/DiscoveredCharacteristicDescriptor.h	Mon Jan 11 08:51:41 2016 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,111 +0,0 @@
-/* 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.
- */
-
-#ifndef __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__
-#define __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__
-
-#include "UUID.h"
-#include "Gap.h"
-#include "GattAttribute.h"
-#include "GattClient.h"
-#include "CharacteristicDescriptorDiscovery.h"
-
-/**
- * @brief Representation of a descriptor discovered during a GattClient
- * discovery procedure (see GattClient::discoverCharacteristicDescriptors or
- * DiscoveredCharacteristic::discoverDescriptors ).
- *
- * @detail Provide detailed informations about a discovered characteristic descriptor
- * like:
- *     - Its UUID (see #getUUID).
- *     - Its handle (see #getAttributeHandle)
- * Basic read (see GattClient::read) and write (see GattClient::write) procedure from
- * GattClient can be used access the value of the descriptor.
- *
- * @todo read member function
- * @todo write member function
- * @todo enumeration of standard descriptors
- */
-class DiscoveredCharacteristicDescriptor {
-
-public:
-
-    /**
-     * @brief construct a new instance of a DiscoveredCharacteristicDescriptor
-     *
-     * @param client The client from where the descriptor has been discovered
-     * @param connectionHandle The connection handle on which the descriptor has
-     * been discovered
-     * @param attributeHandle The handle of the attribute containing this descriptor
-     * @param uuid The UUID of the descriptor
-     */
-    DiscoveredCharacteristicDescriptor(
-        GattClient* client, Gap::Handle_t connectionHandle,  GattAttribute::Handle_t attributeHandle, const UUID& uuid) :
-        _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(attributeHandle) {
-
-    }
-
-    /**
-     * @brief Return the GattClient which can operate on this descriptor.
-     * @return The GattClient which can operate on this descriptor.
-     */
-    GattClient* getGattClient() {
-        return _client;
-    }
-
-    /**
-     * @brief Return the GattClient which can operate on this descriptor.
-     * @return The GattClient which can operate on this descriptor.
-     */
-    const GattClient* getGattClient() const {
-        return _client;
-    }
-
-    /**
-     * @brief Return the connection handle to the GattServer which contain
-     * this descriptor.
-     * @return the connection handle to the GattServer which contain
-     * this descriptor.
-     */
-    Gap::Handle_t getConnectionHandle() const {
-        return _connectionHandle;
-    }
-
-    /**
-     * @brief Return the UUID of this descriptor
-     * @return the UUID of this descriptor
-     */
-    const UUID& getUUID(void) const {
-        return _uuid;
-    }
-
-    /**
-     * @brief Return the attribute handle to use to access to this descriptor
-     * on the gatt server.
-     * @return The attribute handle of the descriptor
-     */
-    GattAttribute::Handle_t getAttributeHandle() const {
-        return _gattHandle;
-    }
-
-private:
-    GattClient  *_client;
-    Gap::Handle_t _connectionHandle;
-    UUID _uuid;
-    GattAttribute::Handle_t _gattHandle;
-};
-
-#endif /*__DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__*/
\ No newline at end of file

--- a/ble/Gap.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/Gap.h	Mon Jan 11 08:51:42 2016 +0000
@@ -983,6 +983,42 @@
         radioNotificationCallback.attach(tptr, mptr);
     }
 
+public:
+    /**
+     * 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
+     * state and not the data held in Gap members. This shall be achieved by a
+     * call to Gap::reset() from the sub-class' reset() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     *
+     * @note: Currently a call to reset() does not reset the advertising and
+     * scan parameters to default values.
+     */
+    virtual ble_error_t reset(void) {
+        /* Clear Gap state */
+        state.advertising = 0;
+        state.connected = 0;
+
+        /* Clear scanning state */
+        scanningActive = false;
+
+        /* Clear advertising and scanning data */
+        _advPayload.clear();
+        _scanResponse.clear();
+
+        /* Clear callbacks */
+        timeoutCallbackChain.clear();
+        connectionCallChain.clear();
+        disconnectionCallChain.clear();
+        radioNotificationCallback = NULL;
+        onAdvertisementReport = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
 protected:
     Gap() :
         _advParams(),

--- a/ble/GattClient.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/GattClient.h	Mon Jan 11 08:51:42 2016 +0000
@@ -20,7 +20,6 @@
 #include "Gap.h"
 #include "GattAttribute.h"
 #include "ServiceDiscovery.h"
-#include "CharacteristicDescriptorDiscovery.h"
 
 #include "GattCallbackParamTypes.h"
 
@@ -217,8 +216,8 @@
      * Initiate a GATT Client write procedure.
      *
      * @param[in] cmd
-     *              Command can be either a write-request (which generates a
-     *              matching response from the peripheral), or a write-command
+     *              Command can be either a write-request (which generates a 
+     *              matching response from the peripheral), or a write-command 
      *              (which doesn't require the connected peer to respond).
      * @param[in] connHandle
      *              Connection handle.
@@ -247,8 +246,8 @@
     /* Event callback handlers. */
 public:
     /**
-     * Set up a callback for read response events.
-     * It is possible to remove registered callbacks using
+     * Set up a callback for read response events. 
+     * It is possible to remove registered callbacks using 
      * onDataRead().detach(callbackToRemove)
      */
     void onDataRead(ReadCallback_t callback) {
@@ -258,7 +257,7 @@
     /**
      * @brief provide access to the callchain of read callbacks
      * It is possible to register callbacks using onDataRead().add(callback);
-     * It is possible to unregister callbacks using onDataRead().detach(callback)
+     * It is possible to unregister callbacks using onDataRead().detach(callback) 
      * @return The read callbacks chain
      */
     ReadCallbackChain_t& onDataRead() {
@@ -267,7 +266,7 @@
 
     /**
      * Set up a callback for write response events.
-     * It is possible to remove registered callbacks using
+     * It is possible to remove registered callbacks using 
      * onDataWritten().detach(callbackToRemove).
      * @Note: Write commands (issued using writeWoResponse) don't generate a response.
      */
@@ -278,10 +277,10 @@
     /**
      * @brief provide access to the callchain of data written callbacks
      * It is possible to register callbacks using onDataWritten().add(callback);
-     * It is possible to unregister callbacks using onDataWritten().detach(callback)
+     * It is possible to unregister callbacks using onDataWritten().detach(callback) 
      * @return The data written callbacks chain
      */
-    WriteCallbackChain_t& onDataWritten() {
+    WriteCallbackChain_t& onDataWritten() { 
         return onDataWriteCallbackChain;
     }
 
@@ -306,59 +305,6 @@
     }
 
     /**
-     * @brief launch discovery of descriptors for a given characteristic
-     * @details This function will discover all descriptors available for a
-     * specific characteristic.
-     *
-     * @param characteristic[in] The characteristic targeted by this discovery
-     * procedure
-     * @param discoveryCallback[in] User function called each time a descriptor
-     * is found during the procedure.
-     * @param terminationCallback[in] User provided function which will be called
-     * once the discovery procedure is terminating. This will get called when all
-     * the descriptors have been discovered or if an error occur during the discovery
-     * procedure.
-     *
-     * @return
-     *   BLE_ERROR_NONE if characteristic descriptor discovery is launched
-     *   successfully; else an appropriate error.
-     */
-    virtual ble_error_t discoverCharacteristicDescriptors(
-        const DiscoveredCharacteristic& characteristic,
-        const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback,
-        const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) {
-        (void) characteristic;
-        (void) discoveryCallback;
-        (void) terminationCallback;
-        /* Requesting action from porter(s): override this API if this capability is supported. */
-        return BLE_ERROR_NOT_IMPLEMENTED;
-    }
-
-    /**
-     * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic
-     * or not.
-     * @param characteristic[in] The characteristic concerned by the descriptors discovery.
-     * @return true if a descriptors discovery is active for the characteristic in input; otherwise false.
-     */
-    virtual bool isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const
-     {
-        (void) characteristic;
-        return false; /* Requesting action from porter(s): override this API if this capability is supported. */
-    }
-
-    /**
-     * @brief Terminate an ongoing characteristic descriptor discovery.
-     * @detail This should result in an invocation of the TerminationCallback if
-     * the characteristic descriptor discovery is active.
-     * @param characteristic[in] The characteristic on which the running descriptors
-     * discovery should be stopped.
-     */
-    virtual void terminateCharacteristicDescriptorsDiscovery(const DiscoveredCharacteristic& characteristic) {
-        /* Requesting action from porter(s): override this API if this capability is supported. */
-        (void) characteristic;
-    }
-
-    /**
      * Set up a callback for when the GATT client receives an update event
      * corresponding to a change in the value of a characteristic on the remote
      * GATT server.
@@ -372,13 +318,33 @@
     /**
      * @brief provide access to the callchain of HVX callbacks
      * It is possible to register callbacks using onHVX().add(callback);
-     * It is possible to unregister callbacks using onHVX().detach(callback)
+     * It is possible to unregister callbacks using onHVX().detach(callback) 
      * @return The HVX callbacks chain
      */
-    HVXCallbackChain_t& onHVX() {
+    HVXCallbackChain_t& onHVX() { 
         return onHVXCallbackChain;
     }
 
+public:
+    /**
+     * 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
+     * state and not the data held in GattClient members. This shall be achieved
+     * by a call to GattClient::reset() from the sub-class' reset()
+     * implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t reset(void) {
+        onDataReadCallbackChain.clear();
+        onDataWriteCallbackChain.clear();
+        onHVXCallbackChain.clear();
+
+        return BLE_ERROR_NONE;
+    }
+
 protected:
     GattClient() {
         /* Empty */

--- a/ble/GattServer.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/GattServer.h	Mon Jan 11 08:51:42 2016 +0000
@@ -396,6 +396,32 @@
         dataSentCallChain.call(count);
     }
 
+public:
+    /**
+     * 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
+     * state and not the data held in GattServer members. This shall be achieved
+     * by a call to GattServer::reset() from the sub-class' reset()
+     * implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t reset(void) {
+        serviceCount = 0;
+        characteristicCount = 0;
+
+        dataSentCallChain.clear();
+        dataWrittenCallChain.clear();
+        dataReadCallChain.clear();
+        updatesEnabledCallback = NULL;
+        updatesDisabledCallback = NULL;
+        confirmationReceivedCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
 protected:
     uint8_t serviceCount;
     uint8_t characteristicCount;

--- a/ble/SecurityManager.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/SecurityManager.h	Mon Jan 11 08:51:42 2016 +0000
@@ -231,6 +231,28 @@
         /* empty */
     }
 
+public:
+    /**
+     * 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
+     * state and not the data held in SecurityManager members. This shall be
+     * achieved by a call to SecurityManager::reset() from the sub-class'
+     * reset() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t reset(void) {
+        securitySetupInitiatedCallback = NULL;
+        securitySetupCompletedCallback = NULL;
+        linkSecuredCallback = NULL;
+        securityContextStoredCallback = NULL;
+        passkeyDisplayCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
 protected:
     SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
     SecuritySetupCompletedCallback_t securitySetupCompletedCallback;

--- a/ble/ServiceDiscovery.h	Mon Jan 11 08:51:41 2016 +0000
+++ b/ble/ServiceDiscovery.h	Mon Jan 11 08:51:42 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 reset its
+     * state and not the data held in ServiceDiscovery members. This shall be
+     * achieved by a call to ServiceDiscovery::reset() from the sub-class'
+     * reset() implementation.
+     *
+     * @return BLE_ERROR_NONE on success.
+     */
+    virtual ble_error_t reset(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;

--- a/source/BLE.cpp	Mon Jan 11 08:51:41 2016 +0000
+++ b/source/BLE.cpp	Mon Jan 11 08:51:42 2016 +0000
@@ -131,7 +131,6 @@
 
 ble_error_t BLE::shutdown(void)
 {
-    clearAdvertisingPayload();
     if (!transport) {
         error("bad handle to underlying transport");
     }

--- a/source/DiscoveredCharacteristic.cpp	Mon Jan 11 08:51:41 2016 +0000
+++ b/source/DiscoveredCharacteristic.cpp	Mon Jan 11 08:51:42 2016 +0000
@@ -151,17 +151,8 @@
     return error;
 }
 
-ble_error_t DiscoveredCharacteristic::discoverDescriptors(
-    const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered, 
-    const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const {
-
-    if(!gattc) {
-        return BLE_ERROR_INVALID_STATE;
-    }
-
-    ble_error_t err = gattc->discoverCharacteristicDescriptors(
-        *this, onCharacteristicDiscovered, onTermination
-    );
-
-    return err;
+ble_error_t
+DiscoveredCharacteristic::discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID) const
+{
+    return BLE_ERROR_NOT_IMPLEMENTED; /* TODO: this needs to be filled in. */
 }
\ No newline at end of file