From 962533e39f5a86de7a60d7d0b2a2ed0fcd7b9656 Mon Sep 17 00:00:00 2001
From: Rohit Grover <rohit.grover@arm.com>
Date: Fri, 19 Jun 2015 08:37:04 +0100
Subject: [PATCH] fix GattServer::onDataWritten()

---
 public/BLE.h        | 30 ++++++++++++++++--------------
 public/GattServer.h | 37 ++++++++++++++++++++++++++-----------
 2 files changed, 42 insertions(+), 25 deletions(-)

diff --git a/public/BLE.h b/public/BLE.h
index 71828ca..9fe99dd 100644
--- a/public/BLE.h
+++ b/public/BLE.h
@@ -1145,8 +1145,11 @@ public:
     }
 
     /**
-     * Setup a callback for when a characteristic has its value updated by a
-     * client.
+     * 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
@@ -1155,9 +1158,18 @@ public:
      *
      * @Note: it is also possible to setup a callback into a member function of
      * some object.
+     *
+     * @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.onDataWritten(...) should be replaced with
+     * ble.gap().onDataWritten(...).
      */
-    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP));
-    template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context));
+    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
+        gattServer().onDataWritten(callback);
+    }
+    template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
+        gattServer().onDataWritten(objPtr, memberPtr);
+    }
 
     /**
      * Setup a callback for when a characteristic is being read by a client.
@@ -1276,16 +1288,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 void
-BLE::onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
-    transport->getGattServer().setOnDataWritten(callback);
-}
-
-template <typename T> inline void
-BLE::onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
-    transport->getGattServer().setOnDataWritten(objPtr, memberPtr);
-}
-
 inline ble_error_t
 BLE::onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
     return transport->getGattServer().setOnDataRead(callback);
diff --git a/public/GattServer.h b/public/GattServer.h
index 7b9bd03..18f9aa0 100644
--- a/public/GattServer.h
+++ b/public/GattServer.h
@@ -35,7 +35,7 @@ protected:
         serviceCount(0),
         characteristicCount(0),
         dataSentCallChain(),
-        onDataWritten(),
+        dataWrittenCallChain(),
         onDataRead(),
         onUpdatesEnabled(NULL),
         onUpdatesDisabled(NULL),
@@ -160,10 +160,25 @@ public:
         dataSentCallChain.add(objPtr, memberPtr);
     }
 
-    void setOnDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {onDataWritten.add(callback);}
+    /**
+     * 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 setOnDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
-        onDataWritten.add(objPtr, memberPtr);
+    void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
+        dataWrittenCallChain.add(objPtr, memberPtr);
     }
 
     /**
@@ -196,8 +211,8 @@ public:
 
 protected:
     void handleDataWrittenEvent(const GattWriteCallbackParams *params) {
-        if (onDataWritten.hasCallbacksAttached()) {
-            onDataWritten.call(params);
+        if (dataWrittenCallChain.hasCallbacksAttached()) {
+            dataWrittenCallChain.call(params);
         }
     }
 
@@ -240,12 +255,12 @@ protected:
     uint8_t characteristicCount;
 
 private:
-    CallChainOfFunctionPointersWithContext<unsigned>                                dataSentCallChain;
-    CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> onDataWritten;
+    CallChainOfFunctionPointersWithContext<unsigned>                        dataSentCallChain;
+    CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> dataWrittenCallChain;
     CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>  onDataRead;
-    EventCallback_t                                                                 onUpdatesEnabled;
-    EventCallback_t                                                                 onUpdatesDisabled;
-    EventCallback_t                                                                 onConfirmationReceived;
+    EventCallback_t                                                         onUpdatesEnabled;
+    EventCallback_t                                                         onUpdatesDisabled;
+    EventCallback_t                                                         onConfirmationReceived;
 
 private:
     /* disallow copy and assignment */