From 82ccb78a8543bf712be591f93fd728ed65b440b4 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Sun, 22 May 2022 03:54:46 +0200 Subject: Adding C++ module/groups to separate the C++ API levels for the user; Adding reference to perihperal-server mode to overview. --- java/org/direct_bt/AdapterSettings.java | 55 ++++++++++++++++++++++++--------- java/org/direct_bt/BTAdapter.java | 1 + java/org/direct_bt/BTDevice.java | 1 + java/org/direct_bt/BTGattChar.java | 7 +++-- java/org/direct_bt/BTGattDesc.java | 5 +++ java/org/direct_bt/BTGattService.java | 5 +++ java/org/direct_bt/BTManager.java | 6 ++++ java/org/direct_bt/DBGattChar.java | 7 +++-- java/org/direct_bt/DBGattDesc.java | 5 +++ java/org/direct_bt/DBGattServer.java | 8 +++-- java/org/direct_bt/DBGattService.java | 5 +++ 11 files changed, 84 insertions(+), 21 deletions(-) (limited to 'java/org') 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++
`direct_bt` | Java Implementation
`jau.direct_bt` | Java Interface
`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 -- cgit v1.2.3