Release 0.2.9

=============

API enhancements to support read/write authorization for GATT accesses.

Enhancements
~~~~~~~~~~~~

* Add support for authorization, whereby the user application can receive a
  callback to authorize a read or a write on a characteristic's value
  attribute before GATT commits the transaction. We now have an API for
  GattCharacterisitc called setWriteAuthorizationCallback() which can filter
  incoming access requests before they get applied to the GATT database.

Bugfixes
~~~~~~~~

Compatibility
~~~~~~~~~~~~~

This release is backward compatible with 0.2.4.

public/GattCharacteristic.h

@@ -334,15 +334,17 @@ public:
         _properties(props),
         _descriptors(descriptors),
         _descriptorCount(numDescriptors),
+        enabledReadAuthorization(false),
         enabledWriteAuthorization(false),
+        readAuthorizationCallback(),
         writeAuthorizationCallback() {
         /* empty */
     }
 
-public:
     /**
-     * Setup write authorization.
+     * Authorization.
      */
+public:
     void setWriteAuthorizationCallback(void (*callback)(GattCharacteristicWriteAuthCBParams *)) {
         writeAuthorizationCallback.attach(callback);
         enabledWriteAuthorization = true;
@@ -352,6 +354,15 @@ public:
         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
@@ -369,11 +380,30 @@ public:
         return params->authorizationReply;
     }
 
-    GattAttribute&          getValueAttribute()                 {return _valueAttribute; }
-    const GattAttribute&    getValueAttribute()           const {return _valueAttribute; }
+    /**
+     * 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;}
+    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) {
@@ -389,7 +419,10 @@ private:
     uint8_t         _properties;
     GattAttribute **_descriptors;
     uint8_t         _descriptorCount;
+
+    bool            enabledReadAuthorization;
     bool            enabledWriteAuthorization;
+    FunctionPointerWithContext<GattCharacteristicReadAuthCBParams *>  readAuthorizationCallback;
     FunctionPointerWithContext<GattCharacteristicWriteAuthCBParams *> writeAuthorizationCallback;
 
 private:

public/GattCharacteristicWriteCBParams.h

@@ -42,4 +42,11 @@ struct GattCharacteristicWriteAuthCBParams {
                                                   * request is to proceed; false otherwise. */
 };
 
+struct GattCharacteristicReadAuthCBParams {
+    GattAttribute::Handle_t  charHandle;
+    uint16_t                 offset; /**< Offset for the write operation. */
+    bool                     authorizationReply; /* This is the out parameter which needs to be set to true by the callback if the
+                                                  * request is to proceed; false otherwise. */
+};
+
 #endif /*__GATT_CHARACTERISTIC_WRITE_CB_PARAMS_H__*/

public/GattServerEvents.h

@@ -31,7 +31,8 @@ public:
         GATT_EVENT_UPDATES_ENABLED         = 3,  /**< Notify/Indicate Enabled in CCCD */
         GATT_EVENT_UPDATES_DISABLED        = 4,  /**< Notify/Indicate Disabled in CCCD */
         GATT_EVENT_CONFIRMATION_RECEIVED   = 5,  /**< Response received from Indicate message */
-        GATT_EVENT_WRITE_AUTHORIZATION_REQ = 6,  /**< Request application to authorize write */
+        GATT_EVENT_READ_AUTHORIZATION_REQ  = 6,  /**< Request application to authorize read */
+        GATT_EVENT_WRITE_AUTHORIZATION_REQ = 7,  /**< Request application to authorize write */
     } gattEvent_t;
 };