jau.direct_bt.DBTDevice Class Reference

Inheritance diagram for jau.direct_bt.DBTDevice:

Collaboration diagram for jau.direct_bt.DBTDevice:

Public Member Functions
boolean	addCharListener (final BTGattCharListener listener)
	Add the given BTGattCharListener to the listener list if not already present. More...
boolean	addCharListener (final BTGattCharListener listener, final BTGattChar associatedCharacteristic)
	Please use BTGattChar#addCharListener(BTGattCharListener) for clarity. 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...
void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...
final HCIStatusCode	connectDefault ()
	jau.direct_bt: Establish a default HCI connection to this device, using certain default parameter. More...
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 HCIStatusCode	disconnect ()
	jau.direct_bt: Disconnect the LE or BREDR peer's GATT and HCI connection. More...
boolean	equals (final Object obj)
BTGattChar	findGattChar (final String char_uuid)
	Find a BTGattChar by its char_uuid only. More...
BTGattChar	findGattChar (final String service_uuid, final String char_uuid)
	Find a BTGattChar by its service_uuid and char_uuid. More...
BTGattService	findGattService (final String service_uuid)
	Find a BTGattService by its service_uuid. More...
DBTAdapter	getAdapter ()
	Returns the adapter on which this device was discovered or connected. More...
BDAddressAndType	getAddressAndType ()
	Returns the devices' unique EUI48 address and BDAddressType type tuple, might be its initially reported (resolvable) random address until pairing, i.e. More...
final SMPKeyMask	getAvailableSMPKeys (final boolean responder)
	Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master). More...
final boolean	getConnected ()
	Returns the connected state of the device. More...
HCIStatusCode	getConnectedLE_PHY (final LE_PHYs[] resTx, final LE_PHYs[] resRx)
	Request and return LE_PHYs bit for the given connection. More...
final short	getConnectionHandle ()
	Return the HCI connection handle to the LE or BREDR peer, zero if not connected. More...
final SMPIOCapability	getConnIOCapability ()
	Return the SMPIOCapability value, determined when the connection is established. More...
final BTSecurityLevel	getConnSecurityLevel ()
	Return the BTSecurityLevel, determined when the connection is established. More...
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 EInfoReport	getEIR ()
	Return the merged advertised EInfoReport for this remote device. More...
EInfoReport	getEIRInd ()
	Return the latest advertised EInfoReport AD_IND variant for this remote device. More...
EInfoReport	getEIRScanRsp ()
	Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device. More...
List< BTGattService >	getGattServices ()
	Returns a complete list of shared BTGattService available on this device, initially retrieved via GATT discovery. More...
final SMPIdentityResolvingKey	getIdentityResolvingKey (final boolean responder)
	Returns a copy of the Identity Resolving Key (IRK), valid after connection and SMP pairing has been completed. 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...
final SMPLinkKey	getLinkKey (final boolean responder)
	Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed. More...
final SMPLongTermKey	getLongTermKey (final boolean responder)
	Returns a copy of the long term key (LTK), valid after connection and SMP pairing has been completed. More...
String	getName ()
	Returns the remote device name. More...
PairingMode	getPairingMode ()
	Returns the current PairingMode used by the device. More...
SMPPairingState	getPairingState ()
	Returns the current SMPPairingState. More...
native int	getResponderSMPPassKey ()
	Returns the responder SMP passkey, ranging from [0..999999]. More...
final String	getResponderSMPPassKeyString ()
	Returns getResponderSMPPassKey() as a canonical string, e.g. More...
final BTRole	getRole ()
	Return the fixed BTRole of this remote BTDevice. More...
native short	getRSSI ()
	Returns Received Signal Strength Indicator (RSSI) in dBm with ±6 dB accuracy of device as recognized at discovery and connect. More...
final LE_PHYs	getRxPhys ()
	Return the Rx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]). More...
final SMPSignatureResolvingKey	getSignatureResolvingKey (final boolean responder)
	Returns a copy of the Signature Resolving Key (CSRK), valid after connection and SMP pairing has been completed. More...
final LE_PHYs	getTxPhys ()
	Return the Tx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]). More...
native short	getTxPower ()
	Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect. More...
BDAddressAndType	getVisibleAddressAndType ()
	Returns the devices' visible BDAddressAndType, i.e. More...
final native boolean	isConnSecurityAutoEnabled ()
	Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false. More...
native boolean	isPrePaired ()
	Returns true if this device has completed SMP pairing or keys are set via uploadKeys() More...
final boolean	isValid ()
	Returns whether the device is valid, i.e. More...
boolean	pingGATT ()
	Issues a GATT ping to the device, validating whether it is still reachable. More...
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...
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...
native boolean	removeCharListener (final BTGattCharListener l)
	Remove the given BTGattCharListener from the listener list. More...
boolean	removeStatusListener (final AdapterStatusListener l)
	Remove the given AdapterStatusListener from the list. More...
native boolean	sendIndication (final short char_value_handle, final byte[] value)
	Send an indication event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master. More...
native boolean	sendNotification (final short char_value_handle, final byte[] value)
	Send a notification event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master. More...
HCIStatusCode	setConnectedLE_PHY (final LE_PHYs Tx, final LE_PHYs Rx)
	Sets preference of used LE_PHYs for the given connection. 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	setConnSecurityAuto (final SMPIOCapability iocap_auto)
	Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode. More...
final void	setIdentityResolvingKey (final SMPIdentityResolvingKey irk)
	Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption. More...
final void	setLinkKey (final SMPLinkKey lk)
	Sets the Link Key (LK) of this device for pre-paired encryption. More...
final void	setLongTermKey (final SMPLongTermKey ltk)
	Sets the Long Term Key (LTK) of this device for pre-paired encryption. More...
HCIStatusCode	setPairingNumericComparison (final boolean equal)
	Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini. 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...
final void	setSignatureResolvingKey (final SMPSignatureResolvingKey irk)
	Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption. More...
final boolean	setSMPKeyBin (final SMPKeyBin bin)
	Copy all keys from the given SMPKeyBin into this BTDevice. More...
final String	toString ()
final HCIStatusCode	unpair ()
	Unpair this device from the adapter while staying connected. More...
final HCIStatusCode	uploadKeys ()
	Upload all set keys to the adapter for pre-pairing. More...
final HCIStatusCode	uploadKeys (final SMPKeyBin bin, final BTSecurityLevel req_min_level)
	Convenient combination of setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level. More...
final HCIStatusCode	uploadKeys (final String smp_key_bin_path, final BTSecurityLevel req_min_level, final boolean verbose_)
	Convenient combination of SMPKeyBin::read(), setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level. More...
Public Member Functions inherited from jau.direct_bt.DBTObject
synchronized void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...
abstract boolean	equals (final Object obj)
final int	hashCode ()
Public Member Functions inherited from jau.direct_bt.DBTNativeDownlink
final void	delete ()
	Deletes the nativeInstance in the following order. 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 (Object obj)
int	hashCode ()
boolean	addCharListener (final BTGattCharListener listener)
	Add the given BTGattCharListener to the listener list if not already present. More...
boolean	addCharListener (final BTGattCharListener listener, final BTGattChar associatedCharacteristic)
	Please use BTGattChar#addCharListener(BTGattCharListener) for clarity. More...
boolean	addStatusListener (final AdapterStatusListener listener)
	Add the given AdapterStatusListener to the list if not already present, listening only for events matching this device. More...
HCIStatusCode	connectDefault () throws BTException
	jau.direct_bt: Establish a default HCI connection to this device, using certain default parameter. More...
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 supervision_timeout)
	Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device. More...
HCIStatusCode	disconnect () throws BTException
	jau.direct_bt: Disconnect the LE or BREDR peer's GATT and HCI connection. More...
boolean	equals (final Object obj)
	If both types are of BTDevice, it compares their BDAddressAndType, see getAddressAndType(). More...
BTGattChar	findGattChar (String char_uuid)
	Find a BTGattChar by its char_uuid only. More...
BTGattChar	findGattChar (String service_uuid, String char_uuid)
	Find a BTGattChar by its service_uuid and char_uuid. More...
BTGattService	findGattService (String service_uuid)
	Find a BTGattService by its service_uuid. More...
BTAdapter	getAdapter ()
	Returns the adapter on which this device was discovered or connected. More...
BDAddressAndType	getAddressAndType ()
	Returns the devices' unique EUI48 address and BDAddressType type tuple, might be its initially reported (resolvable) random address until pairing, i.e. More...
SMPKeyMask	getAvailableSMPKeys (final boolean responder)
	Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master). More...
boolean	getConnected ()
	Returns the connected state of the device. More...
HCIStatusCode	getConnectedLE_PHY (LE_PHYs[] resRx, LE_PHYs[] resTx)
	Request and return LE_PHYs bit for the given connection. More...
short	getConnectionHandle ()
	Return the HCI connection handle to the LE or BREDR peer, zero if not connected. More...
SMPIOCapability	getConnIOCapability ()
	Return the SMPIOCapability value, determined when the connection is established. More...
BTSecurityLevel	getConnSecurityLevel ()
	Return the BTSecurityLevel, determined when the connection is established. More...
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...
EInfoReport	getEIR ()
	Return the merged advertised EInfoReport for this remote device. More...
EInfoReport	getEIRInd ()
	Return the latest advertised EInfoReport AD_IND variant for this remote device. More...
EInfoReport	getEIRScanRsp ()
	Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device. More...
List< BTGattService >	getGattServices ()
	Returns a complete list of shared BTGattService available on this device, initially retrieved via GATT discovery. More...
SMPIdentityResolvingKey	getIdentityResolvingKey (final boolean responder)
	Returns a copy of the Identity Resolving Key (IRK), valid after connection and SMP pairing has been completed. More...
long	getLastDiscoveryTimestamp ()
	Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time. More...
long	getLastUpdateTimestamp ()
	Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time. More...
SMPLinkKey	getLinkKey (final boolean responder)
	Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed. More...
SMPLongTermKey	getLongTermKey (final boolean responder)
	Returns a copy of the long term key (LTK), valid after connection and SMP pairing has been completed. More...
String	getName ()
	Returns the remote device name. More...
PairingMode	getPairingMode ()
	Returns the current PairingMode used by the device. More...
SMPPairingState	getPairingState ()
	Returns the current SMPPairingState. More...
int	getResponderSMPPassKey ()
	Returns the responder SMP passkey, ranging from [0..999999]. More...
String	getResponderSMPPassKeyString ()
	Returns getResponderSMPPassKey() as a canonical string, e.g. More...
BTRole	getRole ()
	Return the fixed BTRole of this remote BTDevice. More...
short	getRSSI ()
	Returns Received Signal Strength Indicator (RSSI) in dBm with ±6 dB accuracy of device as recognized at discovery and connect. More...
LE_PHYs	getRxPhys ()
	Return the Rx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]). More...
SMPSignatureResolvingKey	getSignatureResolvingKey (final boolean responder)
	Returns a copy of the Signature Resolving Key (CSRK), valid after connection and SMP pairing has been completed. More...
LE_PHYs	getTxPhys ()
	Return the Tx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]). More...
short	getTxPower ()
	Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect. More...
BDAddressAndType	getVisibleAddressAndType ()
	Returns the devices' visible BDAddressAndType, i.e. More...
boolean	isConnSecurityAutoEnabled ()
	Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false. More...
boolean	isPrePaired ()
	Returns true if this device has completed SMP pairing or keys are set via uploadKeys() More...
boolean	isValid ()
	Returns whether the device is valid, i.e. More...
boolean	pingGATT ()
	Issues a GATT ping to the device, validating whether it is still reachable. More...
boolean	remove () throws BTException
	Remove this device from the system (like an unpair). More...
int	removeAllAssociatedCharListener (final BTGattChar associatedCharacteristic)
	Remove all BTGattCharListener from the list, which are associated to the given BTGattChar. More...
int	removeAllCharListener ()
	Remove all BTGattCharListener from the list. More...
boolean	removeCharListener (final BTGattCharListener l)
	Remove the given BTGattCharListener from the listener list. More...
boolean	removeStatusListener (final AdapterStatusListener l)
	Remove the given AdapterStatusListener from the list. More...
boolean	sendIndication (final short char_value_handle, final byte[] value)
	Send an indication event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master. More...
boolean	sendNotification (final short char_value_handle, final byte[] value)
	Send a notification event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master. More...
HCIStatusCode	setConnectedLE_PHY (final LE_PHYs Tx, final LE_PHYs Rx)
	Sets preference of used LE_PHYs for the given connection. More...
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...
boolean	setConnSecurityAuto (final SMPIOCapability iocap_auto)
	Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode. More...
void	setIdentityResolvingKey (final SMPIdentityResolvingKey irk)
	Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption. More...
void	setLinkKey (final SMPLinkKey lk)
	Sets the Link Key (LK) of this device for pre-paired encryption. More...
void	setLongTermKey (final SMPLongTermKey ltk)
	Sets the Long Term Key (LTK) of this device for pre-paired encryption. More...
HCIStatusCode	setPairingNumericComparison (final boolean equal)
	Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini. 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...
void	setSignatureResolvingKey (final SMPSignatureResolvingKey csrk)
	Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption. More...
boolean	setSMPKeyBin (final SMPKeyBin bin)
	Copy all keys from the given SMPKeyBin into this BTDevice. More...
String	toString ()
HCIStatusCode	unpair ()
	Unpair this device from the adapter while staying connected. More...
HCIStatusCode	uploadKeys ()
	Upload all set keys to the adapter for pre-pairing. More...
HCIStatusCode	uploadKeys (final SMPKeyBin bin, final BTSecurityLevel req_min_level)
	Convenient combination of setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level. More...
HCIStatusCode	uploadKeys (final String smp_key_bin_path, final BTSecurityLevel req_min_level, final boolean verbose_)
	Convenient combination of SMPKeyBin::read(), setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level. 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 nativeInstance copy 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 ()
	DBTNativeDownlink (final long nativeInstance)
abstract void	deleteImpl (long nativeInstance)
	Deletes the native instance. More...
void	finalize ()
final void	initDownlink (final long nativeInstance)
final boolean	isNativeValid ()
	Returns true if native instance is valid, otherwise false. More...

Detailed Description

Definition at line 60 of file DBTDevice.java.

Member Function Documentation

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 115 of file DBTDevice.java.

Here is the caller 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 132 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 135 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 138 of file DBTDevice.java.

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 141 of file DBTDevice.java.

Here is the caller graph for this function:

getRole()

final BTRole jau.direct_bt.DBTDevice.getRole

(

)

Return the fixed BTRole of this remote BTDevice.

See also

BTDeviceRoles

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 144 of file DBTDevice.java.

Here is the caller graph for this function:

equals()

boolean jau.direct_bt.DBTDevice.equals

(

final Object

obj

)

Reimplemented from jau.direct_bt.DBTObject.

Definition at line 150 of file DBTDevice.java.

getAddressAndType()

BDAddressAndType jau.direct_bt.DBTDevice.getAddressAndType

(

)

Returns the devices' unique EUI48 address and BDAddressType type tuple, might be its initially reported (resolvable) random address until pairing, i.e.

BDAddressType#BDADDR_LE_RANDOM instead of BDAddressType#BDADDR_LE_PUBLIC.

After pairing or if the remote device uses a (static) public address, it is considered unique and BDAddressType#BDADDR_LE_PUBLIC.

Since

3.2.0

Implements org.direct_bt.BTDevice.

Definition at line 164 of file DBTDevice.java.

Here is the caller graph for this function:

getVisibleAddressAndType()

BDAddressAndType jau.direct_bt.DBTDevice.getVisibleAddressAndType

(

)

Returns the devices' visible BDAddressAndType, i.e.

BDAddressType#BDADDR_LE_RANDOM or BDAddressType#BDADDR_LE_PUBLIC.

The devices' address as initially reported by the system might be a (resolvable) random address, i.e. BDAddressType#BDADDR_LE_RANDOM instead of BDAddressType#BDADDR_LE_PUBLIC.

Since

3.2.8

See also

getAddressAndType()

Implements org.direct_bt.BTDevice.

Definition at line 167 of file DBTDevice.java.

getName()

String jau.direct_bt.DBTDevice.getName

(

)

Returns the remote device name.

The name has been set by the advertised EInfoReport if available, otherwise by the GATT GenericAccess data post connection.

See also

getEIR()

Implements org.direct_bt.BTDevice.

Definition at line 170 of file DBTDevice.java.

findGattService()

BTGattService jau.direct_bt.DBTDevice.findGattService

(

final String

service_uuid

)

Find a BTGattService by its service_uuid.

It will check objects of this connected device.

It will not turn on discovery or connect to this remote device.

@parameter service_uuid the UUID of the desired BTGattService

Returns

The matching service or null if not found

Since

2.4.0

See also

findGattChar(String, String)

findGattChar(String)

Implements org.direct_bt.BTDevice.

Definition at line 182 of file DBTDevice.java.

Here is the caller graph for this function:

findGattChar() [1/2]

BTGattChar jau.direct_bt.DBTDevice.findGattChar	(	final String	service_uuid,
		final String	char_uuid
	)

Find a BTGattChar by its service_uuid and char_uuid.

It will check objects of this connected device.

It will not turn on discovery or connect to this remote device.

@parameter service_uuid the UUID of the intermediate BTGattService @parameter char_uuid the UUID of the desired BTGattChar, within the intermediate BTGattService.

Returns

The matching characteristic or null if not found

Since

2.4.0

See also

findGattChar(String)

findGattService(String)

Implements org.direct_bt.BTDevice.

Definition at line 202 of file DBTDevice.java.

findGattChar() [2/2]

BTGattChar jau.direct_bt.DBTDevice.findGattChar

(

final String

char_uuid

)

Find a BTGattChar by its char_uuid only.

It will check objects of this connected device.

It will not turn on discovery or connect to this remote device.

This variation is less efficient than findGattChar() by service_uuid and char_uuid, since it has to traverse through all services.

@parameter char_uuid the UUID of the desired BTGattChar, within the intermediate BTGattService.

Returns

The matching characteristic or null if not found

Since

2.4.0

See also

findGattChar(String, String)

findGattService(String)

Implements org.direct_bt.BTDevice.

Definition at line 211 of file DBTDevice.java.

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

listener	A AdapterStatusListener instance
deviceMatch	Optional 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 238 of file DBTDevice.java.

removeStatusListener()

boolean jau.direct_bt.DBTDevice.removeStatusListener

(

final AdapterStatusListener

l

)

Remove the given AdapterStatusListener from the list.

Parameters

listener

A 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 243 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 248 of file DBTDevice.java.

Here is the caller graph for this function:

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 251 of file DBTDevice.java.

getConnectedLE_PHY()

HCIStatusCode jau.direct_bt.DBTDevice.getConnectedLE_PHY	(	final LE_PHYs[]	resRx,
		final LE_PHYs[]	resTx
	)

Request and return LE_PHYs bit for the given connection.

BT Core Spec v5.2: Vol 4, Part E, 7.8.47 LE Read PHY command

Parameters

resRx	array for one resulting receiver LE_PHYs bit
resTx	array for one resulting transmitter LE_PHYs bit

Returns

HCIStatusCode

See also

getTxPhys()

getRxPhys()

getConnectedLE_PHY(LE_PHYs[], LE_PHYs[])

setConnectedLE_PHY(LE_PHYs, LE_PHYs)

BTAdapter::setDefaultLE_PHY(LE_PHYs, LE_PHYs)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 254 of file DBTDevice.java.

setConnectedLE_PHY()

HCIStatusCode jau.direct_bt.DBTDevice.setConnectedLE_PHY	(	final LE_PHYs	Tx,
		final LE_PHYs	Rx
	)

Sets preference of used LE_PHYs for the given connection.

BT Core Spec v5.2: Vol 4, Part E, 7.8.49 LE Set PHY command

Parameters

Tx	transmitter LE_PHYs bit mask of preference if not set to zero LE_PHYs#mask (ignored).
Rx	receiver LE_PHYs bit mask of preference if not set to zero LE_PHYs#mask (ignored).

Returns

See also

getTxPhys()

getRxPhys()

getConnectedLE_PHY(LE_PHYs[], LE_PHYs[])

BTAdapter::setDefaultLE_PHY(LE_PHYs, LE_PHYs)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 268 of file DBTDevice.java.

getTxPhys()

final LE_PHYs jau.direct_bt.DBTDevice.getTxPhys

(

)

Return the Tx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]).

See also

getTxPhys()

getRxPhys()

getConnectedLE_PHY(LE_PHYs[], LE_PHYs[])

setConnectedLE_PHY(LE_PHYs, LE_PHYs)

BTAdapter::setDefaultLE_PHY(LE_PHYs, LE_PHYs)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 274 of file DBTDevice.java.

getRxPhys()

final LE_PHYs jau.direct_bt.DBTDevice.getRxPhys

(

)

Return the Rx LE_PHYs as notified via LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]).

See also

getTxPhys()

getRxPhys()

getConnectedLE_PHY(LE_PHYs[], LE_PHYs[])

setConnectedLE_PHY(LE_PHYs, LE_PHYs)

BTAdapter::setDefaultLE_PHY(LE_PHYs, LE_PHYs)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 280 of file DBTDevice.java.

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 286 of file DBTDevice.java.

isPrePaired()

native boolean jau.direct_bt.DBTDevice.isPrePaired

(

)

Returns true if this device has completed SMP pairing or keys are set via uploadKeys()

See also

uploadKeys()

Since

3.2.3

Implements org.direct_bt.BTDevice.

getResponderSMPPassKey()

native int jau.direct_bt.DBTDevice.getResponderSMPPassKey

(

)

Returns the responder SMP passkey, ranging from [0..999999].

Authentication (MITM) PASSKEY (produced by this responder adapter, acting as peripheral GATT server) and shall be displayed for the initiating remote device, see PairingMode#PASSKEY_ENTRY_ini

See also

SMPPairingState::PASSKEY_NOTIFY

SMPPairingState::COMPLETED

AdapterStatusListener::deviceReady(BTDevice, long)

Implements org.direct_bt.BTDevice.

Here is the caller graph for this function:

getResponderSMPPassKeyString()

final String jau.direct_bt.DBTDevice.getResponderSMPPassKeyString

(

)

Returns getResponderSMPPassKey() as a canonical string, e.g.

'012345'.

Implements org.direct_bt.BTDevice.

Definition at line 301 of file DBTDevice.java.

connectDefault()

final HCIStatusCode jau.direct_bt.DBTDevice.connectDefault

(

)

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 306 of file DBTDevice.java.

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_interval	in units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_window	in 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_min	in units of 1.25ms, default value 8 for 10ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_interval_max	in units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_latency	slave latency in units of connection events, default value 0; Value range [0 .. 0x01F3].
supervision_timeout	in 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)

connectDefault()

Implements org.direct_bt.BTDevice.

Definition at line 315 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

responder

if true, queries the responder (LL slave) key, otherwise the initiator (LL master) key.

Returns

SMPKeyMask.KeyType SMPKeyMask result

See also

SMPPairingState#COMPLETED

AdapterStatusListener#deviceReady(BTDevice, long)

Since

2.2.0

Implements org.direct_bt.BTDevice.

Definition at line 337 of file DBTDevice.java.

setSMPKeyBin()

final boolean jau.direct_bt.DBTDevice.setSMPKeyBin

(

final SMPKeyBin

bin

)

Copy all keys from the given SMPKeyBin into this BTDevice.

Issue uploadKeys() to upload all SMP keys to the adapter before connecting to enable pre-pairing.

If this instance isValid() and initiator or responder LTK available, i.e. hasLTKInit() or hasLTKResp(), the following procedure will be applied to the given BTDevice:

• If BTSecurityLevel is BTSecurityLevel::NONE
  • Setting security to ::BTSecurityLevel::NONE and SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
• else if BTSecurityLevel > BTSecurityLevel::NONE
  • Setting security to ::BTSecurityLevel::ENC_ONLY and SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
• Copying all keys from SMPKeyBin to this device, without uploading to the adapter

BTSecurityLevel::ENC_ONLY is set to avoid a new SMP PairingMode negotiation, which is undesired as this instances' stored LTK shall be used for PairingMode::PRE_PAIRED.

Parameters

bin

Returns

true if successful, false if already connected (and pairing is currently in progress)

See also

setLongTermKey(SMPLongTermKey)

setIdentityResolvingKey(SMPIdentityResolvingKey)

setSignatureResolvingKey(SMPSignatureResolvingKey)

setLinkKey(SMPLinkKey)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 343 of file DBTDevice.java.

Here is the caller graph for this function:

uploadKeys() [1/3]

final HCIStatusCode jau.direct_bt.DBTDevice.uploadKeys

(

)

Upload all set keys to the adapter for pre-pairing.

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

Returns

HCIStatusCode#SUCCESS if successful, otherwise the appropriate error code.

See also

isPrePaired()

setLongTermKey(SMPLongTermKey)

setIdentityResolvingKey(SMPIdentityResolvingKey)

setSignatureResolvingKey(SMPSignatureResolvingKey)

setLinkKey(SMPLinkKey)

setSMPKeyBin(SMPKeyBin)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 446 of file DBTDevice.java.

Here is the caller graph for this function:

uploadKeys() [2/3]

final HCIStatusCode jau.direct_bt.DBTDevice.uploadKeys	(	final SMPKeyBin	bin,
		final BTSecurityLevel	req_min_level
	)

Convenient combination of setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level.

Parameters

bin	the SMPKeyBin file
req_min_level	SMPKeyBin::getSecLevel() shall be greater or equal to this required minimum

Returns

::HCIStatusCode::SUCCESS if successful, otherwise the appropriate error code.

See also

isPrePaired()

setSMPKeyBin(SMPKeyBin)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 452 of file DBTDevice.java.

uploadKeys() [3/3]

final HCIStatusCode jau.direct_bt.DBTDevice.uploadKeys	(	final String	smp_key_bin_path,
		final BTSecurityLevel	req_min_level,
		final boolean	verbose_
	)

Convenient combination of SMPKeyBin::read(), setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level.

Parameters

smp_key_bin_path	director for the SMPKeyBin file, derived by this BTDevice
req_min_level	SMPKeyBin::getSecLevel() shall be greater or equal to this required minimum

Returns

::HCIStatusCode::SUCCESS if successful, otherwise the appropriate error code.

See also

isPrePaired()

SMPKeyBin::read(String, BTDevice, boolean)

setSMPKeyBin(SMPKeyBin)

uploadKeys(SMPKeyBin, BTSecurityLevel)

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 461 of file DBTDevice.java.

getLongTermKey()

final SMPLongTermKey jau.direct_bt.DBTDevice.getLongTermKey

(

final boolean

responder

)

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

Parameters

responder

true will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).

Returns

the resulting key. SMPLongTermKey#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 467 of file DBTDevice.java.

setLongTermKey()

final void jau.direct_bt.DBTDevice.setLongTermKey

(

final SMPLongTermKey

ltk

)

Sets the Long Term Key (LTK) of this device for pre-paired encryption.

Issue uploadKeys() to upload all SMP keys to the adapter before connecting to enable pre-pairing.

Parameters

ltk	the pre-paired encryption LTK

See also

setSMPKeyBin(SMPKeyBin)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 475 of file DBTDevice.java.

Here is the caller graph for this function:

getIdentityResolvingKey()

final SMPIdentityResolvingKey jau.direct_bt.DBTDevice.getIdentityResolvingKey

(

final boolean

responder

)

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

Parameters

responder

true will return the responder's IRK info (remote device, LL slave), otherwise the initiator's (the LL master).

Returns

the resulting key

See also

::SMPPairingState::COMPLETED

AdapterStatusListener::deviceReady()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 483 of file DBTDevice.java.

setIdentityResolvingKey()

final void jau.direct_bt.DBTDevice.setIdentityResolvingKey

(

final SMPIdentityResolvingKey

irk

)

Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption.

Issue uploadKeys() to upload all SMP keys to the adapter before connecting to enable pre-pairing.

Parameters

irk	the Identity Resolving Key (IRK)

See also

setSMPKeyBin(SMPKeyBin)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 491 of file DBTDevice.java.

Here is the caller graph for this function:

getSignatureResolvingKey()

final SMPSignatureResolvingKey jau.direct_bt.DBTDevice.getSignatureResolvingKey

(

final boolean

responder

)

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

Parameters

responder

true will return the responder's CSRK 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 499 of file DBTDevice.java.

setSignatureResolvingKey()

final void jau.direct_bt.DBTDevice.setSignatureResolvingKey

(

final SMPSignatureResolvingKey

csrk

)

Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption.

Issue uploadKeys() to upload all SMP keys to the adapter before connecting to enable pre-pairing.

Parameters

csrk	the Signature Resolving Key (CSRK)

See also

setSMPKeyBin(SMPKeyBin)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 507 of file DBTDevice.java.

Here is the caller graph for this function:

getLinkKey()

final SMPLinkKey jau.direct_bt.DBTDevice.getLinkKey

(

final boolean

responder

)

Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed.

Parameters

responder

true 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.4.0

Implements org.direct_bt.BTDevice.

Definition at line 515 of file DBTDevice.java.

setLinkKey()

final void jau.direct_bt.DBTDevice.setLinkKey

(

final SMPLinkKey

lk

)

Sets the Link Key (LK) of this device for pre-paired encryption.

Issue uploadKeys() to upload all SMP keys to the adapter before connecting to enable pre-pairing.

Parameters

lk	the pre-paired encryption LK

See also

setSMPKeyBin(SMPKeyBin)

uploadKeys()

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 523 of file DBTDevice.java.

Here is the caller graph for this function:

unpair()

final HCIStatusCode jau.direct_bt.DBTDevice.unpair

(

)

Unpair 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.

Unpair is performed by directly for a consistent and stable security workflow:

• when a BTRole#Slave BTDevice is discovered, see AdapterStatusListener#deviceFound(BTDevice, long).
• when a BTRole#Slave BTDevice is disconnected, see AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, short, long).
• when a BTRole#Master BTDevice gets connected, see AdapterStatusListener#deviceConnected(BTDevice, short, long).

Returns

HCIStatusCode#SUCCESS or an appropriate error status.

Since

2.1.0

See also

AdapterStatusListener::deviceFound(BTDevice, long)

AdapterStatusListener::deviceDisconnected(BTDevice, HCIStatusCode, short, long)

AdapterStatusListener::deviceConnected(BTDevice, short, long)

Implements org.direct_bt.BTDevice.

Definition at line 531 of file DBTDevice.java.

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 537 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 543 of file DBTDevice.java.

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.

Implementation using following pseudo-code, validating the user settings:

  if( BTSecurityLevel::UNSET < sec_level && SMPIOCapability::UNSET != io_cap ) {
     USING: sec_level, io_cap
  } else if( BTSecurityLevel::UNSET < sec_level ) {
      if( BTSecurityLevel::ENC_ONLY >= sec_level ) {
          USING: sec_level, SMPIOCapability::NO_INPUT_NO_OUTPUT
      } else {
          USING: sec_level, SMPIOCapability::UNSET
      }
  } else if( SMPIOCapability::UNSET != io_cap ) {
      USING BTSecurityLevel::UNSET, io_cap
  } else {
      USING BTSecurityLevel::UNSET, SMPIOCapability::UNSET
  }

<p<blockquote>‍

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

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

Parameters

sec_level	BTSecurityLevel to be applied.
io_cap	SMPIOCapability 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 549 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_cap

user SMPIOCapability choice for negotiation

Since

2.2.0

See also

isConnSecurityAutoEnabled()

BTSecurityLevel

SMPIOCapability

Implements org.direct_bt.BTDevice.

Definition at line 555 of file DBTDevice.java.

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.

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

passkey

used 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 564 of file DBTDevice.java.

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 570 of file DBTDevice.java.

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

equal

used 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 576 of file DBTDevice.java.

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 582 of file DBTDevice.java.

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 588 of file DBTDevice.java.

toString()

final String jau.direct_bt.DBTDevice.toString

(

)

Implements org.direct_bt.BTDevice.

Definition at line 594 of file DBTDevice.java.

Here is the caller 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 608 of file DBTDevice.java.

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 622 of file DBTDevice.java.

Here is the caller graph for this function:

getGattServices()

List< BTGattService > jau.direct_bt.DBTDevice.getGattServices

(

)

Returns a complete list of shared BTGattService available on this device, initially retrieved via GATT discovery.

In case of transmission error, zero services or no GATT GenericAccess, method will return zero services indicating an error. In this case, user can assume that the connection is or will be disconnected.

Method is only functional on a remote BTDevice in BTRole#Slave, a GATT server, i.e. the local BTAdapter acting as a BTRole#Master GATT client.

The HCI connectLE(..) or connectBREDR(..) must be performed first, see connectDefault().

If this method has been called for the first time:

• the client MTU exchange will be performed
• a complete list of BTGattService inclusive their BTGattChar and BTGattDesc will be retrieved
• the GATT GenericAccess is extracted from the services.

Since

2.4.0

Implements org.direct_bt.BTDevice.

Definition at line 626 of file DBTDevice.java.

sendNotification()

native boolean jau.direct_bt.DBTDevice.sendNotification	(	final short	char_value_handle,
		final byte[]	value
	)

Send a notification event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master.

This command is only valid if this BTGattHandler is in role GATTRole::Server.

Implementation is not receiving any reply after sending out the indication and returns immediately.

Parameters

char_value_handle	valid characteristic value handle, must be sourced from referenced DBGattServer
value	the octets to be send

Returns

true if successful, otherwise false

Implements org.direct_bt.BTDevice.

sendIndication()

native boolean jau.direct_bt.DBTDevice.sendIndication	(	final short	char_value_handle,
		final byte[]	value
	)

Send an indication event consisting out of the given value representing the given characteristic value handle to the connected BTRole::Master.

This command is only valid if this BTGattHandler is in role GATTRole::Server.

Implementation awaits the indication reply after sending out the indication.

Parameters

char_value_handle	valid characteristic value handle, must be sourced from referenced DBGattServer
value	the octets to be send

Returns

true if successful, otherwise false

Implements org.direct_bt.BTDevice.

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 651 of file DBTDevice.java.

getRSSI()

native short jau.direct_bt.DBTDevice.getRSSI

(

)

Returns Received Signal Strength Indicator (RSSI) in dBm with ±6 dB accuracy of device as recognized at discovery and connect.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.5.4 Read RSSI command

Any positive RSSI value indicates how many dB the RSSI is above the upper limit, any negative value indicates how many dB the RSSI is below the lower limit. The value zero indicates that the RSSI is inside the Golden Receive Power Range.

LE range [-127..20] with 0 inside the Golden Receive Power Range and 127 as "not available" value (core spec).

pathloss = Tx Power Level – RSSI

See also

getTxPower()

Implements org.direct_bt.BTDevice.

getEIR()

final EInfoReport jau.direct_bt.DBTDevice.getEIR

(

)

Return the merged advertised EInfoReport for this remote device.

The EInfoReport is updated by new scan-reports (update) and when disconnected (empty).

Since

2.5.3

Implements org.direct_bt.BTDevice.

Definition at line 670 of file DBTDevice.java.

getEIRInd()

EInfoReport jau.direct_bt.DBTDevice.getEIRInd

(

)

Return the latest advertised EInfoReport AD_IND variant for this remote device.

The EInfoReport is replaced by new scan-reports only.

Since

2.6.6

Implements org.direct_bt.BTDevice.

Definition at line 679 of file DBTDevice.java.

getEIRScanRsp()

EInfoReport jau.direct_bt.DBTDevice.getEIRScanRsp

(

)

Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device.

The EInfoReport is replaced by new scan-reports only.

Since

2.6.6

Implements org.direct_bt.BTDevice.

Definition at line 688 of file DBTDevice.java.

getTxPower()

native short jau.direct_bt.DBTDevice.getTxPower

(

)

Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect.

Core Specification Supplement, Part A, Section 1.5.

Range [-127..20] with 127 as "not available" value (core spec).

pathloss = Tx Power Level – RSSI

See also

getRSSI()

Implements org.direct_bt.BTDevice.

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

nativeInstance

copy of nativeInstance reference, which has been already zeroed.

Native implementation calls DBTDevice::remove()

Reimplemented from jau.direct_bt.DBTNativeDownlink.

addCharListener() [1/2]

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

listener

A 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.

See also

BTGattChar::configNotificationIndication(boolean, boolean, boolean[])

BTGattChar::enableNotificationOrIndication(boolean[])

Since

2.0.0

Implements org.direct_bt.BTDevice.

Definition at line 709 of file DBTDevice.java.

addCharListener() [2/2]

boolean jau.direct_bt.DBTDevice.addCharListener	(	final BTGattCharListener	listener,
		final BTGattChar	associatedCharacteristic
	)

Please use BTGattChar#addCharListener(BTGattCharListener) for clarity.

Implements org.direct_bt.BTDevice.

Definition at line 714 of file DBTDevice.java.

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

listener

A 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.

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

associatedCharacteristic

the 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.

---

The documentation for this class was generated from the following file:

• java/jau/direct_bt/DBTDevice.java