Diff: ble/GattClient.h

Revision:

1064:187f9929cb60

Parent:

1063:a3fd424b73ca

Child:

1073:dd09fe419587

diff -r a3fd424b73ca -r 187f9929cb60 ble/GattClient.h
--- a/ble/GattClient.h	Mon Jan 11 08:51:37 2016 +0000
+++ b/ble/GattClient.h	Mon Jan 11 08:51:37 2016 +0000
@@ -20,6 +20,7 @@
 #include "Gap.h"
 #include "GattAttribute.h"
 #include "ServiceDiscovery.h"
+#include "CharacteristicDescriptorDiscovery.h"
 
 #include "GattCallbackParamTypes.h"
 
@@ -305,6 +306,53 @@
     }
 
     /**
+     * @brief launch discovery of descriptors for a given characteristic
+     * @details This function will discover all descriptors available for a 
+     * specific characteristic. 
+     * 
+     * @param characteristic The characteristic targeted by this discovery
+     * @param callback This is the application callback for each descriptors 
+     * found. 
+     * @note service discovery may still be active when the callback is issued; 
+     * calling asynchronous BLE-stack APIs from within this application callback 
+     * might cause the stack to abort the discovery. If this becomes an issue, 
+     * it may be better to make local copy of the DiscoveredCharacteristicDescriptor 
+     * and wait for characteristic descriptor discovery to terminate before 
+     * operating on the descriptor.
+     * 
+     * @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;
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+    }
+
+    /**
+     * Is characteristic descriptor discovery currently active?
+     */
+    virtual bool isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const 
+     {
+        (void) characteristic;
+        return false; /* Requesting action from porter(s): override this API if this capability is supported. */
+    }
+
+    /**
+     * Terminate an ongoing characteristic descriptor discovery. This should result 
+     * in an invocation of the TerminationCallback if characteristic descriptor discovery is active.
+     */
+    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.
@@ -326,46 +374,6 @@
     }
 
 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 */
     }
@@ -391,10 +399,6 @@
     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 &);