From 9183583ffaca41919ab48280c2a90405738390c0 Mon Sep 17 00:00:00 2001
From: Rohit Grover <rohit.grover@arm.com>
Date: Fri, 19 Jun 2015 10:21:08 +0100
Subject: [PATCH] disconnect() should take a connection handle.

---
 public/BLE.h | 18 ++++++++++++++++++
 public/Gap.h | 19 ++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/public/BLE.h b/public/BLE.h
index 05935e7..6eba551 100644
--- a/public/BLE.h
+++ b/public/BLE.h
@@ -656,6 +656,19 @@ public:
         return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
     }
 
+    /**
+     * This call initiates the disconnection procedure, and its completion will
+     * be communicated to the application with an invocation of the
+     * onDisconnection callback.
+     *
+     * @param[in] connectionHandle
+     * @param[in] reason
+     *              The reason for disconnection to be sent back to the peer.
+     */
+    ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) {
+        return gap().disconnect(connectionHandle, reason);
+    }
+
     /**
      * This call initiates the disconnection procedure, and its completion will
      * be communicated to the application with an invocation of the
@@ -668,6 +681,11 @@ public:
      * You should use the parallel API from Gap directly. A former call to
      * ble.disconnect(reason) should be replaced with
      * ble.gap().disconnect(reason).
+     *
+     * @note: this version of disconnect() doesn't take a connection handle. It
+     * will work reliably only for stacks which are limited to a single
+     * connection. This API should be considered *deprecated* in favour of the
+     * alternative which takes a connection handle. It will be dropped in the future.
      */
     ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
         return gap().disconnect(reason);
diff --git a/public/Gap.h b/public/Gap.h
index 9d053b9..e18fa75 100644
--- a/public/Gap.h
+++ b/public/Gap.h
@@ -74,7 +74,7 @@ public:
         unsigned connected   : 1; /**< peripheral is connected to a central */
     };
 
-    typedef uint16_t Handle_t;
+    typedef uint16_t Handle_t; /* Type for connection handle. */
 
     typedef struct {
         uint16_t minConnectionInterval;      /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
@@ -230,6 +230,23 @@ public:
      * @param  reason
      *           The reason for disconnection to be sent back to the peer.
      */
+    virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
+        return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
+    }
+
+    /**
+     * This call initiates the disconnection procedure, and its completion will
+     * be communicated to the application with an invocation of the
+     * disconnectionCallback.
+     *
+     * @param  reason
+     *           The reason for disconnection to be sent back to the peer.
+     *
+     * @note: this version of disconnect() doesn't take a connection handle. It
+     * will work reliably only for stacks which are limited to a single
+     * connection. This API should be considered *deprecated* in favour of the
+     * altertive which takes a connection handle. It will be dropped in the future.
+     */
     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
         return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
     }