Diff: public/GattServer.h

Revision:

710:b2e1a2660ec2

Parent:

701:19873f48d07b

--- a/public/GattServer.h	Fri Jun 19 15:53:06 2015 +0100
+++ b/public/GattServer.h	Fri Jun 19 15:53:28 2015 +0100
@@ -21,7 +21,7 @@
 #include "GattService.h"
 #include "GattAttribute.h"
 #include "GattServerEvents.h"
-#include "GattCallbackParamTypes.h"
+#include "GattCharacteristicCallbackParams.h"
 #include "CallChainOfFunctionPointersWithContext.h"
 
 class GattServer {
@@ -34,118 +34,39 @@
     GattServer() :
         serviceCount(0),
         characteristicCount(0),
-        dataSentCallChain(),
-        dataWrittenCallChain(),
-        dataReadCallChain(),
-        updatesEnabledCallback(NULL),
-        updatesDisabledCallback(NULL),
-        confirmationReceivedCallback(NULL) {
+        onDataSent(),
+        onDataWritten(),
+        onDataRead(),
+        onUpdatesEnabled(NULL),
+        onUpdatesDisabled(NULL),
+        onConfirmationReceived(NULL) {
         /* empty */
     }
 
-    /*
-     * The following functions are meant to be overridden in the platform-specific sub-class.
-     */
-public:
-
-    /**
-     * Add a service declaration to the local server ATT table. Also add the
-     * characteristics contained within.
-     */
-    virtual ble_error_t addService(GattService &) {
-        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
-    }
-
-    /**
-     * Read the value of a characteristic from the local GattServer
-     * @param[in]     attributeHandle
-     *                  Attribute handle for the value attribute of the characteristic.
-     * @param[out]    buffer
-     *                  A buffer to hold the value being read.
-     * @param[in/out] lengthP
-     *                  Length of the buffer being supplied. If the attribute
-     *                  value is longer than the size of the supplied buffer,
-     *                  this variable will hold upon return the total attribute value length
-     *                  (excluding offset). The application may use this
-     *                  information to allocate a suitable buffer size.
-     *
-     * @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) {
-        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
-    }
+    friend class BLEDevice;
+private:
+    /* These functions must be defined in the sub-class */
+    virtual ble_error_t addService(GattService &)                                                               = 0;
+    virtual ble_error_t readValue(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) = 0;
+    virtual ble_error_t readValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) = 0;
+    virtual ble_error_t updateValue(GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false) = 0;
+    virtual ble_error_t updateValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false) = 0;
+    virtual ble_error_t initializeGATTDatabase(void)                                                            = 0;
 
-    /**
-     * Read the value of a characteristic from the local GattServer
-     * @param[in]     connectionHandle
-     *                  Connection Handle.
-     * @param[in]     attributeHandle
-     *                  Attribute handle for the value attribute of the characteristic.
-     * @param[out]    buffer
-     *                  A buffer to hold the value being read.
-     * @param[in/out] lengthP
-     *                  Length of the buffer being supplied. If the attribute
-     *                  value is longer than the size of the supplied buffer,
-     *                  this variable will hold upon return the total attribute value length
-     *                  (excluding offset). The application may use this
-     *                  information to allocate a suitable buffer size.
-     *
-     * @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
-     *     parameter to allow fetches for connection-specific multivalued
-     *     attribtues (such as the CCCDs).
-     */
-    virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
-        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
-    }
+    // ToDo: For updateValue, check the CCCD to see if the value we are
+    // updating has the notify or indicate bits sent, and if BOTH are set
+    // be sure to call sd_ble_gatts_hvx() twice with notify then indicate!
+    // Strange use case, but valid and must be covered!
 
-    /**
-     * Update the value of a characteristic on the local GattServer.
-     *
-     * @param[in] attributeHandle
-     *              Handle for the value attribute of the Characteristic.
-     * @param[in] 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
-     *              notify/indicate flag in the CCCD for this
-     *              Characteristic? If set to true, no notification
-     *              or indication is generated.
-     *
-     * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
-     */
-    virtual ble_error_t write(GattAttribute::Handle_t, const uint8_t *, uint16_t, bool localOnly = false) {
-        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
+    void setOnDataSent(void (*callback)(unsigned count)) {onDataSent.add(callback);}
+    template <typename T>
+    void setOnDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
+        onDataSent.add(objPtr, memberPtr);
     }
-
-    /**
-     * Update the value of a characteristic on the local GattServer. A version
-     * of the same as above with connection handle parameter to allow updates
-     * for connection-specific multivalued attribtues (such as the CCCDs).
-     *
-     * @param[in] connectionHandle
-     *              Connection Handle.
-     * @param[in] attributeHandle
-     *              Handle for the value attribute of the Characteristic.
-     * @param[in] 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
-     *              notify/indicate flag in the CCCD for this
-     *              Characteristic? If set to true, no notification
-     *              or indication is generated.
-     *
-     * @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, const uint8_t *, uint16_t, bool localOnly = false) {
-        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
+    void setOnDataWritten(void (*callback)(const GattCharacteristicWriteCBParams *eventDataP)) {onDataWritten.add(callback);}
+    template <typename T>
+    void setOnDataWritten(T *objPtr, void (T::*memberPtr)(const GattCharacteristicWriteCBParams *context)) {
+        onDataWritten.add(objPtr, memberPtr);
     }
 
     /**
@@ -153,135 +74,57 @@
      * onDataRead(). It should be overridden to return true as applicable.
      */
     virtual bool isOnDataReadAvailable() const {
-        return false; /* default implementation; override this API if this capability is supported. */
+        return false;
     }
-
-    /*
-     * APIs with non-virtual implementations.
-     */
-public:
-    /**
-     * 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
-     * (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
-     * some object.
-     */
-    void onDataSent(void (*callback)(unsigned count)) {dataSentCallChain.add(callback);}
-    template <typename T>
-    void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
-        dataSentCallChain.add(objPtr, memberPtr);
-    }
+    ble_error_t setOnDataRead(void (*callback)(const GattCharacteristicReadCBParams *eventDataP)) {
+        if (!isOnDataReadAvailable()) {
+            return BLE_ERROR_NOT_IMPLEMENTED;
+        }
 
-    /**
-     * 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
-     * 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
-     * a write request.
-     *
-     * @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
-     * onDataWritten callbacks behind the scenes to trap interesting events.
-     *
-     * @Note: it is also possible to setup a callback into a member function of
-     * some object.
-     */
-    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {dataWrittenCallChain.add(callback);}
-    template <typename T>
-    void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
-        dataWrittenCallChain.add(objPtr, memberPtr);
+        onDataRead.add(callback);
+        return BLE_ERROR_NONE;
     }
-
-    /**
-     * 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.
-     * You could use GattCharacteristic::setReadAuthorizationCallback() as an
-     * alternative.
-     *
-     * @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
-     * some object.
-     *
-     * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
-     *         else BLE_ERROR_NONE.
-     */
-    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
+    template <typename T>
+    ble_error_t setOnDataRead(T *objPtr, void (T::*memberPtr)(const GattCharacteristicReadCBParams *context)) {
         if (!isOnDataReadAvailable()) {
             return BLE_ERROR_NOT_IMPLEMENTED;
         }
 
-        dataReadCallChain.add(callback);
-        return BLE_ERROR_NONE;
-    }
-    template <typename T>
-    ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
-        if (!isOnDataReadAvailable()) {
-            return BLE_ERROR_NOT_IMPLEMENTED;
-        }
-
-        dataReadCallChain.add(objPtr, memberPtr);
+        onDataRead.add(objPtr, memberPtr);
         return BLE_ERROR_NONE;
     }
-
-    /**
-     * Setup a callback for when notifications/indications are enabled for a
-     * characteristic on the local GattServer.
-     */
-    void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
+    void setOnUpdatesEnabled(EventCallback_t callback)       {onUpdatesEnabled       = callback;}
+    void setOnUpdatesDisabled(EventCallback_t callback)      {onUpdatesDisabled      = callback;}
+    void setOnConfirmationReceived(EventCallback_t callback) {onConfirmationReceived = callback;}
 
-    /**
-     * Setup a callback for when notifications/indications are disabled for a
-     * characteristic on the local GattServer.
-     */
-    void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
-
-    /**
-     * Setup a callback for when the GATT server receives a response for an
-     * indication event sent previously.
-     */
-    void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
-
-    /* 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);
+    void handleDataWrittenEvent(const GattCharacteristicWriteCBParams *params) {
+        if (onDataWritten.hasCallbacksAttached()) {
+            onDataWritten.call(params);
         }
     }
 
-    void handleDataReadEvent(const GattReadCallbackParams *params) {
-        if (dataReadCallChain.hasCallbacksAttached()) {
-            dataReadCallChain.call(params);
+    void handleDataReadEvent(const GattCharacteristicReadCBParams *params) {
+        if (onDataRead.hasCallbacksAttached()) {
+            onDataRead.call(params);
         }
     }
 
     void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t charHandle) {
         switch (type) {
             case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
-                if (updatesEnabledCallback) {
-                    updatesEnabledCallback(charHandle);
+                if (onUpdatesEnabled) {
+                    onUpdatesEnabled(charHandle);
                 }
                 break;
             case GattServerEvents::GATT_EVENT_UPDATES_DISABLED:
-                if (updatesDisabledCallback) {
-                    updatesDisabledCallback(charHandle);
+                if (onUpdatesDisabled) {
+                    onUpdatesDisabled(charHandle);
                 }
                 break;
             case GattServerEvents::GATT_EVENT_CONFIRMATION_RECEIVED:
-                if (confirmationReceivedCallback) {
-                    confirmationReceivedCallback(charHandle);
+                if (onConfirmationReceived) {
+                    onConfirmationReceived(charHandle);
                 }
                 break;
             default:
@@ -290,8 +133,8 @@
     }
 
     void handleDataSentEvent(unsigned count) {
-        if (dataSentCallChain.hasCallbacksAttached()) {
-            dataSentCallChain.call(count);
+        if (onDataSent.hasCallbacksAttached()) {
+            onDataSent.call(count);
         }
     }
 
@@ -300,12 +143,12 @@
     uint8_t characteristicCount;
 
 private:
-    CallChainOfFunctionPointersWithContext<unsigned>                        dataSentCallChain;
-    CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> dataWrittenCallChain;
-    CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>  dataReadCallChain;
-    EventCallback_t                                                         updatesEnabledCallback;
-    EventCallback_t                                                         updatesDisabledCallback;
-    EventCallback_t                                                         confirmationReceivedCallback;
+    CallChainOfFunctionPointersWithContext<unsigned>                                onDataSent;
+    CallChainOfFunctionPointersWithContext<const GattCharacteristicWriteCBParams *> onDataWritten;
+    CallChainOfFunctionPointersWithContext<const GattCharacteristicReadCBParams *>  onDataRead;
+    EventCallback_t                                                                 onUpdatesEnabled;
+    EventCallback_t                                                                 onUpdatesDisabled;
+    EventCallback_t                                                                 onConfirmationReceived;
 
 private:
     /* disallow copy and assignment */