C++/Java *Device::connect*(..), disconnect(): Return HCIStatusCode instead of just boolean, passing through potential HCI error detail

The HCIStatusCode on failed connect*/disconnect commands issued via direct_bt HCI,
could help applications making a better fail-recovery decision than just having the binary result.

5 files changed, 130 insertions, 64 deletions

diff --git a/java/direct_bt/tinyb/DBTDevice.java b/java/direct_bt/tinyb/DBTDevice.java
index 65301141..601a30a7 100644
--- a/java/direct_bt/tinyb/DBTDevice.java
+++ b/java/direct_bt/tinyb/DBTDevice.java
@@ -356,36 +356,36 @@ public class DBTDevice extends DBTObject implements BluetoothDevice
     public final boolean getConnected() { return isConnected.get(); }
 
     @Override
-    public final boolean disconnect() throws BluetoothException {
+    public final HCIStatusCode disconnect() throws BluetoothException {
         if( isConnected.get() ) {
-            return disconnectImpl(); // event callbacks will be generated by implementation
+            return HCIStatusCode.get( disconnectImpl() ); // event callbacks will be generated by implementation
         }
-        return false;
+        return HCIStatusCode.CONNECTION_TERMINATED_BY_LOCAL_HOST;
     }
-    private native boolean disconnectImpl() throws BluetoothException;
+    private native byte disconnectImpl() throws BluetoothException;
 
     @Override
-    public final boolean connect() throws BluetoothException {
+    public final HCIStatusCode connect() throws BluetoothException {
         if( !isConnected.get() ) {
-            return connectImpl(); // event callbacks will be generated by implementation
+            return HCIStatusCode.get( connectImpl() ); // event callbacks will be generated by implementation
         }
-        return false;
+        return HCIStatusCode.CONNECTION_ALREADY_EXISTS;
     }
-    private native boolean connectImpl() throws BluetoothException;
+    private native byte connectImpl() throws BluetoothException;
 
     @Override
-    public boolean connect(final short le_scan_interval, final short le_scan_window,
-                           final short conn_interval_min, final short conn_interval_max,
-                           final short conn_latency, final short timeout) {
+    public HCIStatusCode connect(final short le_scan_interval, final short le_scan_window,
+                                 final short conn_interval_min, final short conn_interval_max,
+                                 final short conn_latency, final short timeout) {
         if( !isConnected.get() ) {
             // event callbacks will be generated by implementation
-            return connectImpl(le_scan_interval, le_scan_window, conn_interval_min, conn_interval_max, conn_latency, timeout);
+            return HCIStatusCode.get( connectImpl(le_scan_interval, le_scan_window, conn_interval_min, conn_interval_max, conn_latency, timeout) );
         }
-        return false;
+        return HCIStatusCode.CONNECTION_ALREADY_EXISTS;
     }
-    private native boolean connectImpl(final short le_scan_interval, final short le_scan_window,
-                                       final short conn_interval_min, final short conn_interval_max,
-                                       final short conn_latency, final short timeout);
+    private native byte connectImpl(final short le_scan_interval, final short le_scan_window,
+                                    final short conn_interval_min, final short conn_interval_max,
+                                    final short conn_latency, final short timeout);
 
     /* DBT Java callbacks */
 
diff --git a/java/jni/direct_bt/DBTDevice.cxx b/java/jni/direct_bt/DBTDevice.cxx
index d28ac0c2..e426d2ce 100644
--- a/java/jni/direct_bt/DBTDevice.cxx
+++ b/java/jni/direct_bt/DBTDevice.cxx
@@ -295,16 +295,16 @@ void Java_direct_1bt_tinyb_DBTDevice_deleteImpl(JNIEnv *env, jobject obj, jlong
     }
 }
 
-jboolean Java_direct_1bt_tinyb_DBTDevice_disconnectImpl(JNIEnv *env, jobject obj)
+jbyte Java_direct_1bt_tinyb_DBTDevice_disconnectImpl(JNIEnv *env, jobject obj)
 {
     try {
         DBTDevice *device = getDBTObject<DBTDevice>(env, obj);
         JavaGlobalObj::check(device->getJavaObject(), E_FILE_LINE);
-        return device->disconnect() ? JNI_TRUE : JNI_FALSE;
+        return (jint) number( device->disconnect() );
     } catch(...) {
         rethrow_and_raise_java_exception(env);
     }
-    return JNI_FALSE;
+    return (jbyte) number(HCIStatusCode::INTERNAL_FAILURE);
 }
 
 jboolean Java_direct_1bt_tinyb_DBTDevice_removeImpl(JNIEnv *env, jobject obj)
@@ -319,28 +319,27 @@ jboolean Java_direct_1bt_tinyb_DBTDevice_removeImpl(JNIEnv *env, jobject obj)
     return JNI_TRUE;
 }
 
-jboolean Java_direct_1bt_tinyb_DBTDevice_connectImpl__(JNIEnv *env, jobject obj)
+jbyte Java_direct_1bt_tinyb_DBTDevice_connectImpl__(JNIEnv *env, jobject obj)
 {
     try {
         DBTDevice *device = getDBTObject<DBTDevice>(env, obj);
         JavaGlobalObj::check(device->getJavaObject(), E_FILE_LINE);
-        bool res = device->connectDefault();
-        return res ? JNI_TRUE : JNI_FALSE;
+        return (jbyte) number( device->connectDefault() );
     } catch(...) {
         rethrow_and_raise_java_exception(env);
     }
-    return JNI_FALSE;
+    return (jbyte) number(HCIStatusCode::INTERNAL_FAILURE);
 }
 
-jboolean Java_direct_1bt_tinyb_DBTDevice_connectImpl__SSSSSS(JNIEnv *env, jobject obj,
-                                                             jshort interval, jshort window,
-                                                             jshort min_interval, jshort max_interval,
-                                                             jshort latency, jshort timeout)
+jbyte Java_direct_1bt_tinyb_DBTDevice_connectImpl__SSSSSS(JNIEnv *env, jobject obj,
+                                                          jshort interval, jshort window,
+                                                          jshort min_interval, jshort max_interval,
+                                                          jshort latency, jshort timeout)
 {
     try {
         DBTDevice *device = getDBTObject<DBTDevice>(env, obj);
         JavaGlobalObj::check(device->getJavaObject(), E_FILE_LINE);
-        bool res;
+        HCIStatusCode res;
         switch( device->addressType ) {
             case BDAddressType::BDADDR_LE_PUBLIC:
                 /* fall through intended */
@@ -351,11 +350,11 @@ jboolean Java_direct_1bt_tinyb_DBTDevice_connectImpl__SSSSSS(JNIEnv *env, jobjec
                 res = device->connectDefault();
                 break;
         }
-        return res ? JNI_TRUE : JNI_FALSE;
+        return (jbyte) number(res);
     } catch(...) {
         rethrow_and_raise_java_exception(env);
     }
-    return JNI_FALSE;
+    return (jbyte) number(HCIStatusCode::INTERNAL_FAILURE);
 }
 
 //
diff --git a/java/jni/tinyb/DBusDevice.cxx b/java/jni/tinyb/DBusDevice.cxx
index 5eb8581b..f810ef9d 100644
--- a/java/jni/tinyb/DBusDevice.cxx
+++ b/java/jni/tinyb/DBusDevice.cxx
@@ -72,7 +72,7 @@ jobject Java_tinyb_dbus_DBusDevice_clone(JNIEnv *env, jobject obj)
     return nullptr;
 }
 
-jboolean Java_tinyb_dbus_DBusDevice_disconnect(JNIEnv *env, jobject obj)
+jboolean Java_tinyb_dbus_DBusDevice_disconnectImpl(JNIEnv *env, jobject obj)
 {
     try {
         BluetoothDevice *obj_device = getInstance<BluetoothDevice>(env, obj);
@@ -131,7 +131,7 @@ jboolean Java_tinyb_dbus_DBusDevice_connectAsyncFinish(JNIEnv *env, jobject obj)
     return JNI_FALSE;
 }
 
-jboolean Java_tinyb_dbus_DBusDevice_connect(JNIEnv *env, jobject obj)
+jboolean Java_tinyb_dbus_DBusDevice_connectImpl(JNIEnv *env, jobject obj)
 {
     try {
         BluetoothDevice *obj_device = getInstance<BluetoothDevice>(env, obj);
diff --git a/java/org/tinyb/BluetoothDevice.java b/java/org/tinyb/BluetoothDevice.java
index fe84cce8..2794bde2 100644
--- a/java/org/tinyb/BluetoothDevice.java
+++ b/java/org/tinyb/BluetoothDevice.java
@@ -64,25 +64,83 @@ public interface BluetoothDevice extends BluetoothObject
       */
     BluetoothGattService find(String UUID);
 
-    /* D-Bus method calls: */
-    /** The connection to this device is removed, removing all connected
-      * profiles.
-      * @return TRUE if the device disconnected
-      */
-    boolean disconnect() throws BluetoothException;
+    /* Bluetooth method calls: */
 
-    /** A connection to this device is established, connecting each profile
-      * flagged as auto-connectable.
-      * @return TRUE if the device connected
-      * @see #connect(short, short, short, short, short, short)
-      */
-    boolean connect() throws BluetoothException;
+    /**
+     * <b>direct_bt.tinyb</b>: Disconnect the LE or BREDR peer's GATT and HCI connection.
+     * <p>
+     * BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.6 Disconnect command
+     * </p>
+     * <p>
+     * The actual disconnect event will be delivered asynchronous and
+     * the connection event can be caught via AdapterStatusListener::deviceDisconnected(..).
+     * If unacceptable, {@link HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM} is being returned.
+     * </p>
+     * <p>
+     * The device will be removed from the managing adapter's connected devices
+     * when {@link AdapterStatusListener#deviceDisconnected(BluetoothDevice, HCIStatusCode, long)} has been received.
+     * </p>
+     * <p>
+     * Any open GATT connection will be closed as well.
+     * </p>
+     * <p>
+     * <b>tinyb.dbus</b> The connection to this device is removed, removing all connected
+     * profiles.
+     * </p>
+     * @return {@link HCIStatusCode#SUCCESS} if the command has been accepted, otherwise {@link HCIStatusCode} may disclose reason for rejection.
+     * @since 2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of <i>direct_bt</i>
+     */
+    HCIStatusCode disconnect() throws BluetoothException;
+
+    /**
+     * <b>direct_bt.tinyb</b>: Establish a default HCI connection to this device, using certain default parameter.
+     * <p>
+     * BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command <br>
+     * BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.5 Create Connection command
+     * </p>
+     * <p>
+     * Depending on this device's addressType,
+     * either a BREDR (BDADDR_BREDR) or LE (BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM) connection is attempted.<br>
+     * If unacceptable, {@link HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM} is being returned.
+     * </p>
+     * <p>
+     * The actual new connection handle will be delivered asynchronous and
+     * the connection event can be caught via {@link AdapterStatusListener#deviceConnected(BluetoothDevice, long)},
+     * or if failed via {@link AdapterStatusListener#deviceDisconnected(BluetoothDevice, HCIStatusCode, long)}.
+     * </p>
+     * <p>
+     * The device is tracked by the managing adapter.
+     * </p>
+     * <p>
+     * <b>tinyb.dbus</b>: A connection to this device is established, connecting each profile
+     * flagged as auto-connectable.
+     * </p>
+     * @return {@link HCIStatusCode#SUCCESS} if the command has been accepted, otherwise {@link HCIStatusCode} may disclose reason for rejection.
+     * @see #connect(short, short, short, short, short, short)
+     * @since 2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of <i>direct_bt</i>
+     */
+    HCIStatusCode connect() throws BluetoothException;
 
     /**
-     * A connection to this device is established, see {@link #connect()}.
+     * Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device.
      * <p>
-     * The given LE connection parameter will be used instead of the Bluetooth implementation defaults,
-     * if this device is of type {@link BluetoothAddressType#BDADDR_LE_PUBLIC} or {@link BluetoothAddressType#BDADDR_LE_RANDOM}.
+     * BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command
+     * </p>
+     * <p>
+     * If this device's {@link #getAddressType()} is not BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM,
+     * {@link HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM} is being returned.
+     * </p>
+     * <p>
+     * The actual new connection handle will be delivered asynchronous and
+     * the connection event can be caught via {@link AdapterStatusListener#deviceConnected(BluetoothDevice, long)},
+     * or if failed via {@link AdapterStatusListener#deviceDisconnected(BluetoothDevice, HCIStatusCode, long)}.
+     * </p>
+     * <p>
+     * The device is tracked by the managing adapter.
+     * </p>
+     * <p>
+     * Default parameter values are chosen for using public address resolution
+     * and usual connection latency, interval etc.
      * </p>
      * <p>
      * Set window to the same value as the interval, enables continuous scanning.
@@ -93,15 +151,16 @@ public interface BluetoothDevice extends BluetoothObject
      * @param conn_interval_min in units of 1.25ms, default value 15 for 19.75ms
      * @param conn_interval_max in units of 1.25ms, default value 15 for 19.75ms
      * @param conn_latency slave latency in units of connection events, default value 0
-     * @param timeout in units of 10ms, default value 1000 for 10000ms or 10s.
-     * @return {@code true} if successful, otherwise {@code false}.
+     * @param supervision_timeout in units of 10ms, default value 1000 for 10000ms or 10s.
+     * @return {@link HCIStatusCode#SUCCESS} if the command has been accepted, otherwise {@link HCIStatusCode} may disclose reason for rejection.
      *
      * @see #connect()
-     * @since 2.0.0
+     * @since 2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of <i>direct_bt</i>
+     * @implNote not implemented in <b>tinyb.dbus</b>
      */
-    public boolean connect(final short le_scan_interval, final short le_scan_window,
-                           final short conn_interval_min, final short conn_interval_max,
-                           final short conn_latency, final short timeout);
+    HCIStatusCode connect(final short le_scan_interval, final short le_scan_window,
+                          final short conn_interval_min, final short conn_interval_max,
+                          final short conn_latency, final short timeout);
 
 
     /** Connects a specific profile available on the device, given by UUID
@@ -193,7 +252,7 @@ public interface BluetoothDevice extends BluetoothObject
      * determining whether the device is {@link BluetoothAddressType#BDADDR_BREDR}
      * or an LE device, {@link BluetoothAddressType#BDADDR_LE_PUBLIC} or {@link BluetoothAddressType#BDADDR_LE_RANDOM}.
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus, returns {@link BluetoothAddressType#BDADDR_LE_PUBLIC}
+     * @implNote not implemented in <b>tinyb.dbus</b>, returns {@link BluetoothAddressType#BDADDR_LE_PUBLIC}
      */
     BluetoothAddressType getAddressType();
 
@@ -208,7 +267,7 @@ public interface BluetoothDevice extends BluetoothObject
      * method shall return {@link BLERandomAddressType#UNDEFINED}.
      * </p>
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus, returns {@link BLERandomAddressType#UNDEFINED}
+     * @implNote not implemented in <b>tinyb.dbus</b>, returns {@link BLERandomAddressType#UNDEFINED}
      */
     BLERandomAddressType getBLERandomAddressType();
 
@@ -454,7 +513,7 @@ public interface BluetoothDevice extends BluetoothObject
      * @see BluetoothGattCharacteristic#configNotificationIndication(boolean, boolean, boolean[])
      * @see BluetoothGattCharacteristic#enableNotificationOrIndication(boolean[])
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus
+     * @implNote not implemented in <b>tinyb.dbus</b>
      */
     public boolean addCharacteristicListener(final GATTCharacteristicListener listener)
         throws IllegalStateException;
@@ -467,7 +526,7 @@ public interface BluetoothDevice extends BluetoothObject
      * @param listener A {@link GATTCharacteristicListener} instance
      * @return true if the given listener is an element of the list and has been removed, otherwise false.
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus
+     * @implNote not implemented in <b>tinyb.dbus</b>
      */
     public boolean removeCharacteristicListener(final GATTCharacteristicListener l);
 
@@ -480,7 +539,7 @@ public interface BluetoothDevice extends BluetoothObject
      * @param associatedCharacteristic the match criteria to remove any GATTCharacteristicListener from the list
      * @return number of removed listener.
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus
+     * @implNote not implemented in <b>tinyb.dbus</b>
      */
     public int removeAllAssociatedCharacteristicListener(final BluetoothGattCharacteristic associatedCharacteristic);
 
@@ -488,7 +547,7 @@ public interface BluetoothDevice extends BluetoothObject
      * Remove all {@link GATTCharacteristicListener} from the list.
      * @return number of removed listener.
      * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus
+     * @implNote not implemented in <b>tinyb.dbus</b>
      */
     public int removeAllCharacteristicListener();
 }
diff --git a/java/tinyb/dbus/DBusDevice.java b/java/tinyb/dbus/DBusDevice.java
index 5bbb8f7d..225b01d0 100644
--- a/java/tinyb/dbus/DBusDevice.java
+++ b/java/tinyb/dbus/DBusDevice.java
@@ -42,6 +42,7 @@ import org.tinyb.BluetoothNotification;
 import org.tinyb.BluetoothType;
 import org.tinyb.BluetoothUtils;
 import org.tinyb.GATTCharacteristicListener;
+import org.tinyb.HCIStatusCode;
 
 public class DBusDevice extends DBusObject implements BluetoothDevice
 {
@@ -76,15 +77,22 @@ public class DBusDevice extends DBusObject implements BluetoothDevice
     /* D-Bus method calls: */
 
     @Override
-    public native boolean disconnect() throws BluetoothException;
+    public final HCIStatusCode disconnect() throws BluetoothException {
+        return disconnectImpl() ? HCIStatusCode.SUCCESS : HCIStatusCode.UNSPECIFIED_ERROR ;
+    }
+    private native boolean disconnectImpl() throws BluetoothException;
+
 
     @Override
-    public native boolean connect() throws BluetoothException;
+    public final HCIStatusCode connect() throws BluetoothException {
+        return connectImpl() ? HCIStatusCode.SUCCESS : HCIStatusCode.UNSPECIFIED_ERROR ;
+    }
+    private native boolean connectImpl() throws BluetoothException;
 
     @Override
-    public boolean connect(final short interval, final short window,
-                           final short min_interval, final short max_interval,
-                           final short latency, final short timeout) {
+    public HCIStatusCode connect(final short interval, final short window,
+                                 final short min_interval, final short max_interval,
+                                 final short latency, final short timeout) {
         return connect(); // FIXME connection params ...
     }