Diff: public/GattCharacteristic.h

Revision:

257:6be2b4b0cd71

Parent:

255:097be53aea02

--- a/public/GattCharacteristic.h	Tue Dec 02 02:51:52 2014 +0000
+++ b/public/GattCharacteristic.h	Mon Jan 12 14:49:53 2015 -0800
@@ -18,6 +18,8 @@
 #define __GATT_CHARACTERISTIC_H__
 
 #include "GattAttribute.h"
+#include "GattCharacteristicWriteCBParams.h"
+#include "FunctionPointerWithContext.h"
 
 class GattCharacteristic {
 public:
@@ -289,44 +291,120 @@
     } presentation_format_t;
 
     /**
-      *  @brief  Creates a new GattCharacteristic using the specified 16-bit
-      *          UUID, value length, and properties
-      *
-      *  @note   The UUID value must be unique in the service and is normally >1
-      *
-      *  @param[in]  uuid
-      *              The UUID to use for this characteristic
-      *  @param[in]  valuePtr
-      *              The memory holding the initial value. The value is copied
-      *              into the stack when the enclosing service is added; and
-      *              thereafter maintained internally by the stack.
-      *  @param[in]  initialLen
-      *              The min length in bytes of this characteristic's value
-      *  @param[in]  maxLen
-      *              The max length in bytes of this characteristic's value
-      *  @param[in]  props
-      *              The 8-bit bit field containing the characteristic's properties
-      *  @param[in]  descriptors
-      *              A pointer to an array of descriptors to be included within this characteristic
-      *  @param[in]  numDescriptors
-      *              The number of descriptors
-      *
-      * @NOTE: If valuePtr == NULL, initialLength == 0, and properties == READ
-      *        for the value attribute of a characteristic, then that particular
-      *        characteristic may be considered optional and dropped while
-      *        instantiating the service with the underlying BLE stack.
-      */
-    /**************************************************************************/
-    GattCharacteristic(const UUID &uuid, uint8_t *valuePtr = NULL, uint16_t initialLen = 0, uint16_t maxLen = 0,
-                       uint8_t props = BLE_GATT_CHAR_PROPERTIES_NONE,
-                       GattAttribute *descriptors[] = NULL, unsigned numDescriptors = 0) :
-        _valueAttribute(uuid, valuePtr, initialLen, maxLen), _properties(props), _descriptors(descriptors), _descriptorCount(numDescriptors) {
+     *  @brief  Creates a new GattCharacteristic using the specified 16-bit
+     *          UUID, value length, and properties
+     *
+     *  @note   The UUID value must be unique in the service and is normally >1
+     *
+     *  @param[in]  uuid
+     *              The UUID to use for this characteristic
+     *  @param[in]  valuePtr
+     *              The memory holding the initial value. The value is copied
+     *              into the stack when the enclosing service is added; and
+     *              thereafter maintained internally by the stack.
+     *  @param[in]  initialLen
+     *              The min length in bytes of this characteristic's value
+     *  @param[in]  maxLen
+     *              The max length in bytes of this characteristic's value
+     *  @param[in]  props
+     *              The 8-bit bit field containing the characteristic's properties
+     *  @param[in]  descriptors
+     *              A pointer to an array of descriptors to be included within this characteristic
+     *  @param[in]  numDescriptors
+     *              The number of descriptors
+     *  @param[in]  writeAuthorizationIn
+     *              Do the attribute(s) of this characteristic have write
+     *              authorization enabled? if so, Write Authorization will be
+     *              requested from the application on every write request
+     *              operation (but not write command).
+     *
+     * @NOTE: If valuePtr == NULL, initialLength == 0, and properties == READ
+     *        for the value attribute of a characteristic, then that particular
+     *        characteristic may be considered optional and dropped while
+     *        instantiating the service with the underlying BLE stack.
+     */
+    GattCharacteristic(const UUID    &uuid,
+                       uint8_t       *valuePtr            = NULL,
+                       uint16_t       initialLen          = 0,
+                       uint16_t       maxLen              = 0,
+                       uint8_t        props               = BLE_GATT_CHAR_PROPERTIES_NONE,
+                       GattAttribute *descriptors[]       = NULL,
+                       unsigned       numDescriptors      = 0) :
+        _valueAttribute(uuid, valuePtr, initialLen, maxLen),
+        _properties(props),
+        _descriptors(descriptors),
+        _descriptorCount(numDescriptors),
+        enabledReadAuthorization(false),
+        enabledWriteAuthorization(false),
+        readAuthorizationCallback(),
+        writeAuthorizationCallback() {
+        /* empty */
     }
 
+    /**
+     * Authorization.
+     */
 public:
-    GattAttribute& getValueAttribute()            {return _valueAttribute; }
-    uint8_t        getProperties(void)      const {return _properties;     }
-    uint8_t        getDescriptorCount(void) const {return _descriptorCount;}
+    void setWriteAuthorizationCallback(void (*callback)(GattCharacteristicWriteAuthCBParams *)) {
+        writeAuthorizationCallback.attach(callback);
+        enabledWriteAuthorization = true;
+    }
+    template <typename T>
+    void setWriteAuthorizationCallback(T *object, void (T::*member)(GattCharacteristicWriteAuthCBParams *)) {
+        writeAuthorizationCallback.attach(object, member);
+        enabledWriteAuthorization = true;
+    }
+    void setReadAuthorizationCallback(void (*callback)(GattCharacteristicReadAuthCBParams *)) {
+        readAuthorizationCallback.attach(callback);
+        enabledReadAuthorization = true;
+    }
+    template <typename T>
+    void setReadAuthorizationCallback(T *object, void (T::*member)(GattCharacteristicReadAuthCBParams *)) {
+        readAuthorizationCallback.attach(object, member);
+        enabledReadAuthorization = true;
+    }
+
+    /**
+     * Helper function meant to be called from the guts of the BLE stack to
+     * determine the authorization reply for a write request.
+     * @param  params to capture the context of the write-auth request; and also contains an out-parameter for reply.
+     * @return        true if the write is authorized to proceed.
+     */
+    bool authorizeWrite(GattCharacteristicWriteAuthCBParams *params) {
+        if (!isWriteAuthorizationEnabled()) {
+            return true;
+        }
+
+        params->authorizationReply = true; /* initialized to true by default */
+        writeAuthorizationCallback.call(params);
+        return params->authorizationReply;
+    }
+
+    /**
+     * Helper function meant to be called from the guts of the BLE stack to
+     * determine the authorization reply for a read request.
+     * @param  params to capture the context of the read-auth request; and also contains an out-parameter for reply.
+     * @return        true if the read is authorized to proceed.
+     */
+    bool authorizeRead(GattCharacteristicReadAuthCBParams *params) {
+        if (!isReadAuthorizationEnabled()) {
+            return true;
+        }
+
+        params->authorizationReply = true; /* initialized to true by default */
+        readAuthorizationCallback.call(params);
+        return params->authorizationReply;
+    }
+
+    /* accessors */
+public:
+    GattAttribute&          getValueAttribute()                 {return _valueAttribute;                }
+    const GattAttribute&    getValueAttribute()           const {return _valueAttribute;                }
+    GattAttribute::Handle_t getValueHandle(void)          const {return getValueAttribute().getHandle();}
+    uint8_t                 getProperties(void)           const {return _properties;                    }
+    uint8_t                 getDescriptorCount(void)      const {return _descriptorCount;               }
+    bool                    isReadAuthorizationEnabled()  const {return enabledReadAuthorization;       }
+    bool                    isWriteAuthorizationEnabled() const {return enabledWriteAuthorization;      }
 
     GattAttribute *getDescriptor(uint8_t index) {
         if (index >= _descriptorCount) {
@@ -342,6 +420,11 @@
     GattAttribute **_descriptors;
     uint8_t         _descriptorCount;
 
+    bool            enabledReadAuthorization;
+    bool            enabledWriteAuthorization;
+    FunctionPointerWithContext<GattCharacteristicReadAuthCBParams *>  readAuthorizationCallback;
+    FunctionPointerWithContext<GattCharacteristicWriteAuthCBParams *> writeAuthorizationCallback;
+
 private:
     /* disallow copy and assignment */
     GattCharacteristic(const GattCharacteristic &);