Direct-BT  2.3.1
Direct-BT - Direct Bluetooth Programming.
Public Member Functions | Protected Member Functions | List of all members
jau.direct_bt.DBTAdapter Class Reference
Inheritance diagram for jau.direct_bt.DBTAdapter:
Collaboration diagram for jau.direct_bt.DBTAdapter:

Public Member Functions

final BTManager getManager ()
 Returns the used singleton BTManager instance, used to create this adapter. More...
 
void close ()
 Release the native memory associated with this object The object should not be used following a call to close. More...
 
boolean equals (final Object obj)
 
BDAddressAndType getAddressAndType ()
 Returns the adapter's public BDAddressAndType. More...
 
BDAddressAndType getVisibleAddressAndType ()
 Returns the adapter's currently visible BDAddressAndType. More...
 
String getName ()
 Returns the system name of this adapter. More...
 
int getDevID ()
 Returns the BluetoothAdapter's internal temporary device id. More...
 
BTType getBluetoothType ()
 Returns the BluetoothType of this object. More...
 
BTDevice find (final String name, final BDAddressAndType addressAndType, final long timeoutMS)
 Find a BluetoothDevice. More...
 
BTDevice find (final String name, final BDAddressAndType addressAndType)
 Find a BluetoothDevice. More...
 
final boolean isDeviceWhitelisted (final BDAddressAndType addressAndType)
 Returns true, if the adapter's device is already whitelisted. More...
 
boolean addDeviceToWhitelist (final BDAddressAndType addressAndType, final HCIWhitelistConnectType ctype, final short conn_interval_min, final short conn_interval_max, final short conn_latency, final short timeout)
 Add the given device to the adapter's autoconnect whitelist. More...
 
boolean addDeviceToWhitelist (final BDAddressAndType addressAndType, final HCIWhitelistConnectType ctype)
 Add the given device to the adapter's autoconnect whitelist. More...
 
boolean removeDeviceFromWhitelist (final BDAddressAndType addressAndType)
 Remove the given device from the adapter's autoconnect whitelist. More...
 
boolean getDiscoverable ()
 Returns the discoverable state the adapter. More...
 
final ScanType getCurrentScanType ()
 Returns the current meta discovering ScanType. More...
 
String toString ()
 
native boolean setPowered (boolean value)
 Sets the power state the adapter. More...
 
final HCIStatusCode reset ()
 Reset the adapter. More...
 
native String getAlias ()
 Returns the friendly name of this adapter. More...
 
native void setAlias (final String value)
 Sets the friendly name of this adapter. More...
 
native boolean setDiscoverable (boolean value)
 Sets the discoverable state the adapter. More...
 
final BTDevice connectDevice (final BDAddressAndType addressAndType)
 This method connects to device without need of performing General Discovery. More...
 
native boolean setPairable (boolean value)
 Sets the discoverable state the adapter. More...
 
boolean getPoweredState ()
 Returns the power state the adapter. More...
 
final boolean isPowered ()
 Returns whether the adapter is valid, plugged in and powered. More...
 
native boolean isPoweredImpl ()
 
final boolean isSuspended ()
 Returns whether the adapter is suspended, i.e. More...
 
native boolean isSuspendedImpl ()
 
final boolean isValid ()
 Returns whether the adapter is valid, i.e. More...
 
native boolean isValidImpl ()
 
HCIStatusCode startDiscovery (final boolean keepAlive, final boolean le_scan_active) throws BTException
 Turns on device discovery if it is disabled. More...
 
HCIStatusCode startDiscovery (final boolean keepAlive, final boolean le_scan_active, final short le_scan_interval, final short le_scan_window, final byte filter_policy) throws BTException
 Shares same implementation as startDiscovery(boolean, boolean), but allows setting custom scan values. More...
 
HCIStatusCode stopDiscovery () throws BTException
 Turns off device discovery if it is enabled. More...
 
int removeDiscoveredDevices () throws BTException
 Remove all the discovered devices found on this adapter. More...
 
boolean removeDiscoveredDevice (final BDAddressAndType addressAndType)
 Discards matching discovered devices. More...
 
List< BTDevicegetDiscoveredDevices ()
 Returns a list of discovered BluetoothDevices from this adapter. More...
 
final boolean addStatusListener (final AdapterStatusListener l)
 Add the given AdapterStatusListener to the list if not already present. More...
 
boolean removeStatusListener (final AdapterStatusListener l)
 Remove the given AdapterStatusListener from the list. More...
 
native int removeAllStatusListener ()
 Remove all AdapterStatusListener from the list. More...
 
final void printDeviceLists ()
 Print the internally maintained BTDevice lists to stderr: More...
 
- Public Member Functions inherited from jau.direct_bt.DBTObject
final int hashCode ()
 
BTObject clone ()
 

Protected Member Functions

native void deleteImpl (long nativeInstance)
 Deletes the native instance. More...
 
- Protected Member Functions inherited from jau.direct_bt.DBTObject
 DBTObject (final long nativeInstance, final int hashValue)
 
void finalize ()
 

Detailed Description

Definition at line 58 of file DBTAdapter.java.

Member Function Documentation

◆ addDeviceToWhitelist() [1/2]

boolean jau.direct_bt.DBTAdapter.addDeviceToWhitelist ( final BDAddressAndType  addressAndType,
final HCIWhitelistConnectType  ctype 
)

Add the given device to the adapter's autoconnect whitelist.

This variant of addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType, short, short, short, short) uses default connection parameter, which will be uploaded to the kernel for the given device first.

Method will reject duplicate devices, in which case it should be removed first.

Parameters
address
address_type
ctype
Returns
true
if successful, otherwise
false
.
See also
#addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType, short, short, short, short)
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 196 of file DBTAdapter.java.

◆ addDeviceToWhitelist() [2/2]

boolean jau.direct_bt.DBTAdapter.addDeviceToWhitelist ( final BDAddressAndType  addressAndType,
final HCIWhitelistConnectType  ctype,
final short  conn_interval_min,
final short  conn_interval_max,
final short  conn_latency,
final short  timeout 
)

Add the given device to the adapter's autoconnect whitelist.

The given LE connection parameter will be uploaded to the kernel for the given device first, if the device is of type BDAddressType#BDADDR_LE_PUBLIC or BDAddressType#BDADDR_LE_RANDOM.

Method will reject duplicate devices, in which case it should be removed first.

Parameters
address
address_type
ctype
conn_interval_mindefault value 0x000F
conn_interval_maxdefault value 0x000F
conn_latencydefault value 0x0000
timeoutin units of 10ms, default value 1000 for 10000ms or 10s.
Returns
true
if successful, otherwise
false
.
See also
#addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType)
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 184 of file DBTAdapter.java.

◆ addStatusListener()

final boolean jau.direct_bt.DBTAdapter.addStatusListener ( final AdapterStatusListener  listener)

Add the given AdapterStatusListener to the list if not already present.

In case the AdapterStatusListener's lifecycle and event delivery shall be constrained to this device, please use BTDevice#addStatusListener(AdapterStatusListener).

The newly added AdapterStatusListener will receive an initial adapterSettingsChanged event, passing an empty oldMask and changedMask, as well as current newMask.
This allows the receiver to be aware of this adapter's current settings.

Parameters
listenerA AdapterStatusListener instance
Returns
true if the given listener is not element of the list and has been newly added, otherwise false.
Since
2.3.0
See also
BTDevice#addStatusListener(AdapterStatusListener)
removeStatusListener(AdapterStatusListener)
removeAllStatusListener()

Implements org.direct_bt.BTAdapter.

Definition at line 397 of file DBTAdapter.java.

Here is the call graph for this function:

◆ close()

void jau.direct_bt.DBTAdapter.close ( )

Release the native memory associated with this object The object should not be used following a call to close.

Reimplemented from jau.direct_bt.DBTObject.

Definition at line 106 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ connectDevice()

final BTDevice jau.direct_bt.DBTAdapter.connectDevice ( final BDAddressAndType  addressAndType)

This method connects to device without need of performing General Discovery.

Connection mechanism is similar to Connect method from Device1 interface with exception that this method returns success when physical connection is established. After this method returns, services discovery will continue and any supported profile will be connected. There is no need for calling Connect on Device1 after this call. If connection was successful this method returns object path to created device object.

Parameters
addressThe Bluetooth device address of the remote device. This parameter is mandatory.
addressTypeThe Bluetooth device Address Type. This is address type that should be used for initial connection. If this parameter is not present BR/EDR device is created. Possible values:
  • public
    - Public address
  • random
    - Random address

Implements org.direct_bt.BTAdapter.

Definition at line 251 of file DBTAdapter.java.

◆ deleteImpl()

native void jau.direct_bt.DBTAdapter.deleteImpl ( long  nativeInstance)
protected

Deletes the native instance.

Called via delete() and at this point

  • this java reference has been removed from the native instance, i.e.
    JavaUplink
    's
    javaObjectRef = nullptr
  • the nativeInstance reference has been zeroed, but passed as argument for this final native deletion task.
Parameters
nativeInstancecopy of nativeInstance reference, which has been already zeroed.

Reimplemented from jau.direct_bt.DBTNativeDownlink.

◆ equals()

boolean jau.direct_bt.DBTAdapter.equals ( final Object  obj)

Reimplemented from jau.direct_bt.DBTObject.

Definition at line 140 of file DBTAdapter.java.

Here is the call graph for this function:

◆ find() [1/2]

BTDevice jau.direct_bt.DBTAdapter.find ( final String  name,
final BDAddressAndType  addressAndType 
)

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 or connect to devices. @parameter name optionally specify the name of the object you are waiting for @parameter address optionally specify the MAC address of the device you are waiting for

Returns
An object matching the name and address.

Implements org.direct_bt.BTAdapter.

Definition at line 175 of file DBTAdapter.java.

Here is the call graph for this function:

◆ find() [2/2]

BTDevice jau.direct_bt.DBTAdapter.find ( final String  name,
final BDAddressAndType  addressAndType,
final long  timeoutMS 
)

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 or connect to devices. @parameter name optionally specify the name of the object you are waiting for @parameter address optionally specify the MAC address of the device you are waiting for @parameter timeoutMS the function will return after timeout time in milliseconds, a value of zero means wait forever. If object is not found during this time null will be returned.

Returns
An object matching the name and address or null if not found before timeout expires.

Implements org.direct_bt.BTAdapter.

Definition at line 170 of file DBTAdapter.java.

Here is the caller graph for this function:

◆ getAddressAndType()

BDAddressAndType jau.direct_bt.DBTAdapter.getAddressAndType ( )

Returns the adapter's public BDAddressAndType.

The adapter's address as initially reported by the system is always its public address, i.e. BDAddressType#BDADDR_LE_PUBLIC.

Since
2.2.8
See also
getVisibleAddressAndType()

Implements org.direct_bt.BTAdapter.

Definition at line 153 of file DBTAdapter.java.

◆ getAlias()

native String jau.direct_bt.DBTAdapter.getAlias ( )

Returns the friendly name of this adapter.

Returns
The friendly name of this adapter, or NULL if not set.

Implements org.direct_bt.BTAdapter.

◆ getBluetoothType()

BTType jau.direct_bt.DBTAdapter.getBluetoothType ( )

Returns the BluetoothType of this object.

Returns
The BluetoothType of this object

Implements org.direct_bt.BTObject.

Definition at line 165 of file DBTAdapter.java.

◆ getCurrentScanType()

final ScanType jau.direct_bt.DBTAdapter.getCurrentScanType ( )

Returns the current meta discovering ScanType.

It can be modified through startDiscovery(boolean, boolean) and stopDiscovery().

Note that if startDiscovery(boolean, boolean) has been issued with keepAlive==true, the meta ScanType will still keep the desired ScanType enabled even if it has been temporarily disabled.

See also
#startDiscovery(boolean)
stopDiscovery()
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 214 of file DBTAdapter.java.

Here is the call graph for this function:

◆ getDevID()

int jau.direct_bt.DBTAdapter.getDevID ( )

Returns the BluetoothAdapter's internal temporary device id.

The internal device id is constant across the adapter lifecycle, but may change after its destruction.

Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 162 of file DBTAdapter.java.

◆ getDiscoverable()

boolean jau.direct_bt.DBTAdapter.getDiscoverable ( )

Returns the discoverable state the adapter.

Returns
The discoverable state of the adapter.

Implements org.direct_bt.BTAdapter.

Definition at line 211 of file DBTAdapter.java.

◆ getDiscoveredDevices()

List<BTDevice> jau.direct_bt.DBTAdapter.getDiscoveredDevices ( )

Returns a list of discovered BluetoothDevices from this adapter.

Returns
A list of discovered BluetoothDevices on this adapter, NULL if an error occurred

Implements org.direct_bt.BTAdapter.

Definition at line 371 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getManager()

final BTManager jau.direct_bt.DBTAdapter.getManager ( )

Returns the used singleton BTManager instance, used to create this adapter.

Implements org.direct_bt.BTAdapter.

Definition at line 103 of file DBTAdapter.java.

Here is the call graph for this function:

◆ getName()

String jau.direct_bt.DBTAdapter.getName ( )

Returns the system name of this adapter.

Returns
The system name of this adapter.

Implements org.direct_bt.BTAdapter.

Definition at line 159 of file DBTAdapter.java.

◆ getPoweredState()

boolean jau.direct_bt.DBTAdapter.getPoweredState ( )

Returns the power state the adapter.

Consider using isPowered()

Returns
The power state of the adapter.
Since
2.0.0 Renamed from getPowered() to getPoweredState()
See also
isPowered()
isSuspended()
isValid()

Implements org.direct_bt.BTAdapter.

Definition at line 260 of file DBTAdapter.java.

◆ getVisibleAddressAndType()

BDAddressAndType jau.direct_bt.DBTAdapter.getVisibleAddressAndType ( )

Returns the adapter's currently visible BDAddressAndType.

The adapter's address as initially reported by the system is always its public address, i.e. BDAddressType#BDADDR_LE_PUBLIC.

The adapter's visible BDAddressAndType might be set to BDAddressType#BDADDR_LE_RANDOM before scanning / discovery mode (TODO).

Since
2.2.8
See also
getAddressAndType()

Implements org.direct_bt.BTAdapter.

Definition at line 156 of file DBTAdapter.java.

◆ isDeviceWhitelisted()

final boolean jau.direct_bt.DBTAdapter.isDeviceWhitelisted ( final BDAddressAndType  addressAndType)

Returns true, if the adapter's device is already whitelisted.

Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 180 of file DBTAdapter.java.

◆ isPowered()

final boolean jau.direct_bt.DBTAdapter.isPowered ( )

Returns whether the adapter is valid, plugged in and powered.

Returns
true if isValid(), HCI channel open and POWERED state is set.
See also
isSuspended()
isValid()
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 263 of file DBTAdapter.java.

Here is the call graph for this function:

◆ isPoweredImpl()

native boolean jau.direct_bt.DBTAdapter.isPoweredImpl ( )
Here is the caller graph for this function:

◆ isSuspended()

final boolean jau.direct_bt.DBTAdapter.isSuspended ( )

Returns whether the adapter is suspended, i.e.

valid and plugged in, but not powered.

Returns
true if isValid(), HCI channel open and POWERED state is not set.
See also
isPowered()
isValid()

Implements org.direct_bt.BTAdapter.

Definition at line 267 of file DBTAdapter.java.

Here is the call graph for this function:

◆ isSuspendedImpl()

native boolean jau.direct_bt.DBTAdapter.isSuspendedImpl ( )
Here is the caller graph for this function:

◆ isValid()

final boolean jau.direct_bt.DBTAdapter.isValid ( )

Returns whether the adapter is valid, i.e.

reference is valid, plugged in and generally operational, but not necessarily isPowered().

Returns
true if this adapter references are valid and hadn't been close()'ed
See also
isPowered()
isSuspended()
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 271 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isValidImpl()

native boolean jau.direct_bt.DBTAdapter.isValidImpl ( )
Here is the caller graph for this function:

◆ printDeviceLists()

final void jau.direct_bt.DBTAdapter.printDeviceLists ( )

Print the internally maintained BTDevice lists to stderr:

  • sharedDevices
  • connectedDevice
  • discoveredDevices
  • StatusListener

This is intended as a debug facility.

Since
2.3.0

Implements org.direct_bt.BTAdapter.

Definition at line 425 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeAllStatusListener()

native int jau.direct_bt.DBTAdapter.removeAllStatusListener ( )

Remove all AdapterStatusListener from the list.

Returns
number of removed listener.
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Here is the caller graph for this function:

◆ removeDeviceFromWhitelist()

boolean jau.direct_bt.DBTAdapter.removeDeviceFromWhitelist ( final BDAddressAndType  addressAndType)

Remove the given device from the adapter's autoconnect whitelist.

Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 203 of file DBTAdapter.java.

◆ removeDiscoveredDevice()

boolean jau.direct_bt.DBTAdapter.removeDiscoveredDevice ( final BDAddressAndType  addressAndType)

Discards matching discovered devices.

Returns
true
if found and removed, otherwise false.
Since
2.2.0

Implements org.direct_bt.BTAdapter.

Definition at line 344 of file DBTAdapter.java.

◆ removeDiscoveredDevices()

int jau.direct_bt.DBTAdapter.removeDiscoveredDevices ( ) throws BTException

Remove all the discovered devices found on this adapter.

Returns
The number of removed discovered devices on this adapter
Exceptions
BTException
Since
2.2.0 @implNote Changed from 'removeDiscoveredDevices()' for clarity since version 2.2.0

Implements org.direct_bt.BTAdapter.

Definition at line 321 of file DBTAdapter.java.

◆ removeStatusListener()

boolean jau.direct_bt.DBTAdapter.removeStatusListener ( final AdapterStatusListener  l)

Remove the given AdapterStatusListener from the list.

Parameters
listenerA AdapterStatusListener instance
Returns
true if the given listener is an element of the list and has been removed, otherwise false.
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 408 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reset()

final HCIStatusCode jau.direct_bt.DBTAdapter.reset ( )

Reset the adapter.

The semantics are specific to the HCI host implementation, however, it shall comply at least with the HCI Reset command and bring up the device from standby into a POWERED functional state afterwards.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.3.2 Reset command
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 236 of file DBTAdapter.java.

Here is the call graph for this function:

◆ setAlias()

native void jau.direct_bt.DBTAdapter.setAlias ( final String  value)

Sets the friendly name of this adapter.

Implements org.direct_bt.BTAdapter.

◆ setDiscoverable()

native boolean jau.direct_bt.DBTAdapter.setDiscoverable ( boolean  value)

Sets the discoverable state the adapter.

@apiNote return value boolean since 2.0.0

Since
2.0.0

Implements org.direct_bt.BTAdapter.

◆ setPairable()

native boolean jau.direct_bt.DBTAdapter.setPairable ( boolean  value)

Sets the discoverable state the adapter.

@apiNote return value boolean since 2.0.0

Since
2.0.0

Implements org.direct_bt.BTAdapter.

◆ setPowered()

native boolean jau.direct_bt.DBTAdapter.setPowered ( boolean  value)

Sets the power state the adapter.

@apiNote return value boolean since 2.0.0

Since
2.0.0

Implements org.direct_bt.BTAdapter.

◆ startDiscovery() [1/2]

HCIStatusCode jau.direct_bt.DBTAdapter.startDiscovery ( final boolean  keepAlive,
final boolean  le_scan_active 
) throws BTException

Turns on device discovery if it is disabled.

's implementation will always issue removeDiscoveredDevices(), ensuring all scanned devices will be found after calling this method. Regardless whether discovery is already running.

+ --+-------+--------+-----------+----------------------------------------------------+
| # | meta  | native | keepAlive | Note
+---+-------+--------+-----------+----------------------------------------------------+
| 1 | true  | true   | false     | -
| 2 | false | false  | false     | -
+---+-------+--------+-----------+----------------------------------------------------+
| 3 | true  | true   | true      | -
| 4 | true  | false  | true      | temporarily disabled -> startDiscoveryBackground()
| 5 | false | false  | true      | [4] -> [5] requires manual DISCOVERING event
+---+-------+--------+-----------+----------------------------------------------------+
Parameters
keepAliveif
true
, indicates that discovery shall be restarted if stopped by the underlying Bluetooth implementation (BlueZ, ..). Using startDiscovery(
keepAlive=true
) and stopDiscovery() is the recommended workflow for a reliable discovery process.
le_scan_activetrue enables delivery of active scanning PDUs, otherwise no scanning PDUs shall be sent (default)
Returns
HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state
Exceptions
BTException
Since
2.0.0
2.2.8
See also
#startDiscovery(boolean, boolean, int, int, byte)
#getDiscovering()

Implements org.direct_bt.BTAdapter.

Definition at line 280 of file DBTAdapter.java.

◆ startDiscovery() [2/2]

HCIStatusCode jau.direct_bt.DBTAdapter.startDiscovery ( final boolean  keepAlive,
final boolean  le_scan_active,
final short  le_scan_interval,
final short  le_scan_window,
final byte  filter_policy 
) throws BTException

Shares same implementation as startDiscovery(boolean, boolean), but allows setting custom scan values.

Parameters
keepAlive
le_scan_activetrue enables delivery of active scanning PDUs, otherwise no scanning PDUs shall be sent (default)
le_scan_intervalin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_windowin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]. Shall be <= le_scan_interval
filter_policy0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...
Returns
HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state
Exceptions
BTException
Since
2.2.8
See also
startDiscovery(boolean, boolean)
#getDiscovering()

Implements org.direct_bt.BTAdapter.

Definition at line 284 of file DBTAdapter.java.

Here is the call graph for this function:

◆ stopDiscovery()

HCIStatusCode jau.direct_bt.DBTAdapter.stopDiscovery ( ) throws BTException

Turns off device discovery if it is enabled.

Returns
HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state @apiNote return HCIStatusCode since 2.0.0
Since
2.0.0

Implements org.direct_bt.BTAdapter.

Definition at line 304 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString()

String jau.direct_bt.DBTAdapter.toString ( )

Definition at line 219 of file DBTAdapter.java.

Here is the call graph for this function:
Here is the caller graph for this function:

The documentation for this class was generated from the following file:
jau
jau.direct_bt
Author: Sven Gothel sgothel@jausoft.com Copyright (c) 2020 Gothel Software e.K.
Definition: DBTAdapter.java:26