[DBT]Adapter (Java/C++) startDiscovery(bool keepAlive) policy change: keepAlive default := true

Using startDiscovery(keepAlive=true) and stopDiscovery()
is the recommended workflow for a reliable discovery process.

Without keepAlive=true, we already experienced a too short discovery cycle
where the subsequent manual startDiscovery restart will purge
the already discovered devices via removeDiscoveredDevices().

Hence keepAlive=true is strongly indicated for increased reliability
especially when _not_ using the AdapterStatusListener,
since adapter.getDevices() may simply come too late.

6 files changed, 44 insertions, 9 deletions

diff --git a/api/direct_bt/DBTAdapter.hpp b/api/direct_bt/DBTAdapter.hpp
index 3dc1f003..48585a81 100644
--- a/api/direct_bt/DBTAdapter.hpp
+++ b/api/direct_bt/DBTAdapter.hpp
@@ -382,10 +382,14 @@ namespace direct_bt {
              * <p>
              * if {@code keepAlive} is {@code  true}, discovery state will be re-enabled
              * in case the underlying Bluetooth implementation (BlueZ, ..) disabled it.
-             * Default is {@code false}.
+             * Default is {@code true}.
              * </p>
              * <p>
-             * Default parameter values are chosen for using public address resolution
+             * Using startDiscovery(keepAlive=true) and stopDiscovery()
+             * is the recommended workflow for a reliable discovery process.
+             * </p>
+             * <p>
+             * Remaining default parameter values are chosen for using public address resolution
              * and usual discovery intervals etc.
              * </p>
              * <p>
@@ -394,9 +398,14 @@ namespace direct_bt {
              * <p>
              * Also clears previous discovered devices via removeDiscoveredDevices().
              * </p>
+             * @param keepAlive
+             * @param own_mac_type
+             * @param le_scan_interval in units of 0.625ms, default value 48 for 30ms, min value 4 for 2.5ms -> 0x4000 for 10.24s
+             * @param le_scan_window in units of 0.625ms, default value 48 for 30ms,  min value 4 for 2.5ms -> 0x4000 for 10.24s. Shall be <= le_scan_interval
+             * @return
              */
-            bool startDiscovery(bool keepAlive=false, HCIAddressType own_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
-                                uint16_t interval=0x0004, uint16_t window=0x0004);
+            bool startDiscovery(const bool keepAlive=true, const HCIAddressType own_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
+                                const uint16_t le_scan_interval=48, const uint16_t le_scan_window=48);
 
             /**
              * Closes the discovery session.
diff --git a/java/direct_bt/tinyb/DBTManager.java b/java/direct_bt/tinyb/DBTManager.java
index c9c6ef9c..c74f0706 100644
--- a/java/direct_bt/tinyb/DBTManager.java
+++ b/java/direct_bt/tinyb/DBTManager.java
@@ -255,7 +255,10 @@ public class DBTManager implements BluetoothManager
     public BluetoothAdapter getDefaultAdapter() { return adapters.get(defaultAdapterIndex); }
 
     @Override
-    public boolean startDiscovery() throws BluetoothException { return getDefaultAdapter().startDiscovery(); }
+    public boolean startDiscovery() throws BluetoothException { return startDiscovery(true); }
+
+    @Override
+    public boolean startDiscovery(final boolean keepAlive) throws BluetoothException { return getDefaultAdapter().startDiscovery(keepAlive); }
 
     @Override
     public boolean stopDiscovery() throws BluetoothException { return getDefaultAdapter().stopDiscovery(); }
diff --git a/java/org/tinyb/BluetoothAdapter.java b/java/org/tinyb/BluetoothAdapter.java
index 1261f28d..e17878f7 100644
--- a/java/org/tinyb/BluetoothAdapter.java
+++ b/java/org/tinyb/BluetoothAdapter.java
@@ -142,6 +142,9 @@ public interface BluetoothAdapter extends BluetoothObject
      * Turns on device discovery if it is disabled.
      * @param keepAlive if {@code true}, indicates that discovery shall be restarted
      *        if stopped by the underlying Bluetooth implementation (BlueZ, ..).
+     *        Using {@link #startDiscovery(boolean) startDiscovery}({@code keepAlive=true})
+     *        and {@link #stopDiscovery()} is the recommended workflow
+     *        for a reliable discovery process.
      * @return TRUE if discovery was successfully enabled
      * @throws BluetoothException
      * @since 2.0.0
diff --git a/java/org/tinyb/BluetoothManager.java b/java/org/tinyb/BluetoothManager.java
index b7bec3cb..4e772a7b 100644
--- a/java/org/tinyb/BluetoothManager.java
+++ b/java/org/tinyb/BluetoothManager.java
@@ -169,9 +169,24 @@ public interface BluetoothManager
 
     /** Turns on device discovery on the default adapter if it is disabled.
       * @return TRUE if discovery was successfully enabled
+      * @deprecated since 2.0.0, use {@link #startDiscovery(boolean)}.
       */
     public boolean startDiscovery() throws BluetoothException;
 
+    /**
+     * Turns on device discovery on the default adapter if it is disabled.
+     * @param keepAlive if {@code true}, indicates that discovery shall be restarted
+     *        if stopped by the underlying Bluetooth implementation (BlueZ, ..).
+     *        Using {@link #startDiscovery(boolean) startDiscovery}({@code keepAlive=true})
+     *        and {@link #stopDiscovery()} is the recommended workflow
+     *        for a reliable discovery process.
+     * @return TRUE if discovery was successfully enabled
+     * @throws BluetoothException
+     * @since 2.0.0
+     */
+    public boolean startDiscovery(final boolean keepAlive) throws BluetoothException;
+
+
     /** Turns off device discovery on the default adapter if it is enabled.
       * @return TRUE if discovery was successfully disabled
       */
diff --git a/java/tinyb/dbus/DBusManager.java b/java/tinyb/dbus/DBusManager.java
index bfcd5e4b..ffb8a935 100644
--- a/java/tinyb/dbus/DBusManager.java
+++ b/java/tinyb/dbus/DBusManager.java
@@ -104,6 +104,11 @@ public class DBusManager implements BluetoothManager
     public native boolean startDiscovery() throws BluetoothException;
 
     @Override
+    public boolean startDiscovery(final boolean keepAlive) throws BluetoothException {
+        return startDiscovery(); // FIXME keepAlive
+    }
+
+    @Override
     public native boolean stopDiscovery() throws BluetoothException;
 
     @Override
diff --git a/src/direct_bt/DBTAdapter.cpp b/src/direct_bt/DBTAdapter.cpp
index 9d3bbd42..293937d8 100644
--- a/src/direct_bt/DBTAdapter.cpp
+++ b/src/direct_bt/DBTAdapter.cpp
@@ -299,12 +299,12 @@ int DBTAdapter::removeAllStatusListener() {
     return count;
 }
 
-bool DBTAdapter::startDiscovery(bool keepAlive, HCIAddressType own_mac_type,
-                                uint16_t interval, uint16_t window)
+bool DBTAdapter::startDiscovery(const bool keepAlive, const HCIAddressType own_mac_type,
+                                const uint16_t le_scan_interval, const uint16_t le_scan_window)
 {
     (void)own_mac_type;
-    (void)interval;
-    (void)window;
+    (void)le_scan_interval;
+    (void)le_scan_window;
 
     DBG_PRINT("DBTAdapter::startDiscovery: keepAlive %d ...", keepAlive);
     removeDiscoveredDevices();