Introduce BTRole: Bluetooth device roles from the perspective of the link layer (connection initiator): Initially for BTAdapter

5 files changed, 133 insertions, 8 deletions

diff --git a/java/jau/direct_bt/DBTAdapter.java b/java/jau/direct_bt/DBTAdapter.java
index 440b4f8e..edf97e24 100644
--- a/java/jau/direct_bt/DBTAdapter.java
+++ b/java/jau/direct_bt/DBTAdapter.java
@@ -46,6 +46,7 @@ import org.direct_bt.BTGattService;
 import org.direct_bt.BTManager;
 import org.direct_bt.BTMode;
 import org.direct_bt.BTObject;
+import org.direct_bt.BTRole;
 import org.direct_bt.BTType;
 import org.direct_bt.BTUtils;
 import org.direct_bt.EIRDataTypeSet;
@@ -104,6 +105,18 @@ public class DBTAdapter extends DBTObject implements BTAdapter
     public final BTManager getManager() { return DBTManager.getManager(); }
 
     @Override
+    public final BTRole getRole() {
+        return BTRole.get(getRoleImpl());
+    }
+    private native byte getRoleImpl();
+
+    @Override
+    public final BTMode getBTMode() {
+        return BTMode.get(getBTModeImpl());
+    }
+    private native byte getBTModeImpl();
+
+    @Override
     public void close() {
         final DBTManager mngr = (DBTManager)DBTManager.getManager();
         if( !isValid() ) {
diff --git a/java/jni/direct_bt/DBTAdapter.cxx b/java/jni/direct_bt/DBTAdapter.cxx
index 8f4ad701..b5bd1083 100644
--- a/java/jni/direct_bt/DBTAdapter.cxx
+++ b/java/jni/direct_bt/DBTAdapter.cxx
@@ -789,6 +789,28 @@ jbyte Java_jau_direct_1bt_DBTAdapter_stopDiscoveryImpl(JNIEnv *env, jobject obj)
     return (jbyte) number(HCIStatusCode::INTERNAL_FAILURE);
 }
 
+jbyte Java_jau_direct_1bt_DBTAdapter_getRoleImpl(JNIEnv *env, jobject obj)
+{
+    try {
+        BTAdapter *adapter = jau::getJavaUplinkObject<BTAdapter>(env, obj);
+        return (jbyte) number( adapter->getRole() );
+    } catch(...) {
+        rethrow_and_raise_java_exception(env);
+    }
+    return (jbyte) number( BTRole::None );
+}
+
+jbyte Java_jau_direct_1bt_DBTAdapter_getBTModeImpl(JNIEnv *env, jobject obj)
+{
+    try {
+        BTAdapter *adapter = jau::getJavaUplinkObject<BTAdapter>(env, obj);
+        return (jbyte) number( adapter->getBTMode() );
+    } catch(...) {
+        rethrow_and_raise_java_exception(env);
+    }
+    return (jbyte) number( BTMode::NONE );
+}
+
 jobject Java_jau_direct_1bt_DBTAdapter_getDiscoveredDevicesImpl(JNIEnv *env, jobject obj)
 {
     try {
diff --git a/java/org/direct_bt/BTAdapter.java b/java/org/direct_bt/BTAdapter.java
index 442d9f4e..6e4e5875 100644
--- a/java/org/direct_bt/BTAdapter.java
+++ b/java/org/direct_bt/BTAdapter.java
@@ -31,10 +31,15 @@ package org.direct_bt;
 import java.util.List;
 
 /**
-  * Provides access to Bluetooth adapters.
+  * BTAdapter represents one Bluetooth Controller.
+  * <p>
+  * BTAdapter roles:
+  *
+  * - {@link BTRole#Master} discovery is enabled via {@link #startDiscovery(boolean, boolean, short, short, byte) startDiscovery(..)}, but also per default at construction.
+  * - {@link BTRole#Slave} once advertising is enabled via {@link #startAdvertising(short, short, byte, byte, byte) startAdvertising(..)}, explicit until next {@link #startDiscovery(boolean, boolean, short, short, byte) startDiscovery(..)}.
+  * </p>
   *
   * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
-  * @see [BlueZ adapter API](http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/adapter-api.txt)
   */
 public interface BTAdapter extends BTObject
 {
@@ -43,6 +48,18 @@ public interface BTAdapter extends BTObject
      */
     public BTManager getManager();
 
+    /**
+     * Return the current {@link BTRole} of this adapter.
+     * @since 2.4.0
+     */
+    public BTRole getRole();
+
+    /**
+     * Returns the current {@link BTMode} of this adapter.
+     * @since 2.4.0
+     */
+    public BTMode getBTMode();
+
     /** Find a BluetoothDevice. If parameters name and address are not null,
       * the returned object will have to match them.
       * It will first check for existing objects. It will not turn on discovery
diff --git a/java/org/direct_bt/BTDevice.java b/java/org/direct_bt/BTDevice.java
index 70cfdba8..03d4150f 100644
--- a/java/org/direct_bt/BTDevice.java
+++ b/java/org/direct_bt/BTDevice.java
@@ -32,12 +32,10 @@ import java.util.List;
 import java.util.Map;
 
 /**
-  * Provides access to Bluetooth adapters.
-  *
-  * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
-  * @see [BlueZ device API](http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/device-api.txt)
-  *
-  */
+ * BTDevice represents one Bluetooth device.
+ *
+ * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
+ */
 public interface BTDevice extends BTObject
 {
     /** Find a BluetoothGattService. If parameter UUID is not null,
diff --git a/java/org/direct_bt/BTRole.java b/java/org/direct_bt/BTRole.java
new file mode 100644
index 00000000..ac50fa18
--- /dev/null
+++ b/java/org/direct_bt/BTRole.java
@@ -0,0 +1,75 @@
+/**
+ * Author: Sven Gothel <[email protected]>
+ * Copyright (c) 2021 Gothel Software e.K.
+ * Copyright (c) 2021 ZAFENA AB
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package org.direct_bt;
+
+/**
+ * Bluetooth device roles from the perspective of the link layer (connection initiator).
+ * <p>
+ * See {@link #get(byte)} for its native integer mapping.
+ * </p>
+ * @since 2.4.0
+ */
+public enum BTRole {
+    /** Undefined role. */
+    None      ((byte)0),
+    /** Master or *central* role, discovering remote devices and initiating connection. This is a GATT client. */
+    Master    ((byte)1),
+    /** Slave or *peripheral* role, advertising and waiting for connections to accept. This is a GATT server. */
+    Slave     ((byte)2);
+
+    public final byte value;
+
+    /**
+     * Maps the specified name to a constant of BTRole.
+     * <p>
+     * Implementation simply returns {@link #valueOf(String)}.
+     * This maps the constant names itself to their respective constant.
+     * </p>
+     * @param name the string name to be mapped to a constant of this enum type.
+     * @return the corresponding constant of this enum type.
+     * @throws IllegalArgumentException if the specified name can't be mapped to a constant of this enum type
+     *                                  as described above.
+     */
+    public static BTRole get(final String name) throws IllegalArgumentException {
+        return valueOf(name);
+    }
+
+    /**
+     * Maps the specified integer value to a constant of {@link BTRole}.
+     * @param value the integer value to be mapped to a constant of this enum type.
+     * @return the corresponding constant of this enum type, using {@link #None} if not supported.
+     */
+    public static BTRole get(final byte value) {
+        switch(value) {
+            case (byte)0x01: return Master;
+            case (byte)0x02: return Slave;
+            default: return None;
+        }
+    }
+
+    BTRole(final byte v) {
+        value = v;
+    }
+}