Refine BTAdapter API and doc on commands in powerd-off state only: setName() and setSecureConnections()

7 files changed, 60 insertions, 27 deletions

diff --git a/api/direct_bt/BTAdapter.hpp b/api/direct_bt/BTAdapter.hpp
index e860c250..cfe1794a 100644
--- a/api/direct_bt/BTAdapter.hpp
+++ b/api/direct_bt/BTAdapter.hpp
@@ -702,14 +702,18 @@ namespace direct_bt {
 
             /**
              * Sets the name and short-name.
-             * <p>
-             * Shall be performed while powered-off.
-             * </p>
-             * <p>
+             *
              * The corresponding management event will change the name and short-name.
-             * </p>
+             *
+             * Shall be called while adapter is powered off, see setPowered().
+             * If adapter is powered, method returns HCIStatusCode::COMMAND_DISALLOWED.
+             *
+             * @param name
+             * @param short_name
+             * @return HCIStatusCode::SUCCESS or an error state on failure
              * @see getName()
              * @see getShortName()
+             * @see setPowered()
              * @since 2.4.0
              */
             HCIStatusCode setName(const std::string &name, const std::string &short_name) noexcept;
@@ -741,12 +745,16 @@ namespace direct_bt {
              *
              * By default, Secure Connections (SC) is enabled if supported.
              *
+             * Shall be called while adapter is powered off, see setPowered().
+             * If adapter is powered, method returns HCIStatusCode::COMMAND_DISALLOWED.
+             *
              * @param enable
-             * @return true if successful, otherwise false
+             * @return HCIStatusCode::SUCCESS or an error state on failure
              * @see getSecureConnectionsEnabled()
-             * @since 2.4.0
+             * @see setPowered()
+             * @since 2.5.3
              */
-            bool setSecureConnections(const bool enable) noexcept;
+            HCIStatusCode setSecureConnections(const bool enable) noexcept;
 
             /**
              * Sets the given ::BTSecurityLevel and ::SMPIOCapability for connecting device when in server (peripheral) mode, see [adapter's role](@ref BTAdapterRoles).
diff --git a/examples/dbt_peripheral00.cpp b/examples/dbt_peripheral00.cpp
index 8e847d6f..a6a13373 100644
--- a/examples/dbt_peripheral00.cpp
+++ b/examples/dbt_peripheral00.cpp
@@ -584,13 +584,15 @@ static bool initAdapter(std::shared_ptr<BTAdapter>& adapter) {
     fprintf_td(stderr, "initAdapter.1: %s\n", adapter->toString().c_str());
 
     if( adapter->setPowered(false) ) {
-        const HCIStatusCode status = adapter->setName(adapter_name, adapter_short_name);
+        HCIStatusCode status = adapter->setName(adapter_name, adapter_short_name);
         if( HCIStatusCode::SUCCESS == status ) {
             fprintf_td(stderr, "initAdapter: setLocalName OK: %s\n", adapter->toString().c_str());
         } else {
             fprintf_td(stderr, "initAdapter: setLocalName failed: %s\n", adapter->toString().c_str());
         }
-        if( adapter->setSecureConnections( use_SC ) ) {
+
+        status = adapter->setSecureConnections( use_SC );
+        if( HCIStatusCode::SUCCESS == status ) {
             fprintf_td(stderr, "initAdapter: setSecureConnections OK: %s\n", adapter->toString().c_str());
         } else {
             fprintf_td(stderr, "initAdapter: setSecureConnections failed: %s\n", adapter->toString().c_str());
diff --git a/examples/java/DBTPeripheral00.java b/examples/java/DBTPeripheral00.java
index 25b1a1cf..97cb8f12 100644
--- a/examples/java/DBTPeripheral00.java
+++ b/examples/java/DBTPeripheral00.java
@@ -632,13 +632,15 @@ public class DBTPeripheral00 {
         BTUtils.println(System.err, "initAdapter.1: "+adapter.toString());
 
         if( adapter.setPowered(false) ) {
-            final HCIStatusCode status = adapter.setName(adapter_name, adapter_short_name);
+            HCIStatusCode status = adapter.setName(adapter_name, adapter_short_name);
             if( HCIStatusCode.SUCCESS == status ) {
                 BTUtils.fprintf_td(System.err, "initAdapter: setLocalName OK: %s\n", adapter.toString());
             } else {
                 BTUtils.fprintf_td(System.err, "initAdapter: setLocalName failed: %s\n", adapter.toString());
             }
-            if( adapter.setSecureConnections( use_SC ) ) {
+
+            status = adapter.setSecureConnections( use_SC );
+            if( HCIStatusCode.SUCCESS == status ) {
                 BTUtils.fprintf_td(System.err, "initAdapter: setSecureConnections OK: %s\n", adapter.toString());
             } else {
                 BTUtils.fprintf_td(System.err, "initAdapter: setSecureConnections failed: %s\n", adapter.toString());
diff --git a/java/jau/direct_bt/DBTAdapter.java b/java/jau/direct_bt/DBTAdapter.java
index 0d83eaee..e7967fda 100644
--- a/java/jau/direct_bt/DBTAdapter.java
+++ b/java/jau/direct_bt/DBTAdapter.java
@@ -283,7 +283,10 @@ public class DBTAdapter extends DBTObject implements BTAdapter
     public native boolean getSecureConnectionsEnabled();
 
     @Override
-    public native boolean setSecureConnections(final boolean enable);
+    public final HCIStatusCode setSecureConnections(final boolean enable) {
+        return HCIStatusCode.get( setSecureConnectionsImpl(enable) );
+    }
+    private native byte setSecureConnectionsImpl(final boolean enable);
 
     @Override
     public final void setServerConnSecurity(final BTSecurityLevel sec_level, final SMPIOCapability io_cap) {
diff --git a/java/jni/direct_bt/DBTAdapter.cxx b/java/jni/direct_bt/DBTAdapter.cxx
index 8af300fd..6d26e1ec 100644
--- a/java/jni/direct_bt/DBTAdapter.cxx
+++ b/java/jni/direct_bt/DBTAdapter.cxx
@@ -834,15 +834,17 @@ jboolean Java_jau_direct_1bt_DBTAdapter_getSecureConnectionsEnabled(JNIEnv *env,
     return JNI_FALSE;
 }
 
-jboolean Java_jau_direct_1bt_DBTAdapter_setSecureConnections(JNIEnv *env, jobject obj, jboolean enable) {
+jbyte Java_jau_direct_1bt_DBTAdapter_setSecureConnectionsImpl(JNIEnv *env, jobject obj, jboolean enable) {
     try {
         BTAdapter *adapter = jau::getJavaUplinkObject<BTAdapter>(env, obj);
         jau::JavaGlobalObj::check(adapter->getJavaObject(), E_FILE_LINE);
-        return adapter->setSecureConnections(JNI_TRUE == enable ? true : false) ? JNI_TRUE : JNI_FALSE;
+        HCIStatusCode res = adapter->setSecureConnections(JNI_TRUE == enable ? true : false);
+        return (jbyte) number(res);
     } catch(...) {
         rethrow_and_raise_java_exception(env);
     }
-    return JNI_FALSE;
+    return (jbyte) number(HCIStatusCode::INTERNAL_FAILURE);
+}
 }
 
 void Java_jau_direct_1bt_DBTAdapter_setServerConnSecurityImpl(JNIEnv *env, jobject obj, jbyte jsec_level, jbyte jio_cap) {
diff --git a/java/org/direct_bt/BTAdapter.java b/java/org/direct_bt/BTAdapter.java
index 615fdae3..fcbd8165 100644
--- a/java/org/direct_bt/BTAdapter.java
+++ b/java/org/direct_bt/BTAdapter.java
@@ -481,14 +481,18 @@ public interface BTAdapter extends BTObject
 
     /**
      * Sets the name and short-name.
-     * <p>
-     * Shall be performed while powered-off.
-     * </p>
-     * <p>
+     *
      * The corresponding management event will change the name and short-name.
-     * </p>
+     *
+     * Shall be called while adapter is powered off, see {@link #setPowered(boolean)}.
+     * If adapter is powered, method returns {@link HCIStatusCode#COMMAND_DISALLOWED}.
+     *
+     * @param name
+     * @param short_name
+     * @return {@link HCIStatusCode#SUCCESS} if successful, otherwise the {@link HCIStatusCode} error state
      * @see #getName()
      * @see #getShortName()
+     * @see #setPowered(boolean)
      * @since 2.4.0
      */
     HCIStatusCode setName(String name, String short_name);
@@ -570,12 +574,17 @@ public interface BTAdapter extends BTObject
      *
      * By default, Secure Connections (SC) is enabled if supported.
      *
+     * Shall be called while adapter is powered off, see {@link #setPowered(boolean)}.
+     * If adapter is powered, method returns {@link HCIStatusCode#COMMAND_DISALLOWED}.
+     *
      * @param enable
-     * @return true if successful, otherwise false
+     * @return {@link HCIStatusCode#SUCCESS} if successful, otherwise the {@link HCIStatusCode} error state
      * @see #getSecureConnectionsEnabled()
+     * @see #setPowered(boolean)
      * @since 2.4.0
      */
-    boolean setSecureConnections(final boolean enable);
+    HCIStatusCode setSecureConnections(final boolean enable);
+
 
     /**
      * Sets the given ::BTSecurityLevel and ::SMPIOCapability for connecting device when in server (peripheral) mode, see [adapter's role](@ref BTAdapterRoles).
diff --git a/src/direct_bt/BTAdapter.cpp b/src/direct_bt/BTAdapter.cpp
index f857bceb..8a632433 100644
--- a/src/direct_bt/BTAdapter.cpp
+++ b/src/direct_bt/BTAdapter.cpp
@@ -564,6 +564,9 @@ void BTAdapter::printStatusListenerList() noexcept {
 }
 
 HCIStatusCode BTAdapter::setName(const std::string &name, const std::string &short_name) noexcept {
+    if( isAdapterSettingBitSet(adapterInfo.getCurrentSettingMask(), AdapterSetting::POWERED) ) {
+        return HCIStatusCode::COMMAND_DISALLOWED;
+    }
     std::shared_ptr<NameAndShortName> res = mgmt.setLocalName(dev_id, name, short_name);
     return nullptr != res ? HCIStatusCode::SUCCESS : HCIStatusCode::FAILED;
 }
@@ -582,18 +585,22 @@ bool BTAdapter::setPowered(const bool power_on) noexcept {
     return power_on == isAdapterSettingBitSet(new_settings, AdapterSetting::POWERED);
 }
 
-bool BTAdapter::setSecureConnections(const bool enable) noexcept {
+HCIStatusCode BTAdapter::setSecureConnections(const bool enable) noexcept {
     AdapterSetting settings = adapterInfo.getCurrentSettingMask();
+    if( isAdapterSettingBitSet(settings, AdapterSetting::POWERED) ) {
+        return HCIStatusCode::COMMAND_DISALLOWED;
+    }
     if( enable == isAdapterSettingBitSet(settings, AdapterSetting::SECURE_CONN) ) {
         // unchanged
-        return true;
+        return HCIStatusCode::SUCCESS;
     }
     if( !mgmt.setMode(dev_id, MgmtCommand::Opcode::SET_SECURE_CONN, enable ? 1 : 0, settings) ) {
-        return false;
+        return HCIStatusCode::FAILED;
     }
     const AdapterSetting new_settings = adapterInfo.setCurrentSettingMask(settings);
     updateAdapterSettings(false /* off_thread */, new_settings, false /* sendEvent */, 0);
-    return enable == isAdapterSettingBitSet(new_settings, AdapterSetting::SECURE_CONN);
+    return ( enable == isAdapterSettingBitSet(new_settings, AdapterSetting::SECURE_CONN) ) ? HCIStatusCode::SUCCESS : HCIStatusCode::FAILED;
+}
 }
 
 void BTAdapter::setServerConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap) noexcept {