Diff: ble/GattServer.h

Revision:

993:4d62b7967c11

Parent:

992:ca834f7ae8ed

Child:

1042:21a86ac7f5b1

diff -r ca834f7ae8ed -r 4d62b7967c11 ble/GattServer.h
--- a/ble/GattServer.h	Wed Dec 02 10:29:44 2015 +0000
+++ b/ble/GattServer.h	Wed Dec 02 10:29:44 2015 +0000
@@ -26,9 +26,18 @@
 
 class GattServer {
 public:
+
     /* Event callback handlers. */
-    typedef void (*EventCallback_t)(GattAttribute::Handle_t attributeHandle);
-    typedef void (*ServerEventCallback_t)(void);                    /**< independent of any particular attribute */
+    typedef FunctionPointerWithContext<unsigned> DataSentCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t;
+
+    typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t;    
+
+    typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t;
+    typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t;
+
+    typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t;
 
 protected:
     GattServer() :
@@ -53,14 +62,14 @@
      * characteristics contained within.
      */
     virtual ble_error_t addService(GattService &service) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)service;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Read the value of a characteristic from the local GattServer
+     * Read the value of a characteristic from the local GATT server.
      * @param[in]     attributeHandle
      *                  Attribute handle for the value attribute of the characteristic.
      * @param[out]    buffer
@@ -75,18 +84,18 @@
      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
      */
     virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)attributeHandle;
         (void)buffer;
         (void)lengthP;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Read the value of a characteristic from the local GattServer
+     * Read the value of a characteristic from the local GATT server.
      * @param[in]     connectionHandle
-     *                  Connection Handle.
+     *                  Connection handle.
      * @param[in]     attributeHandle
      *                  Attribute handle for the value attribute of the characteristic.
      * @param[out]    buffer
@@ -100,32 +109,32 @@
      *
      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
      *
-     * @note This API is a version of above with an additional connection handle
+     * @note This API is a version of the above, with an additional connection handle
      *     parameter to allow fetches for connection-specific multivalued
      *     attributes (such as the CCCDs).
      */
     virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)connectionHandle;
         (void)attributeHandle;
         (void)buffer;
         (void)lengthP;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Update the value of a characteristic on the local GattServer.
+     * Update the value of a characteristic on the local GATT server.
      *
      * @param[in] attributeHandle
-     *              Handle for the value attribute of the Characteristic.
+     *              Handle for the value attribute of the characteristic.
      * @param[in] value
-     *              A pointer to a buffer holding the new value
+     *              A pointer to a buffer holding the new value.
      * @param[in] size
      *              Size of the new value (in bytes).
      * @param[in] localOnly
      *              Should this update be kept on the local
-     *              GattServer regardless of the state of the
+     *              GATT server regardless of the state of the
      *              notify/indicate flag in the CCCD for this
      *              Characteristic? If set to true, no notification
      *              or indication is generated.
@@ -133,26 +142,26 @@
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      */
     virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)attributeHandle;
         (void)value;
         (void)size;
         (void)localOnly;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Update the value of a characteristic on the local GattServer. A version
-     * of the same as above with connection handle parameter to allow updates
+     * Update the value of a characteristic on the local GATT server. A version
+     * of the same as the above, with a connection handle parameter to allow updates
      * for connection-specific multivalued attributes (such as the CCCDs).
      *
      * @param[in] connectionHandle
-     *              Connection Handle.
+     *              Connection handle.
      * @param[in] attributeHandle
-     *              Handle for the value attribute of the Characteristic.
+     *              Handle for the value attribute of the characteristic.
      * @param[in] value
-     *              A pointer to a buffer holding the new value
+     *              A pointer to a buffer holding the new value.
      * @param[in] size
      *              Size of the new value (in bytes).
      * @param[in] localOnly
@@ -165,54 +174,54 @@
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      */
     virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)connectionHandle;
         (void)attributeHandle;
         (void)value;
         (void)size;
         (void)localOnly;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Determine the updates-enabled status (notification/indication) for the current connection from a characteristic's CCCD.
+     * Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD.
      *
      * @param       characteristic
-     *                The characteristic
+     *                The characteristic.
      * @param[out]  enabledP
      *                Upon return, *enabledP is true if updates are enabled, else false.
      *
-     * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
+     * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise.
      */
     virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)characteristic;
         (void)enabledP;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
-     * Determine the connection-specific updates-enabled status (notification/indication) from a characteristic's CCCD.
+     * Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD.
      *
      * @param       connectionHandle
-     *                The connection handle
+     *                The connection handle.
      * @param[out]  enabledP
      *                Upon return, *enabledP is true if updates are enabled, else false.
      *
      * @param  characteristic
-     *           The characteristic
+     *           The characteristic.
      *
-     * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
+     * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise.
      */
     virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) {
-        /* avoid compiler warnings about unused variables */
+        /* Avoid compiler warnings about unused variables. */
         (void)connectionHandle;
         (void)characteristic;
         (void)enabledP;
 
-        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /**
@@ -220,7 +229,7 @@
      * onDataRead(). It should be overridden to return true as applicable.
      */
     virtual bool isOnDataReadAvailable() const {
-        return false; /* Requesting action from porter(s): override this API if this capability is supported. */
+        return false; /* Requesting action from porters: override this API if this capability is supported. */
     }
 
     /*
@@ -231,60 +240,81 @@
      * Add a callback for the GATT event DATA_SENT (which is triggered when
      * updates are sent out by GATT in the form of notifications).
      *
-     * @Note: it is possible to chain together multiple onDataSent callbacks
+     * @Note: It is possible to chain together multiple onDataSent callbacks
      * (potentially from different modules of an application) to receive updates
      * to characteristics.
      *
-     * @Note: it is also possible to setup a callback into a member function of
+     * @Note: It is also possible to set up a callback into a member function of
      * some object.
      */
-    void onDataSent(void (*callback)(unsigned count)) {dataSentCallChain.add(callback);}
+    void onDataSent(const DataSentCallback_t& callback) {dataSentCallChain.add(callback);}
     template <typename T>
     void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
         dataSentCallChain.add(objPtr, memberPtr);
     }
 
     /**
-     * Setup a callback for when an attribute has its value updated by or at the
-     * connected peer. For a peripheral, this callback triggered when the local
+     * @brief get the callback chain called when the event DATA_EVENT is triggered. 
+     */
+    DataSentCallbackChain_t& onDataSent() { 
+        return dataSentCallChain;
+    }
+
+    /**
+     * Set up a callback for when an attribute has its value updated by or at the
+     * connected peer. For a peripheral, this callback is triggered when the local
      * GATT server has an attribute updated by a write command from the peer.
-     * For a Central, this callback is triggered when a response is received for
+     * For a central, this callback is triggered when a response is received for
      * a write request.
      *
-     * @Note: it is possible to chain together multiple onDataWritten callbacks
+     * @Note: It is possible to chain together multiple onDataWritten callbacks
      * (potentially from different modules of an application) to receive updates
-     * to characteristics. Many services, such as DFU and UART add their own
+     * to characteristics. Many services, such as DFU and UART, add their own
      * onDataWritten callbacks behind the scenes to trap interesting events.
      *
-     * @Note: it is also possible to setup a callback into a member function of
+     * @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 onDataWritten().detach(callback)
      */
-    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {dataWrittenCallChain.add(callback);}
+    void onDataWritten(const DataWrittenCallback_t& callback) {dataWrittenCallChain.add(callback);}
     template <typename T>
     void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
         dataWrittenCallChain.add(objPtr, memberPtr);
     }
 
     /**
+     * @brief provide access to the callchain of data written event callbacks
+     * It is possible to register callbacks using onDataWritten().add(callback);
+     * It is possible to unregister callbacks using onDataWritten().detach(callback) 
+     * @return The data written event callbacks chain
+     */    
+    DataWrittenCallbackChain_t& onDataWritten() {
+        return dataWrittenCallChain;
+    }
+
+    /**
      * Setup a callback to be invoked on the peripheral when an attribute is
      * being read by a remote client.
      *
-     * @Note: this functionality may not be available on all underlying stacks.
+     * @Note: This functionality may not be available on all underlying stacks.
      * You could use GattCharacteristic::setReadAuthorizationCallback() as an
      * alternative. Refer to isOnDataReadAvailable().
      *
-     * @Note: it is possible to chain together multiple onDataRead callbacks
+     * @Note: It is possible to chain together multiple onDataRead callbacks
      * (potentially from different modules of an application) to receive updates
      * to characteristics. Services may add their own onDataRead callbacks
      * behind the scenes to trap interesting events.
      *
-     * @Note: it is also possible to setup a callback into a member function of
+     * @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 onDataRead().detach(callback)
+     *
      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
      *         else BLE_ERROR_NONE.
      */
-    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
+    ble_error_t onDataRead(const DataReadCallback_t& callback) {
         if (!isOnDataReadAvailable()) {
             return BLE_ERROR_NOT_IMPLEMENTED;
         }
@@ -303,19 +333,29 @@
     }
 
     /**
-     * Setup a callback for when notifications/indications are enabled for a
-     * characteristic on the local GattServer.
+     * @brief provide access to the callchain of data read event callbacks
+     * It is possible to register callbacks using onDataRead().add(callback);
+     * It is possible to unregister callbacks using onDataRead().detach(callback) 
+     * @return The data read event callbacks chain
+     */
+    DataReadCallbackChain_t& onDataRead() {
+        return dataReadCallChain;
+    }
+
+    /**
+     * Set up a callback for when notifications or indications are enabled for a
+     * characteristic on the local GATT server.
      */
     void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
 
     /**
-     * Setup a callback for when notifications/indications are disabled for a
-     * characteristic on the local GattServer.
+     * Set up a callback for when notifications or indications are disabled for a
+     * characteristic on the local GATT server.
      */
     void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
 
     /**
-     * Setup a callback for when the GATT server receives a response for an
+     * Set up a callback for when the GATT server receives a response for an
      * indication event sent previously.
      */
     void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
@@ -323,15 +363,11 @@
     /* Entry points for the underlying stack to report events back to the user. */
 protected:
     void handleDataWrittenEvent(const GattWriteCallbackParams *params) {
-        if (dataWrittenCallChain.hasCallbacksAttached()) {
-            dataWrittenCallChain.call(params);
-        }
+        dataWrittenCallChain.call(params);
     }
 
     void handleDataReadEvent(const GattReadCallbackParams *params) {
-        if (dataReadCallChain.hasCallbacksAttached()) {
-            dataReadCallChain.call(params);
-        }
+        dataReadCallChain.call(params);
     }
 
     void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) {
@@ -357,9 +393,7 @@
     }
 
     void handleDataSentEvent(unsigned count) {
-        if (dataSentCallChain.hasCallbacksAttached()) {
-            dataSentCallChain.call(count);
-        }
+        dataSentCallChain.call(count);
     }
 
 protected:
@@ -367,15 +401,15 @@
     uint8_t characteristicCount;
 
 private:
-    CallChainOfFunctionPointersWithContext<unsigned>                        dataSentCallChain;
-    CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> dataWrittenCallChain;
-    CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>  dataReadCallChain;
-    EventCallback_t                                                         updatesEnabledCallback;
-    EventCallback_t                                                         updatesDisabledCallback;
-    EventCallback_t                                                         confirmationReceivedCallback;
+    DataSentCallbackChain_t    dataSentCallChain;
+    DataWrittenCallbackChain_t dataWrittenCallChain;
+    DataReadCallbackChain_t    dataReadCallChain;
+    EventCallback_t            updatesEnabledCallback;
+    EventCallback_t            updatesDisabledCallback;
+    EventCallback_t            confirmationReceivedCallback;
 
 private:
-    /* disallow copy and assignment */
+    /* Disallow copy and assignment. */
     GattServer(const GattServer &);
     GattServer& operator=(const GattServer &);
 };