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

Public Member Functions

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)
 
final long getCreationTimestamp ()
 Returns the timestamp in monotonic milliseconds when this device instance has been created, either via its initial discovery or its initial direct connection. More...
 
final long getLastDiscoveryTimestamp ()
 Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time. More...
 
final long getLastUpdateTimestamp ()
 Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time. More...
 
DBTAdapter getAdapter ()
 Returns the adapter on which this device was discovered or connected. More...
 
BDAddressAndType getAddressAndType ()
 Returns the unique device EUI48 address and BDAddressType type. More...
 
String getName ()
 Returns the remote friendly name of this device. More...
 
BTType getBluetoothType ()
 Returns the BluetoothType of this object. More...
 
BTGattService find (final String UUID, final long timeoutMS)
 Find a BluetoothGattService. More...
 
BTGattService find (final String UUID)
 Find a BluetoothGattService. More...
 
final boolean addStatusListener (final AdapterStatusListener l)
 Add the given AdapterStatusListener to the list if not already present, listening only for events matching this device. More...
 
boolean removeStatusListener (final AdapterStatusListener l)
 Remove the given AdapterStatusListener from the list. More...
 
final boolean getConnected ()
 Returns the connected state of the device. More...
 
final short getConnectionHandle ()
 Return the HCI connection handle to the LE or BREDR peer, zero if not connected. More...
 
final HCIStatusCode disconnect ()
 
final HCIStatusCode connect ()
 
HCIStatusCode connectLE (final short le_scan_interval, final short le_scan_window, final short conn_interval_min, final short conn_interval_max, final short conn_latency, final short timeout)
 Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device. More...
 
final SMPKeyMask getAvailableSMPKeys (final boolean responder)
 Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master). More...
 
final SMPLongTermKeyInfo getLongTermKeyInfo (final boolean responder)
 Returns a copy of the long term key (LTK) info, valid after connection and SMP pairing has been completed. More...
 
final HCIStatusCode setLongTermKeyInfo (final SMPLongTermKeyInfo ltk)
 Sets the long term ket (LTK) info of this device to reuse pre-paired encryption. More...
 
final SMPSignatureResolvingKeyInfo getSignatureResolvingKeyInfo (final boolean responder)
 Returns a copy of the Signature Resolving Key (LTK) info, valid after connection and SMP pairing has been completed. More...
 
final HCIStatusCode unpair ()
 Unpairs this device from the adapter while staying connected. More...
 
final boolean setConnSecurityLevel (final BTSecurityLevel sec_level)
 Set the BTSecurityLevel used to connect to this device on the upcoming connection. More...
 
final BTSecurityLevel getConnSecurityLevel ()
 Return the BTSecurityLevel, determined when the connection is established. More...
 
final boolean setConnIOCapability (final SMPIOCapability io_cap)
 Sets the given SMPIOCapability used to connect to this device on the upcoming connection. More...
 
final SMPIOCapability getConnIOCapability ()
 Return the SMPIOCapability value, determined when the connection is established. More...
 
final boolean setConnSecurity (final BTSecurityLevel sec_level, final SMPIOCapability io_cap)
 Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming connection. More...
 
final boolean setConnSecurityBest (final BTSecurityLevel sec_level, final SMPIOCapability io_cap)
 Convenience method to determine the best practice BTSecurityLevel and SMPIOCapability based on the given arguments, used to connect to this device on the upcoming connection. More...
 
final boolean setConnSecurityAuto (final SMPIOCapability iocap_auto)
 Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode. More...
 
final native boolean isConnSecurityAutoEnabled ()
 Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false. More...
 
HCIStatusCode setPairingPasskey (final int passkey)
 Method sets the given passkey entry, see PairingMode#PASSKEY_ENTRY_ini. More...
 
HCIStatusCode setPairingPasskeyNegative ()
 Method replies with a negative passkey response, i.e. More...
 
HCIStatusCode setPairingNumericComparison (final boolean equal)
 Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini. More...
 
PairingMode getPairingMode ()
 Returns the current PairingMode used by the device. More...
 
SMPPairingState getPairingState ()
 Returns the current SMPPairingState. More...
 
final String toString ()
 
final boolean remove () throws BTException
 Remove this device from the system (like an unpair).Direct-BT: Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared references from the Adapter: connected-devices, discovered-devices and shared-devices. This method shall be issued to ensure no device reference will be leaked in a long lived adapter, as only its reference within connected-devices and discovered-devices are removed at disconnect. After calling this method, this instance is destroyed and shall not be used anymore! This method is automatically called @ destructor. This method is an atomic operation. An application using one thread per device and rapid connect, should either use disconnect() or remove(), but never issue remove() after disconnect() if the device is in use.
Returns
TRUE if the device has been removed
Exceptions
BTException
More...
 
final boolean isValid ()
 Returns whether the device is valid, i.e. More...
 
List< BTGattService > getServices ()
 Returns a list of BluetoothGattServices available on this device. More...
 
boolean pingGATT ()
 Issues a GATT ping to the device, validating whether it is still reachable. More...
 
native short getRSSI ()
 Returns the Received Signal Strength Indicator of the device. More...
 
native Map< Short, byte[]> getManufacturerData ()
 Returns a map containing manufacturer specific advertisement data. More...
 
native short getTxPower ()
 Returns the transmission power level (0 means unknown). More...
 
boolean addCharListener (final BTGattCharListener listener)
 Add the given BTGattCharListener to the listener list if not already present. More...
 
native boolean removeCharListener (final BTGattCharListener l)
 Remove the given BTGattCharListener from the listener list. More...
 
native int removeAllAssociatedCharListener (final BTGattChar associatedCharacteristic)
 Remove all BTGattCharListener from the list, which are associated to the given BTGattChar. More...
 
native int removeAllCharListener ()
 Remove all BTGattCharListener from the list. More...
 
- Public Member Functions inherited from jau.direct_bt.DBTObject
final int hashCode ()
 
BTObject clone ()
 
- Public Member Functions inherited from jau.direct_bt.DBTNativeDownlink
final void delete ()
 Deletes the. More...
 

Protected Member Functions

native void deleteImpl (long nativeInstance)
 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.
More...
 
- Protected Member Functions inherited from jau.direct_bt.DBTObject
 DBTObject (final long nativeInstance, final int hashValue)
 
void finalize ()
 
- Protected Member Functions inherited from jau.direct_bt.DBTNativeDownlink
 DBTNativeDownlink (final long nativeInstance)
 

Detailed Description

Definition at line 57 of file DBTDevice.java.

Member Function Documentation

◆ addCharListener()

boolean jau.direct_bt.DBTDevice.addCharListener ( final BTGattCharListener  listener)

Add the given BTGattCharListener to the listener list if not already present.

To enable the actual BLE notification and/or indication, one needs to call BTGattChar#configNotificationIndication(boolean, boolean, boolean[]) or BTGattChar#enableNotificationOrIndication(boolean[]).

Parameters
listenerA BTGattCharListener instance, listening to all BTGattChar events of this device
Returns
true if the given listener is not element of the list and has been newly added, otherwise false.
Exceptions
IllegalStateExceptionif the BTDevice's BTGattHandler is null, i.e. not connected
IllegalStateExceptionif the given BTGattCharListener is already in use, i.e. added.
See also
BTGattChar::configNotificationIndication(boolean, boolean, boolean[])
BTGattChar::enableNotificationOrIndication(boolean[])
Since
2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 460 of file DBTDevice.java.

Here is the call graph for this function:

◆ addStatusListener()

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

Add the given AdapterStatusListener to the list if not already present, listening only for events matching this device.

The AdapterStatusListener is released at remove() or this device's destruction.

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
deviceMatchOptional BTDevice to be matched before calling any AdapterStatusListener
device*
methods. Pass
null
for no filtering.
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, BTDevice)
removeStatusListener(AdapterStatusListener)
removeAllStatusListener()

Implements org.direct_bt.BTDevice.

Definition at line 200 of file DBTDevice.java.

Here is the call graph for this function:

◆ close()

void jau.direct_bt.DBTDevice.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 121 of file DBTDevice.java.

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

◆ connect()

final HCIStatusCode jau.direct_bt.DBTDevice.connect ( )
jau.direct_bt

: Establish a default HCI connection to this device, using certain default parameter.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command
BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.5 Create Connection command

Depending on this device's addressType, either a BREDR (BDADDR_BREDR) or LE (BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM) connection is attempted.
If unacceptable, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The actual new connection handle will be delivered asynchronous and the connection event can be caught via AdapterStatusListener#deviceConnected(BTDevice, long), or if failed via AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long).

The device is tracked by the managing adapter.

flagged as auto-connectable.

Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
See also
connectLE(short, short, short, short, short, short)
Since
2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of
jau.direct_bt
. @implNote
jau.direct_bt
does not throw a BTException on error, only a 'general' exception in case of fatality like NPE etc (FIXME: Remove throws)

Implements org.direct_bt.BTDevice.

Definition at line 225 of file DBTDevice.java.

Here is the call graph for this function:

◆ connectLE()

HCIStatusCode jau.direct_bt.DBTDevice.connectLE ( final short  le_scan_interval,
final short  le_scan_window,
final short  conn_interval_min,
final short  conn_interval_max,
final short  conn_latency,
final short  supervision_timeout 
)

Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command

If this device's getAddressType() is not BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The actual new connection handle will be delivered asynchronous and the connection event can be caught via AdapterStatusListener#deviceConnected(BTDevice, long), or if failed via AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long).

The device is tracked by the managing adapter.

Default parameter are used if

-1

has been passed for any of the arguments.

Default parameter values are chosen for using public address resolution and usual connection latency, interval etc.

Set window to the same value as the interval, enables continuous scanning.

Parameters
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
conn_interval_minin units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_interval_maxin units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_latencyslave latency in units of connection events, default value 0; Value range [0 .. 0x01F3].
supervision_timeoutin units of 10ms, default value >= 10 x conn_interval_max, we use 500 ms minimum; Value range [0xA-0x0C80] for [100ms - 32s].
Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
See also
BTUtils::getHCIConnSupervisorTimeout(int, int, int, int)
connect()

Implements org.direct_bt.BTDevice.

Definition at line 234 of file DBTDevice.java.

Here is the call graph for this function:

◆ deleteImpl()

native void jau.direct_bt.DBTDevice.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.

Native implementation calls DBTDevice::remove()

Reimplemented from jau.direct_bt.DBTNativeDownlink.

◆ disconnect()

final HCIStatusCode jau.direct_bt.DBTDevice.disconnect ( )
jau.direct_bt

: Disconnect the LE or BREDR peer's GATT and HCI connection.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.6 Disconnect command

The actual disconnect event will be delivered asynchronous and the connection event can be caught via AdapterStatusListener::deviceDisconnected(..). If unacceptable, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The device will be removed from the managing adapter's connected devices when AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long) has been received.

An open GATT connection will also be closed.
The connection to this device is removed, removing all connected profiles.

An application using one thread per device and rapid connect, should either use disconnect() or remove(), but never issue remove() after disconnect(). Doing so would eventually delete the device being already in use by another thread due to discovery post disconnect!

Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
Since
2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of direct_bt @implNote
jau.direct_bt
does not throw a BTException on error, only a 'general' exception in case of fatality like NPE etc (FIXME: Remove throws)

Implements org.direct_bt.BTDevice.

Definition at line 216 of file DBTDevice.java.

Here is the call graph for this function:

◆ equals()

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

Reimplemented from jau.direct_bt.DBTObject.

Definition at line 139 of file DBTDevice.java.

Here is the call graph for this function:

◆ find() [1/2]

BTGattService jau.direct_bt.DBTDevice.find ( final String  UUID)

Find a BluetoothGattService.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattService you are waiting for

Returns
An object matching the UUID or null if not found before timeout expires or event is canceled.

Implements org.direct_bt.BTDevice.

Definition at line 189 of file DBTDevice.java.

Here is the call graph for this function:

◆ find() [2/2]

BTGattService jau.direct_bt.DBTDevice.find ( final String  UUID,
final long  timeoutMS 
)

Find a BluetoothGattService.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattService 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 UUID or null if not found before timeout expires or event is canceled.

Implements org.direct_bt.BTDevice.

Definition at line 184 of file DBTDevice.java.

Here is the caller graph for this function:

◆ getAdapter()

DBTAdapter jau.direct_bt.DBTDevice.getAdapter ( )

Returns the adapter on which this device was discovered or connected.

Returns
The adapter.

Implements org.direct_bt.BTDevice.

Definition at line 161 of file DBTDevice.java.

Here is the caller graph for this function:

◆ getAddressAndType()

BDAddressAndType jau.direct_bt.DBTDevice.getAddressAndType ( )

Returns the unique device EUI48 address and BDAddressType type.

Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 164 of file DBTDevice.java.

◆ getAvailableSMPKeys()

final SMPKeyMask jau.direct_bt.DBTDevice.getAvailableSMPKeys ( final boolean  responder)

Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master).

Parameters
responderif true, queries the responder (LL slave) key, otherwise the initiator (LL master) key.
Returns
SMPKeyMask.KeyType SMPKeyMask result
Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 256 of file DBTDevice.java.

◆ getBluetoothType()

BTType jau.direct_bt.DBTDevice.getBluetoothType ( )

Returns the BluetoothType of this object.

Returns
The BluetoothType of this object

Implements org.direct_bt.BTObject.

Definition at line 179 of file DBTDevice.java.

◆ getConnected()

final boolean jau.direct_bt.DBTDevice.getConnected ( )

Returns the connected state of the device.

Returns
The connected state of the device.

Implements org.direct_bt.BTDevice.

Definition at line 210 of file DBTDevice.java.

◆ getConnectionHandle()

final short jau.direct_bt.DBTDevice.getConnectionHandle ( )

Return the HCI connection handle to the LE or BREDR peer, zero if not connected.

Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 213 of file DBTDevice.java.

◆ getConnIOCapability()

final SMPIOCapability jau.direct_bt.DBTDevice.getConnIOCapability ( )

Return the SMPIOCapability value, determined when the connection is established.

Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
setConnSecurityLevel(BTSecurityLevel)
getConnSecurityLevel()
setConnIOCapability(SMPIOCapability)
setConnSecurity(BTSecurityLevel, SMPIOCapability)
setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 310 of file DBTDevice.java.

Here is the call graph for this function:

◆ getConnSecurityLevel()

final BTSecurityLevel jau.direct_bt.DBTDevice.getConnSecurityLevel ( )

Return the BTSecurityLevel, determined when the connection is established.

Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
setConnSecurityLevel(BTSecurityLevel)
#setConnIOCapability(SMPIOCapability, boolean)
getConnIOCapability()
#setConnSecurity(BTSecurityLevel, SMPIOCapability, boolean)
setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 298 of file DBTDevice.java.

Here is the call graph for this function:

◆ getCreationTimestamp()

final long jau.direct_bt.DBTDevice.getCreationTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance has been created, either via its initial discovery or its initial direct connection.

See also
BTUtils::currentTimeMillis()
Since
2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 152 of file DBTDevice.java.

◆ getLastDiscoveryTimestamp()

final long jau.direct_bt.DBTDevice.getLastDiscoveryTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time.

See also
BTUtils::currentTimeMillis()
Since
2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 155 of file DBTDevice.java.

◆ getLastUpdateTimestamp()

final long jau.direct_bt.DBTDevice.getLastUpdateTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time.

See also
BTUtils::currentTimeMillis()
Since
2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 158 of file DBTDevice.java.

◆ getLongTermKeyInfo()

final SMPLongTermKeyInfo jau.direct_bt.DBTDevice.getLongTermKeyInfo ( final boolean  responder)

Returns a copy of the long term key (LTK) info, valid after connection and SMP pairing has been completed.

Parameters
respondertrue will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).
Returns
the resulting key. SMPLongTermKeyInfo#enc_size will be zero if invalid.
See also
SMPPairingState#COMPLETED
AdapterStatusListener#deviceReady(BTDevice, long)
Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 262 of file DBTDevice.java.

◆ getManufacturerData()

native Map<Short, byte[]> jau.direct_bt.DBTDevice.getManufacturerData ( )

Returns a map containing manufacturer specific advertisement data.

An entry has a uint16_t key and an array of bytes.

Returns
manufacturer specific advertisement data.

Implements org.direct_bt.BTDevice.

◆ getName()

String jau.direct_bt.DBTDevice.getName ( )

Returns the remote friendly name of this device.

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

Implements org.direct_bt.BTDevice.

Definition at line 167 of file DBTDevice.java.

Here is the call graph for this function:

◆ getPairingMode()

PairingMode jau.direct_bt.DBTDevice.getPairingMode ( )

Returns the current PairingMode used by the device.

If the device is not paired, the current mode is PairingMode#NONE.

If the Pairing Feature Exchange is completed, i.e. SMPPairingState#FEATURE_EXCHANGE_COMPLETED as notified by devicePairingState the current mode reflects the currently used PairingMode.

In case the Pairing Feature Exchange is in progress, the current mode is PairingMode#NEGOTIATING.

Returns
current PairingMode.
See also
PairingMode
SMPPairingState
AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
setPairingPasskey(int)
setPairingNumericComparison(boolean)
getPairingMode()
getPairingState()
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 366 of file DBTDevice.java.

Here is the call graph for this function:

◆ getPairingState()

SMPPairingState jau.direct_bt.DBTDevice.getPairingState ( )

Returns the current SMPPairingState.

If the device is not paired, the current state is SMPPairingState#NONE.

See also
PairingMode
SMPPairingState
AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
setPairingPasskey(int)
setPairingNumericComparison(boolean)
getPairingMode()
getPairingState()
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 372 of file DBTDevice.java.

Here is the call graph for this function:

◆ getRSSI()

native short jau.direct_bt.DBTDevice.getRSSI ( )

Returns the Received Signal Strength Indicator of the device.

Returns
The Received Signal Strength Indicator of the device.

Implements org.direct_bt.BTDevice.

◆ getServices()

List<BTGattService> jau.direct_bt.DBTDevice.getServices ( )

Returns a list of BluetoothGattServices available on this device.

Returns
A list of BluetoothGattServices available on this device, NULL if an error occurred

Implements org.direct_bt.BTDevice.

Definition at line 410 of file DBTDevice.java.

Here is the call graph for this function:

◆ getSignatureResolvingKeyInfo()

final SMPSignatureResolvingKeyInfo jau.direct_bt.DBTDevice.getSignatureResolvingKeyInfo ( final boolean  responder)

Returns a copy of the Signature Resolving Key (LTK) info, valid after connection and SMP pairing has been completed.

Parameters
respondertrue will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).
Returns
the resulting key
See also
SMPPairingState#COMPLETED
AdapterStatusListener#deviceReady(BTDevice, long)
Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 278 of file DBTDevice.java.

◆ getTxPower()

native short jau.direct_bt.DBTDevice.getTxPower ( )

Returns the transmission power level (0 means unknown).

Returns
the transmission power level (0 means unknown).

Implements org.direct_bt.BTDevice.

◆ isConnSecurityAutoEnabled()

final native boolean jau.direct_bt.DBTDevice.isConnSecurityAutoEnabled ( )

Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false.

Since
2.2.0
See also
setConnSecurityAuto(SMPIOCapability)

Implements org.direct_bt.BTDevice.

◆ isValid()

final boolean jau.direct_bt.DBTDevice.isValid ( )

Returns whether the device is valid, i.e.

reference is valid but not necessarily connected.

Returns
true if this device's references are valid and hasn't been remove()'ed
See also
remove()
Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 406 of file DBTDevice.java.

Here is the caller graph for this function:

◆ pingGATT()

boolean jau.direct_bt.DBTDevice.pingGATT ( )

Issues a GATT ping to the device, validating whether it is still reachable.

This method could be periodically utilized to shorten the underlying OS disconnect period after turning the device off, which lies within 7-13s.

In case the device is no more reachable, disconnect will be initiated due to the occurring IO error.

GATT services must have been initialized via getServices(), otherwise

false

is being returned.

Returns
true
if successful or not implemented, otherwise false in case no GATT services exists or is not connected..
Since
2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 426 of file DBTDevice.java.

Here is the call graph for this function:

◆ remove()

final boolean jau.direct_bt.DBTDevice.remove ( ) throws BTException

Remove this device from the system (like an unpair).Direct-BT: Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared references from the Adapter: connected-devices, discovered-devices and shared-devices. This method shall be issued to ensure no device reference will be leaked in a long lived adapter, as only its reference within connected-devices and discovered-devices are removed at disconnect. After calling this method, this instance is destroyed and shall not be used anymore! This method is automatically called @ destructor. This method is an atomic operation. An application using one thread per device and rapid connect, should either use disconnect() or remove(), but never issue remove() after disconnect() if the device is in use.

Returns
TRUE if the device has been removed
Exceptions
BTException

Implements org.direct_bt.BTDevice.

Definition at line 392 of file DBTDevice.java.

Here is the call graph for this function:

◆ removeAllAssociatedCharListener()

native int jau.direct_bt.DBTDevice.removeAllAssociatedCharListener ( final BTGattChar  associatedCharacteristic)

Remove all BTGattCharListener from the list, which are associated to the given BTGattChar.

Implementation tests all listener's BTGattCharListener#getAssociatedChar() to match with the given associated characteristic.

Parameters
associatedCharacteristicthe match criteria to remove any BTGattCharListener from the list
Returns
number of removed listener.
Since
2.0.0

Implements org.direct_bt.BTDevice.

◆ removeAllCharListener()

native int jau.direct_bt.DBTDevice.removeAllCharListener ( )

Remove all BTGattCharListener from the list.

Returns
number of removed listener.
Since
2.0.0

Implements org.direct_bt.BTDevice.

◆ removeCharListener()

native boolean jau.direct_bt.DBTDevice.removeCharListener ( final BTGattCharListener  l)

Remove the given BTGattCharListener from the listener list.

If the BTDevice's BTGattHandler is null, i.e. not connected,

false

is being returned.

Parameters
listenerA BTGattCharListener 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.BTDevice.

◆ removeStatusListener()

boolean jau.direct_bt.DBTDevice.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.3.0

Implements org.direct_bt.BTDevice.

Definition at line 205 of file DBTDevice.java.

Here is the call graph for this function:

◆ setConnIOCapability()

final boolean jau.direct_bt.DBTDevice.setConnIOCapability ( final SMPIOCapability  io_cap)

Sets the given SMPIOCapability used to connect to this device on the upcoming connection.

Method returns false if SMPIOCapability#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

Parameters
io_capSMPIOCapability to be applied, SMPIOCapability#UNSET will be ignored and method fails.
Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
setConnSecurityLevel(BTSecurityLevel)
getConnSecurityLevel()
getConnIOCapability()
setConnSecurity(BTSecurityLevel, SMPIOCapability)
setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 304 of file DBTDevice.java.

Here is the caller graph for this function:

◆ setConnSecurity()

final boolean jau.direct_bt.DBTDevice.setConnSecurity ( final BTSecurityLevel  sec_level,
final SMPIOCapability  io_cap 
)

Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming connection.

Method returns false if this device has already being connected, or connectLE or connect() has been issued already.

Method either changes both parameter for the upcoming connection or none at all.

Parameters
sec_levelBTSecurityLevel to be applied.
io_capSMPIOCapability to be applied.
Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
setConnSecurityLevel(BTSecurityLevel)
getConnSecurityLevel()
setConnIOCapability(SMPIOCapability)
getConnIOCapability()
setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 316 of file DBTDevice.java.

Here is the caller graph for this function:

◆ setConnSecurityAuto()

final boolean jau.direct_bt.DBTDevice.setConnSecurityAuto ( final SMPIOCapability  iocap_auto)

Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode.

Disabled by default and if set to SMPIOCapability#UNSET

Implementation iterates through below setup from highest security to lowest, while performing a full connection attempt for each. 

BTSecurityLevel::ENC_AUTH_FIPS, iocap_auto*
BTSecurityLevel::ENC_AUTH,      iocap_auto*
BTSecurityLevel::ENC_ONLY,      SMPIOCapability::NO_INPUT_NO_OUTPUT
BTSecurityLevel::NONE,          SMPIOCapability::NO_INPUT_NO_OUTPUT
(*): user SMPIOCapability choice of for authentication IO, skipped if ::SMPIOCapability::NO_INPUT_NO_OUTPUT

<p<blockquote>

Implementation may perform multiple connection and disconnect actions until successful pairing or failure.

Intermediate deviceConnected(..) and deviceDisconnected(..) callbacks are not delivered while negotiating. This avoids any interference by the user application.

Parameters
auth_io_capuser SMPIOCapability choice for negotiation
Since
2.2.0
See also
isConnSecurityAutoEnabled()
BTSecurityLevel
SMPIOCapability

Implements org.direct_bt.BTDevice.

Definition at line 339 of file DBTDevice.java.

◆ setConnSecurityBest()

final boolean jau.direct_bt.DBTDevice.setConnSecurityBest ( final BTSecurityLevel  sec_level,
final SMPIOCapability  io_cap 
)

Convenience method to determine the best practice BTSecurityLevel and SMPIOCapability based on the given arguments, used to connect to this device on the upcoming connection. 

  if( BTSecurityLevel::UNSET < sec_level && SMPIOCapability::UNSET != io_cap ) {
     return setConnSecurity(sec_level, io_cap);
  } else if( BTSecurityLevel::UNSET < sec_level ) {
      if( BTSecurityLevel::ENC_ONLY >= sec_level ) {
          return setConnSecurity(sec_level, SMPIOCapability::NO_INPUT_NO_OUTPUT);
      } else {
          return setConnSecurityLevel(sec_level);
      }
  } else if( SMPIOCapability::UNSET != io_cap ) {
      return setConnIOCapability(io_cap);
  } else {
      return false;
  }

<p<blockquote>

Method returns false if BTSecurityLevel#UNSET and SMPIOCapability#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

Parameters
sec_levelBTSecurityLevel to be applied.
io_capSMPIOCapability to be applied.
Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
setConnSecurityLevel(BTSecurityLevel)
getConnSecurityLevel()
setConnIOCapability(SMPIOCapability)
getConnIOCapability()
setConnSecurity(BTSecurityLevel, SMPIOCapability)
setConnSecurityAuto(SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 322 of file DBTDevice.java.

Here is the call graph for this function:

◆ setConnSecurityLevel()

final boolean jau.direct_bt.DBTDevice.setConnSecurityLevel ( final BTSecurityLevel  sec_level)

Set the BTSecurityLevel used to connect to this device on the upcoming connection.

Method returns false if BTSecurityLevel#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

To ensure a consistent authentication setup, it is advised to set SMPIOCapability#NO_INPUT_NO_OUTPUT for sec_level <= BTSecurityLevel#ENC_ONLY using setConnSecurity(..) as well as an IO capable SMPIOCapability value for BTSecurityLevel#ENC_AUTH or BTSecurityLevel#ENC_AUTH_FIPS.
You may like to consider using setConnSecurityBest(BTSecurityLevel, SMPIOCapability).

Parameters
sec_levelBTSecurityLevel to be applied, BTSecurityLevel#UNSET will be ignored and method fails.
Returns
Since
2.1.0
See also
BTSecurityLevel
SMPIOCapability
getConnSecurityLevel()
setConnIOCapability(SMPIOCapability)
getConnIOCapability()
setConnSecurity(BTSecurityLevel, SMPIOCapability)
setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implements org.direct_bt.BTDevice.

Definition at line 292 of file DBTDevice.java.

Here is the caller graph for this function:

◆ setLongTermKeyInfo()

final HCIStatusCode jau.direct_bt.DBTDevice.setLongTermKeyInfo ( final SMPLongTermKeyInfo  ltk)

Sets the long term ket (LTK) info of this device to reuse pre-paired encryption.

Must be called before connecting to this device, otherwise HCIStatusCode#CONNECTION_ALREADY_EXISTS will be returned.

Parameters
ltkthe pre-paired encryption LTK
Returns
HCIStatusCode#SUCCESS if successful, otherwise the appropriate error code.
Since
2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 270 of file DBTDevice.java.

Here is the call graph for this function:

◆ setPairingNumericComparison()

HCIStatusCode jau.direct_bt.DBTDevice.setPairingNumericComparison ( final boolean  equal)

Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini.

Call this method if the device shall be securely paired with PairingMode#NUMERIC_COMPARE_ini, i.e. when notified via devicePairingState in state SMPPairingState#NUMERIC_COMPARE_EXPECTED.

Parameters
equalused for PairingMode#NUMERIC_COMPARE_ini method. Will be encrypted before sending to counter-party.
Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
See also
PairingMode
SMPPairingState
AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
setPairingPasskey(int)
setPairingNumericComparison(boolean)
getPairingMode()
getPairingState()
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 360 of file DBTDevice.java.

Here is the call graph for this function:

◆ setPairingPasskey()

HCIStatusCode jau.direct_bt.DBTDevice.setPairingPasskey ( final int  passkey)

Method sets the given passkey entry, see PairingMode#PASSKEY_ENTRY_ini.

Call this method if the device shall be securely paired with PairingMode#PASSKEY_ENTRY_ini, i.e. when notified via devicePairingState in state SMPPairingState#PASSKEY_EXPECTED.

Parameters
passkeyused for PairingMode#PASSKEY_ENTRY_ini method. Will be encrypted before sending to counter-party.
Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
See also
PairingMode
SMPPairingState
AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
setPairingPasskey(int)
setPairingNumericComparison(boolean)
getPairingMode()
getPairingState()
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 348 of file DBTDevice.java.

Here is the call graph for this function:

◆ setPairingPasskeyNegative()

HCIStatusCode jau.direct_bt.DBTDevice.setPairingPasskeyNegative ( )

Method replies with a negative passkey response, i.e.

rejection, see PairingMode#PASSKEY_ENTRY_ini.

You may call this method if the device shall be securely paired with PairingMode#PASSKEY_ENTRY_ini, i.e. when notified via devicePairingState in state SMPPairingState#PASSKEY_EXPECTED.

Current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.

Hence using setPairingPasskey(int) with

passkey = 0

is recommended, especially when utilizing automatic security negotiation via setConnSecurityAuto()!

Returns
HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
See also
PairingMode
SMPPairingState
AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long)
setPairingPasskey(int)
setPairingNumericComparison(boolean)
getPairingMode()
getPairingState()
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 354 of file DBTDevice.java.

Here is the call graph for this function:

◆ toString()

final String jau.direct_bt.DBTDevice.toString ( )

Definition at line 378 of file DBTDevice.java.

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

◆ unpair()

final HCIStatusCode jau.direct_bt.DBTDevice.unpair ( )

Unpairs this device from the adapter while staying connected.

All keys will be cleared within the adapter and host implementation.
Should rarely being used by user.
Internally being used to re-start pairing if GATT connection fails in PairingMode#PRE_PAIRED mode.

Returns
HCIStatusCode#SUCCESS or an appropriate error status.
Since
2.1.0

Implements org.direct_bt.BTDevice.

Definition at line 286 of file DBTDevice.java.

Here is the call 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
Generated on Wed Sep 1 2021 22:28:08 for Direct-BT by   doxygen 1.8.18