Adding C++ module/groups to separate the C++ API levels for the user; Adding reference to perihperal-server mode to overview.v2.7.1

11 files changed, 84 insertions, 21 deletions

diff --git a/java/org/direct_bt/AdapterSettings.java b/java/org/direct_bt/AdapterSettings.java
index a14e0b0b..47deb10f 100644
--- a/java/org/direct_bt/AdapterSettings.java
+++ b/java/org/direct_bt/AdapterSettings.java
@@ -20,10 +20,16 @@
  *   - Using *BlueZ Kernel Manager Control Channel* via MgmtMsg communication.
  * - *HCI Handling* via HCIHandler using HCIPacket implementing connect/disconnect w/ tracking, device discovery, etc
  * - *ATT PDU* AttPDUMsg via L2CAP for low level packet communication
- * - *GATT Support* via BTGattHandler using AttPDUMsg over L2CAPComm, providing
- *   -  BTGattService
- *   -  BTGattChar
- *   -  BTGattDesc
+ * - *GATT Support* via BTGattHandler using AttPDUMsg over L2CAPComm, ...
+ *   - Central-Client Functionality, i.e. GATT client role or BTAdapter in {@link BTRole#Master}:
+ *     - BTGattService
+ *     - BTGattChar
+ *     - BTGattDesc
+ *   - Peripheral-Server Functionality, i.e. GATT server role or BTAdapter in {@link BTRole#Slave}:
+ *     - DBGattServer
+ *     - DBGattService
+ *     - DBGattChar
+ *     - DBGattDesc
  * - *SMP PDU* SMPPDUMsg via L2CAP for Security Manager Protocol (SMP) communication
  * - *SMP Support* via SMPHandler using SMPPDUMsg over L2CAPComm, providing (Not yet supported by Linux/BlueZ)
  *   - LE Secure Connections
@@ -44,7 +50,8 @@
  *
  * ## Direct-BT User Hierarchy
  *
- * From a user perspective the following hierarchy is provided
+ * From a user central-client perspective the following hierarchy is provided,
+ * i.e. GATT client role or BTAdapter in {@link BTRole#Master}:
  * - BTManager has zero or more
  *   - BTAdapter has zero or more
  *     - BTDevice has zero or more
@@ -52,6 +59,15 @@
  *         - BTGattChar has zero or more
  *           - BTGattDesc
  *
+ * From a user peripheral-server perspective the following hierarchy is provided,
+ * i.e. GATT server role or BTAdapter in {@link BTRole#Slave}:
+ * - BTManager has zero or more
+ *   - BTAdapter has zero or one
+ *     - DBGattServer has zero or more
+ *       - DBGattService has zero or more
+ *         - DBGattChar has zero or more
+ *           - DBGattDesc
+ *
  * - - - - - - - - - - - - - - -
  *
  * ## Direct-BT Object Lifecycle
@@ -65,6 +81,12 @@
  *         - BTGattChar ownership by BTGattService, with weak BTGattService back-reference
  *           - BTGattDesc ownership by BTGattChar, with weak BTGattChar back-reference
  *
+ * User application instantiates for peripheral-server functionality:
+ * - DBGattServer ownership by user
+ *   - DBGattService ownership by user
+ *     - DBGattChar ownership by user
+ *       - DBGattDesc
+ *
  * - - - - - - - - - - - - - - -
  *
  * ## Direct-BT Mapped Names C++ vs Java
@@ -72,16 +94,19 @@
  * Mapped names from C++ implementation to Java implementation and to Java interface:
  *
  *  C++  <br> `direct_bt` | Java Implementation  <br> `jau.direct_bt` | Java Interface <br> `org.direct_bt` |
- *  :----------------| :---------------------| :--------------------|
- *  BTManager        | DBTManager            | BTManager            |
- *  BTAdapter        | DBTAdapter            | BTAdapter            |
- *  BTDevice         | DBTDevice             | BTDevice             |
- *  BTGattService    | DBTGattService        | BTGattService        |
- *  BTGattChar       | DBTGattChar           | BTGattChar           |
- *  BTGattDesc       | DBTGattDesc           | BTGattDesc           |
- *  AdapterStatusListener |                  | AdapterStatusListener   |
- *  BTGattCharListener |                     | BTGattCharListener   |
- *  ChangedAdapterSetFunc() |                | BTManager::ChangedAdapterSetListener   |
+ *  :-----------------------| :-----------------| :------------------------------------|
+ *  BTManager               | DBTManager        | BTManager                            |
+ *  BTAdapter               | DBTAdapter        | BTAdapter                            |
+ *  BTDevice                | DBTDevice         | BTDevice                             |
+ *  BTGattService           | DBTGattService    | BTGattService                        |
+ *  BTGattChar              | DBTGattChar       | BTGattChar                           |
+ *  BTGattDesc              | DBTGattDesc       | BTGattDesc                           |
+ *  DBGattService           |                   | DBGattService                        |
+ *  DBGattChar              |                   | DBGattChar                           |
+ *  DBGattDesc              |                   | DBGattDesc                           |
+ *  AdapterStatusListener   |                   | AdapterStatusListener                |
+ *  BTGattCharListener      |                   | BTGattCharListener                   |
+ *  ChangedAdapterSetFunc() |                   | BTManager::ChangedAdapterSetListener |
  *
  * - - - - - - - - - - - - - - -
  *
diff --git a/java/org/direct_bt/BTAdapter.java b/java/org/direct_bt/BTAdapter.java
index 1a0c9732..ee5f3efa 100644
--- a/java/org/direct_bt/BTAdapter.java
+++ b/java/org/direct_bt/BTAdapter.java
@@ -42,6 +42,7 @@ import java.util.List;
   * @see BTDevice
   * @see [BTDevice roles](@ref BTDeviceRoles).
   * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
+  * @see [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details)
   */
 public interface BTAdapter extends BTObject
 {
diff --git a/java/org/direct_bt/BTDevice.java b/java/org/direct_bt/BTDevice.java
index 57187d6b..253bdd3b 100644
--- a/java/org/direct_bt/BTDevice.java
+++ b/java/org/direct_bt/BTDevice.java
@@ -42,6 +42,7 @@ import java.util.Map;
  * @see BTAdapter
  * @see [BTAdapter roles](@ref BTAdapterRoles).
  * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
+ * @see [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details)
  */
 public interface BTDevice extends BTObject
 {
diff --git a/java/org/direct_bt/BTGattChar.java b/java/org/direct_bt/BTGattChar.java
index bb185da7..11063873 100644
--- a/java/org/direct_bt/BTGattChar.java
+++ b/java/org/direct_bt/BTGattChar.java
@@ -30,9 +30,12 @@ import java.util.List;
 /**
  * Representing a Gatt Characteristic object from the GATT client perspective.
  *
- * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3 Characteristic Definition
+ * A list of shared BTGattChar instances is available from BTGattService
+ * via BTGattService::getChars().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
  *
- * handle -> CDAV value
+ * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3 Characteristic Definition
  *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 4.6.1 Discover All Characteristics of a Service
  *
diff --git a/java/org/direct_bt/BTGattDesc.java b/java/org/direct_bt/BTGattDesc.java
index aaba037b..618be333 100644
--- a/java/org/direct_bt/BTGattDesc.java
+++ b/java/org/direct_bt/BTGattDesc.java
@@ -28,6 +28,11 @@ package org.direct_bt;
 /**
  * Representing a Gatt Characteristic Descriptor object from the GATT client perspective.
  *
+ * A list of shared BTGattDesc instances is available from BTGattChar
+ * via BTGattChar::getDescriptors().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
+ *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3 Characteristic Descriptor
  *
  * See {@link DBGattDesc.UUID16} for selected standard GATT descriptor numbers in UUID16 format
diff --git a/java/org/direct_bt/BTGattService.java b/java/org/direct_bt/BTGattService.java
index 592ca9fc..6bc48fd0 100644
--- a/java/org/direct_bt/BTGattService.java
+++ b/java/org/direct_bt/BTGattService.java
@@ -31,6 +31,11 @@ import java.util.List;
 /**
  * Representing a Gatt Service object from the GATT client perspective.
  *
+ * A list of shared BTGattService instances can be retrieved from BTDevice
+ * after successful connection and optional pairing via BTDevice::getGattServices().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
+ *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 3.1 Service Definition
  *
  * Includes a complete [Primary] Service Declaration
diff --git a/java/org/direct_bt/BTManager.java b/java/org/direct_bt/BTManager.java
index c3de67bc..e30f7764 100644
--- a/java/org/direct_bt/BTManager.java
+++ b/java/org/direct_bt/BTManager.java
@@ -27,6 +27,11 @@ package org.direct_bt;
 
 import java.util.List;
 
+/**
+ * A thread safe singleton handler of the BTAdapter manager, e.g. Linux Kernel's BlueZ manager control channel.
+ *
+ * @see [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details)
+ */
 public interface BTManager
 {
     /**
@@ -43,6 +48,7 @@ public interface BTManager
      * @since 2.0.0
      * @see BTManager#addChangedAdapterSetListener(ChangedAdapterSetListener)
      * @see BTManager#removeChangedAdapterSetListener(ChangedAdapterSetListener)
+     * @see [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details)
      */
     public static interface ChangedAdapterSetListener {
         /**
diff --git a/java/org/direct_bt/DBGattChar.java b/java/org/direct_bt/DBGattChar.java
index 0872ba5e..7638d011 100644
--- a/java/org/direct_bt/DBGattChar.java
+++ b/java/org/direct_bt/DBGattChar.java
@@ -30,9 +30,12 @@ import java.util.List;
 /**
  * Representing a Gatt Characteristic object from the GATT server perspective.
  *
- * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3 Characteristic Definition
+ * A list of shared DBGattChar instances are passed at DBGattService construction
+ * and are retrievable via DBGattService::getChars().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
  *
- * handle -> CDAV value
+ * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3 Characteristic Definition
  *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 4.6.1 Discover All Characteristics of a Service
  *
diff --git a/java/org/direct_bt/DBGattDesc.java b/java/org/direct_bt/DBGattDesc.java
index 4a7495ab..81303da6 100644
--- a/java/org/direct_bt/DBGattDesc.java
+++ b/java/org/direct_bt/DBGattDesc.java
@@ -28,6 +28,11 @@ package org.direct_bt;
 /**
  * Representing a Gatt Characteristic Descriptor object from the GATT server perspective.
  *
+ * A list of shared DBGattChar instances are passed at DBGattChar construction
+ * and are retrievable via DBGattChar::getDescriptors().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
+ *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3 Characteristic Descriptor
  *
  * @since 2.4.0
diff --git a/java/org/direct_bt/DBGattServer.java b/java/org/direct_bt/DBGattServer.java
index e4001198..59fcb8da 100644
--- a/java/org/direct_bt/DBGattServer.java
+++ b/java/org/direct_bt/DBGattServer.java
@@ -32,8 +32,12 @@ import java.util.List;
  * Representing a complete list of Gatt Service objects from the GATT server perspective,
  * i.e. the Gatt Server database.
  *
- * One instance shall be attached to BTAdapter
- * when operating in Gatt Server mode.
+ * One instance shall be attached to BTAdapter when advertising via BTAdapter::startAdvertising(),
+ * changing its operating mode to Gatt Server mode.
+ *
+ * The instance can also be retrieved via BTAdapter::getGATTServerData().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
  *
  * @since 2.4.0
  */
diff --git a/java/org/direct_bt/DBGattService.java b/java/org/direct_bt/DBGattService.java
index bb8aed32..d7054485 100644
--- a/java/org/direct_bt/DBGattService.java
+++ b/java/org/direct_bt/DBGattService.java
@@ -30,6 +30,11 @@ import java.util.List;
 /**
  * Representing a Gatt Service object from the ::GATTRole::Server perspective.
  *
+ * A list of shared DBGattService instances are passed at DBGattServer construction
+ * and are retrievable via DBGattServer::getServices().
+ *
+ * See [Direct-BT Overview](namespaceorg_1_1direct__bt.html#details).
+ *
  * BT Core Spec v5.2: Vol 3, Part G GATT: 3.1 Service Definition
  *
  * Includes a complete [Primary] Service Declaration