BTDevice::setPairingPasskeyNegative(): Added API doc and missing Java binding. Hint: Better use setPairingPasskey(passkey = 0) ..

.. since current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.

5 files changed, 70 insertions, 1 deletions

diff --git a/api/direct_bt/BTDevice.hpp b/api/direct_bt/BTDevice.hpp
index 9ffb3dfe..6cffb6a8 100644
--- a/api/direct_bt/BTDevice.hpp
+++ b/api/direct_bt/BTDevice.hpp
@@ -685,6 +685,28 @@ namespace direct_bt {
              */
             HCIStatusCode setPairingPasskey(const uint32_t passkey) noexcept;
 
+            /**
+             * Method replies with a negative passkey response, i.e. rejection, see ::PairingMode::PASSKEY_ENTRY_ini.
+             * <p>
+             * You may call this method if the device shall be securely paired with ::PairingMode::PASSKEY_ENTRY_ini,
+             * i.e. when notified via AdapterStatusListener::devicePairingState() in state ::SMPPairingState::PASSKEY_EXPECTED.
+             * </p>
+             * <p>
+             * Current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.
+             *
+             * Hence using setPairingPasskey() with `passkey = 0` is recommended, especially when utilizing
+             * automatic security negotiation via setConnSecurityAuto()!
+             * </p>
+             *
+             * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise ::HCIStatusCode may disclose reason for rejection.
+             * @see PairingMode
+             * @see SMPPairingState
+             * @see AdapterStatusListener::devicePairingState()
+             * @see setPairingPasskey()
+             * @see setPairingNumericComparison()
+             * @see getPairingMode()
+             * @see getPairingState()
+             */
             HCIStatusCode setPairingPasskeyNegative() noexcept;
 
             /**
diff --git a/java/jau/direct_bt/DBTDevice.java b/java/jau/direct_bt/DBTDevice.java
index 1b464a27..c69e5ca9 100644
--- a/java/jau/direct_bt/DBTDevice.java
+++ b/java/jau/direct_bt/DBTDevice.java
@@ -424,6 +424,12 @@ public class DBTDevice extends DBTObject implements BTDevice
     private native byte setPairingPasskeyImpl(final int passkey) throws BTException;
 
     @Override
+    public HCIStatusCode setPairingPasskeyNegative() {
+        return HCIStatusCode.get( setPairingPasskeyNegativeImpl() );
+    }
+    private native byte setPairingPasskeyNegativeImpl() throws BTException;
+
+    @Override
     public HCIStatusCode setPairingNumericComparison(final boolean equal) {
         return HCIStatusCode.get( setPairingNumericComparisonImpl(equal) );
     }
diff --git a/java/jni/direct_bt/DBTDevice.cxx b/java/jni/direct_bt/DBTDevice.cxx
index 6d0305a2..a5ec55a2 100644
--- a/java/jni/direct_bt/DBTDevice.cxx
+++ b/java/jni/direct_bt/DBTDevice.cxx
@@ -593,7 +593,6 @@ jbyte Java_jau_direct_1bt_DBTDevice_setPairingPasskeyImpl(JNIEnv *env, jobject o
         BTDevice *device = getJavaUplinkObject<BTDevice>(env, obj);
         JavaGlobalObj::check(device->getJavaObject(), E_FILE_LINE);
 
-        // const std::string passkey = nullptr != jpasskey ? from_jstring_to_string(env, jpasskey) : std::string();
         return number( device->setPairingPasskey( static_cast<uint32_t>(jpasskey) ) );
     } catch(...) {
         rethrow_and_raise_java_exception(env);
@@ -601,6 +600,18 @@ jbyte Java_jau_direct_1bt_DBTDevice_setPairingPasskeyImpl(JNIEnv *env, jobject o
     return static_cast<uint8_t>( HCIStatusCode::INTERNAL_FAILURE );
 }
 
+jbyte Java_jau_direct_1bt_DBTDevice_setPairingPasskeyNegativeImpl(JNIEnv *env, jobject obj) {
+    try {
+        BTDevice *device = getJavaUplinkObject<BTDevice>(env, obj);
+        JavaGlobalObj::check(device->getJavaObject(), E_FILE_LINE);
+
+        return number( device->setPairingPasskeyNegative() );
+    } catch(...) {
+        rethrow_and_raise_java_exception(env);
+    }
+    return static_cast<uint8_t>( HCIStatusCode::INTERNAL_FAILURE );
+}
+
 jbyte Java_jau_direct_1bt_DBTDevice_setPairingNumericComparisonImpl(JNIEnv *env, jobject obj, jboolean jequal) {
     try {
         BTDevice *device = getJavaUplinkObject<BTDevice>(env, obj);
diff --git a/java/org/direct_bt/BTDevice.java b/java/org/direct_bt/BTDevice.java
index 0b8eaf4e..bb1bd9c9 100644
--- a/java/org/direct_bt/BTDevice.java
+++ b/java/org/direct_bt/BTDevice.java
@@ -458,6 +458,33 @@ public interface BTDevice extends BTObject
     HCIStatusCode setPairingPasskey(final int passkey);
 
     /**
+     * Method replies with a negative passkey response, i.e. rejection, see {@link PairingMode#PASSKEY_ENTRY_ini}.
+     * <p>
+     * You may call this method if the device shall be securely paired with {@link PairingMode#PASSKEY_ENTRY_ini},
+     * i.e. when notified via {@link AdapterStatusListener#devicePairingState(BTDevice, SMPPairingState, PairingMode, long) devicePairingState}
+     * in state {@link SMPPairingState#PASSKEY_EXPECTED}.
+     * </p>
+     * <p>
+     * Current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.
+     *
+     * Hence using {@link #setPairingPasskey(int)} with {@code passkey = 0} is recommended, especially when utilizing
+     * automatic security negotiation via {@link #setConnSecurityAuto()}!
+     * </p>
+     *
+     * @return {@link HCIStatusCode#SUCCESS} if the command has been accepted, otherwise {@link HCIStatusCode} may disclose reason for rejection.
+     * @see PairingMode
+     * @see SMPPairingState
+     * @see AdapterStatusListener#devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
+     * @see #setPairingPasskey(int)
+     * @see #setPairingNumericComparison(boolean)
+     * @see #getPairingMode()
+     * @see #getPairingState()
+     * @since 2.1.0
+     * @implNote not implemented in {@code tinyb.dbus}
+     */
+    HCIStatusCode setPairingPasskeyNegative();
+
+    /**
      * Method sets the numeric comparison result, see {@link PairingMode#NUMERIC_COMPARE_ini}.
      * <p>
      * Call this method if the device shall be securely paired with {@link PairingMode#NUMERIC_COMPARE_ini},
diff --git a/java/tinyb/dbus/DBusDevice.java b/java/tinyb/dbus/DBusDevice.java
index 7fd552a6..b431e4c1 100644
--- a/java/tinyb/dbus/DBusDevice.java
+++ b/java/tinyb/dbus/DBusDevice.java
@@ -156,6 +156,9 @@ public class DBusDevice extends DBusObject implements BTDevice
     public HCIStatusCode setPairingPasskey(final int passkey) { return HCIStatusCode.INTERNAL_FAILURE; }
 
     @Override
+    public HCIStatusCode setPairingPasskeyNegative() { return HCIStatusCode.INTERNAL_FAILURE; }
+
+    @Override
     public HCIStatusCode setPairingNumericComparison(final boolean equal) { return HCIStatusCode.INTERNAL_FAILURE; }
 
     @Override