fix GattServer::onDataRead()

public/BLE.h

@@ -1172,7 +1172,8 @@ public:
     }
 
     /**
-     * Setup a callback for when a characteristic is being read by a client.
+     * 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
@@ -1188,9 +1189,18 @@ public:
      *
      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
      *         else BLE_ERROR_NONE.
+     *
+     * @note: This API is now *deprecated* and will be dropped in the future.
+     * You should use the parallel API from GattServer directly. A former call
+     * to ble.onDataRead(...) should be replaced with
+     * ble.gattServer().onDataRead(...).
      */
-    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP));
-    template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context));
+    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
+        return gattServer().onDataRead(callback);
+    }
+    template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
+        return gattServer().onDataRead(objPtr, memberPtr);
+    }
 
     /**
      * Setup a callback for when notifications/indications are enabled for a
@@ -1300,16 +1310,6 @@ typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake o
 /* BLE methods. Most of these simply forward the calls to the underlying
  * transport.*/
 
-inline ble_error_t
-BLE::onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
-    return transport->getGattServer().setOnDataRead(callback);
-}
-
-template <typename T> inline ble_error_t
-BLE::onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
-    return transport->getGattServer().setOnDataRead(objPtr, memberPtr);
-}
-
 inline void
 BLE::onUpdatesDisabled(GattServer::EventCallback_t callback)
 {

public/GattServer.h

@@ -36,7 +36,7 @@ protected:
         characteristicCount(0),
         dataSentCallChain(),
         dataWrittenCallChain(),
-        onDataRead(),
+        dataReadCallChain(),
         updatesEnabledCallback(NULL),
         onUpdatesDisabled(NULL),
         onConfirmationReceived(NULL) {
@@ -188,21 +188,41 @@ public:
     virtual bool isOnDataReadAvailable() const {
         return false;
     }
-    ble_error_t setOnDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
+
+    /**
+     * 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)) {
         if (!isOnDataReadAvailable()) {
             return BLE_ERROR_NOT_IMPLEMENTED;
         }
 
-        onDataRead.add(callback);
+        dataReadCallChain.add(callback);
         return BLE_ERROR_NONE;
     }
     template <typename T>
-    ble_error_t setOnDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
+    ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
         if (!isOnDataReadAvailable()) {
             return BLE_ERROR_NOT_IMPLEMENTED;
         }
 
-        onDataRead.add(objPtr, memberPtr);
+        dataReadCallChain.add(objPtr, memberPtr);
         return BLE_ERROR_NONE;
     }
 
@@ -223,8 +243,8 @@ protected:
     }
 
     void handleDataReadEvent(const GattReadCallbackParams *params) {
-        if (onDataRead.hasCallbacksAttached()) {
-            onDataRead.call(params);
+        if (dataReadCallChain.hasCallbacksAttached()) {
+            dataReadCallChain.call(params);
         }
     }
 
@@ -263,7 +283,7 @@ protected:
 private:
     CallChainOfFunctionPointersWithContext<unsigned>                        dataSentCallChain;
     CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> dataWrittenCallChain;
-    CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>  onDataRead;
+    CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>  dataReadCallChain;
     EventCallback_t                                                         updatesEnabledCallback;
     EventCallback_t                                                         onUpdatesDisabled;
     EventCallback_t                                                         onConfirmationReceived;