Revision 253:097be53aea02, committed 2014-12-12

Comitter:

rgrover1

Date:

Fri Dec 12 13:32:24 2014 +0000

Parent:

252:69d049317cae

Child:

254:fb2a891a0d98

Commit message:

Synchronized with git rev 2552bf25
Author: Rohit Grover
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.

Changed in this revision

--- a/public/GattCharacteristic.h	Fri Dec 12 13:32:24 2014 +0000
+++ b/public/GattCharacteristic.h	Fri Dec 12 13:32:24 2014 +0000
@@ -334,15 +334,17 @@
         _properties(props),
         _descriptors(descriptors),
         _descriptorCount(numDescriptors),
+        enabledReadAuthorization(false),
         enabledWriteAuthorization(false),
+        readAuthorizationCallback(),
         writeAuthorizationCallback() {
         /* empty */
     }
 
+    /**
+     * Authorization.
+     */
 public:
-    /**
-     * Setup write authorization.
-     */
     void setWriteAuthorizationCallback(void (*callback)(GattCharacteristicWriteAuthCBParams *)) {
         writeAuthorizationCallback.attach(callback);
         enabledWriteAuthorization = true;
@@ -352,6 +354,15 @@
         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 @@
         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 @@
     uint8_t         _properties;
     GattAttribute **_descriptors;
     uint8_t         _descriptorCount;
+
+    bool            enabledReadAuthorization;
     bool            enabledWriteAuthorization;
+    FunctionPointerWithContext<GattCharacteristicReadAuthCBParams *>  readAuthorizationCallback;
     FunctionPointerWithContext<GattCharacteristicWriteAuthCBParams *> writeAuthorizationCallback;
 
 private:

--- a/public/GattCharacteristicWriteCBParams.h	Fri Dec 12 13:32:24 2014 +0000
+++ b/public/GattCharacteristicWriteCBParams.h	Fri Dec 12 13:32:24 2014 +0000
@@ -42,4 +42,11 @@
                                                   * 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__*/
\ No newline at end of file

--- a/public/GattServerEvents.h	Fri Dec 12 13:32:24 2014 +0000
+++ b/public/GattServerEvents.h	Fri Dec 12 13:32:24 2014 +0000
@@ -31,7 +31,8 @@
         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;
 };