BTDevice represents one remote Bluetooth device. More...

#include <BTDevice.hpp>

Inheritance diagram for direct_bt::BTDevice:

Collaboration diagram for direct_bt::BTDevice:

Public Types
typedef jau::darray< BTGattServiceRef, size_type >	GattServiceList_t

typedef jau::nsize_t	size_type

typedef jau::snsize_t	ssize_type

Public Member Functions
	BTDevice (const BTDevice &)=delete

	BTDevice (const BTDevice::ctor_cookie &cc, BTAdapter &adapter, EInfoReport const &r)
	Private ctor for private BTDevice::make_shared() intended for friends. More...

	~BTDevice () noexcept override
	Releases this instance after calling `remove()`. More...

bool	addCharListener (const BTGattCharListenerRef &l) noexcept
	Add the given BTGattCharListener to the listener list if not already present. More...

bool	addCharListener (const BTGattCharListenerRef &l, const BTGattCharRef &d) noexcept
	Please use BTGattChar::addCharListener() for clarity, merely existing here to allow JNI access. More...

bool	addStatusListener (const AdapterStatusListenerRef &l) noexcept
	Add the given AdapterStatusListener to the list if not already present, intended to listen only for events matching this device. More...

HCIStatusCode	connectBREDR (const uint16_t pkt_type=HCI_DM1\|HCI_DM3\|HCI_DM5\|HCI_DH1\|HCI_DH3\|HCI_DH5, const uint16_t clock_offset=0x0000, const uint8_t role_switch=0x01) noexcept
	Establish a HCI BDADDR_BREDR connection to this device. More...

HCIStatusCode	connectDefault () noexcept
	Establish a default HCI connection to this device, using certain default parameter. More...

HCIStatusCode	connectLE (const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24, const uint16_t conn_interval_min=8, const uint16_t conn_interval_max=12, const uint16_t conn_latency=0, const uint16_t conn_supervision_timeout=getHCIConnSupervisorTimeout(0, 15)) noexcept
	Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device. More...

HCIStatusCode	disconnect (const HCIStatusCode reason=HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION) noexcept
	Disconnect the LE or BREDR peer's GATT and HCI connection. More...

BTGattCharRef	findGattChar (const jau::uuid_t &char_uuid) noexcept
	Find a BTGattChar by its char_uuid only. More...

BTGattCharRef	findGattChar (const jau::uuid_t &service_uuid, const jau::uuid_t &char_uuid) noexcept
	Find a BTGattChar by its service_uuid and char_uuid. More...

BTGattServiceRef	findGattService (const jau::uuid_t &service_uuid) noexcept
	Find a BTGattService by its service_uuid. More...

std::string	get_java_class () const noexcept override

BTAdapter &	getAdapter () const
	Returns the managing adapter. More...

constexpr BDAddressAndType const &	getAddressAndType () const noexcept
	Returns the devices' unique EUI48 address and type tuple, might be its initially reported (resolvable) random address until pairing, i.e. More...

SMPKeyType	getAvailableSMPKeys (const bool responder) const noexcept
	Returns the available SMPKeyType mask for the responder (LL slave) or initiator (LL master). More...

bool	getConnected () noexcept
	Return true if the device has been successfully connected, otherwise false. More...

HCIStatusCode	getConnectedLE_PHY (LE_PHYs &resTx, LE_PHYs &resRx) noexcept
	Request and return LE_PHYs bit for the given connection. More...

uint16_t	getConnectionHandle () const noexcept
	Return the HCI connection handle to the LE or BREDR peer, zero if not connected. More...

std::shared_ptr< ConnectionInfo >	getConnectionInfo () noexcept
	Retrieves the current connection info for this device and returns the ConnectionInfo reference if successful, otherwise returns nullptr. More...

SMPIOCapability	getConnIOCapability () const noexcept
	Return the set SMPIOCapability value, determined when the connection is established. More...

BTSecurityLevel	getConnSecurityLevel () const noexcept
	Return the BTSecurityLevel, determined when the connection is established. More...

uint64_t	getCreationTimestamp () const noexcept
	Returns the timestamp in monotonic milliseconds when this device instance has been created, either via its initial discovery or its initial direct connection. More...

EInfoReportRef	getEIR () noexcept
	Return the merged advertised EInfoReport for this remote device. More...

EInfoReportRef	getEIRInd () noexcept
	Return the latest advertised EInfoReport AD_IND variant for this remote device. More...

EInfoReportRef	getEIRScanRsp () noexcept
	Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device. More...

std::shared_ptr< GattGenericAccessSvc >	getGattGenericAccess ()
	Returns the shared GenericAccess instance, retrieved by getGattServices() or nullptr if not available. More...

std::shared_ptr< BTGattHandler >	getGattHandler () noexcept
	Returns the connected GATTHandler or nullptr, see connectGATT(), getGattServices() and disconnect(). More...

GattServiceList_t	getGattServices () noexcept
	Returns a complete list of shared BTGattService available on this device, initially retrieved via GATT discovery. More...

SMPIdentityResolvingKey	getIdentityResolvingKey (const bool responder) const noexcept
	Returns a copy of the Identity Resolving Key (IRK), valid after connection and SMP pairing has been completed. More...

uint64_t	getLastDiscoveryTimestamp () const noexcept
	Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time. More...

uint64_t	getLastUpdateAge (const uint64_t ts_now) const noexcept

uint64_t	getLastUpdateTimestamp () const noexcept
	Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time. More...

SMPLinkKey	getLinkKey (const bool responder) const noexcept
	Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed. More...

GATTRole	getLocalGATTRole () const noexcept
	Return the local GATTRole operating for the remote BTDevice. More...

SMPLongTermKey	getLongTermKey (const bool responder) const noexcept
	Returns a copy of the Long Term Key (LTK), valid after connection and SMP pairing has been completed. More...

std::string const	getName () const noexcept
	Returns the remote device name. More...

PairingMode	getPairingMode () const noexcept
	Returns the current PairingMode used by the device. More...

SMPPairingState	getPairingState () const noexcept
	Returns the current SMPPairingState. More...

std::uint32_t	getResponderSMPPassKey () const noexcept
	Returns the responder SMP passkey, ranging from [0..999999]. More...

std::string	getResponderSMPPassKeyString () const noexcept
	Returns getResponderSMPPassKey() as a canonical string, e.g. More...

BTRole	getRole () const noexcept
	Return the fixed BTRole of this remote BTDevice. More...

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

LE_PHYs	getRxPhys () const noexcept
	Return the Rx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY() More...

std::shared_ptr< BTDevice >	getSharedInstance () const noexcept
	Returns the shared pointer of this instance managed by the adapter. More...

SMPSignatureResolvingKey	getSignatureResolvingKey (const bool responder) const noexcept
	Returns a copy of the Signature Resolving Key (CSRK), valid after connection and SMP pairing has been completed. More...

LE_PHYs	getTxPhys () const noexcept
	Return the Tx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY() More...

int8_t	getTxPower () const noexcept
	Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect. More...

BDAddressAndType const &	getVisibleAddressAndType () const noexcept
	Returns the devices' visible BDAddressAndType, i.e. More...

bool	isConnSecurityAutoEnabled () const noexcept
	Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(), otherwise false. More...

bool	isPrePaired () const noexcept
	Returns true if this device has completed SMP pairing or keys are set via uploadKeys() More...

bool	matches_irk (const BDAddressAndType &rpa) noexcept
	Returns true if this remote device's IRK matches the given random private address (rpa) More...

void	operator= (const BTDevice &)=delete

bool	pingGATT () noexcept
	Issues a GATT ping to the device, validating whether it is still reachable. More...

void	remove () noexcept
	Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared references from the Adapter: connected-devices, discovered-devices and shared-devices. More...

size_type	removeAllAssociatedCharListener (const BTGattChar *associatedCharacteristic) noexcept

size_type	removeAllAssociatedCharListener (const BTGattCharRef &associatedCharacteristic) noexcept
	Remove all `BTGattCharListener` from the list, which are associated to the given `BTGattChar`. More...

size_type	removeAllCharListener () noexcept
	Remove all `BTGattCharListener` from the list. More...

bool	removeCharListener (const BTGattCharListenerRef &l) noexcept
	Remove the given `BTGattCharListener` from the listener list. More...

bool	removeStatusListener (const AdapterStatusListenerRef &l) noexcept
	Remove the given listener from the list. More...

bool	sendIndication (const uint16_t char_value_handle, const jau::TROOctets &value) noexcept
	Send an indication event consisting out of the given `value` representing the given characteristic value handle to the connected BTRole::Master. More...

bool	sendNotification (const uint16_t char_value_handle, const jau::TROOctets &value) noexcept
	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 (const LE_PHYs Tx, const LE_PHYs Rx) noexcept
	Sets preference of used LE_PHYs for the given connection. More...

bool	setConnSecurity (const BTSecurityLevel sec_level, const SMPIOCapability io_cap=SMPIOCapability::UNSET) noexcept
	Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming connection. More...

bool	setConnSecurityAuto (const SMPIOCapability iocap_auto) noexcept
	Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode. More...

void	setIdentityResolvingKey (const SMPIdentityResolvingKey &irk) noexcept
	Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption. More...

void	setLinkKey (const SMPLinkKey &lk) noexcept
	Sets the Link Key (LK) of this device for pre-paired encryption. More...

void	setLongTermKey (const SMPLongTermKey &ltk) noexcept
	Sets the Long Term Key (LTK) of this device for pre-paired encryption. More...

HCIStatusCode	setPairingNumericComparison (const bool equal) noexcept
	Method sets the numeric comparison result, see PairingMode::NUMERIC_COMPARE_ini. More...

HCIStatusCode	setPairingPasskey (const uint32_t passkey) noexcept
	Method sets the given passkey entry, see PairingMode::PASSKEY_ENTRY_ini. More...

HCIStatusCode	setPairingPasskeyNegative () noexcept
	Method replies with a negative passkey response, i.e. More...

HCIStatusCode	setPairingPINCode (const std::string &pinCode) noexcept

HCIStatusCode	setPairingPINCodeNegative () noexcept

void	setSignatureResolvingKey (const SMPSignatureResolvingKey &csrk) noexcept
	Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption. More...

bool	setSMPKeyBin (const SMPKeyBin &bin) noexcept
	Copy all keys from the given SMPKeyBin into this BTDevice. More...

std::string	toString () const noexcept override

std::string	toString (bool includeDiscoveredServices) const noexcept

HCIStatusCode	unpair () noexcept
	Unpair this device from the adapter while staying connected. More...

HCIStatusCode	uploadKeys () noexcept
	Upload all set keys to the adapter for pre-pairing. More...

HCIStatusCode	uploadKeys (const SMPKeyBin &bin, const BTSecurityLevel req_min_level) noexcept
	Convenient combination of setSMPKeyBin() and uploadKeys() after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level. More...

HCIStatusCode	uploadKeys (const std::string &smp_key_bin_path, const BTSecurityLevel req_min_level, const bool verbose_) noexcept
	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 direct_bt::BTObject
	~BTObject () noexcept override

void	checkValidInstance () const override
	Throws an IllegalStateException if instance is not valid. More...

bool	isValidInstance () const noexcept
	Returns whether the object's reference is valid and in a general operational state. More...

std::string	toString () const noexcept override

Public Member Functions inherited from jau::jni::JavaUplink
	JavaUplink () noexcept=default

	JavaUplink (const JavaUplink &o) noexcept=default

	JavaUplink (JavaUplink &&o) noexcept=default

virtual	~JavaUplink () noexcept

virtual void	checkValidInstance () const
	Throws an IllegalStateException if instance is not valid. More...

virtual std::string	get_java_class () const noexcept=0

const JavaAnonRef &	getJavaObject () noexcept

std::string	javaObjectToString () const noexcept

JavaUplink &	operator= (const JavaUplink &o) noexcept=default

JavaUplink &	operator= (JavaUplink &&o) noexcept=default

void	setJavaObject () noexcept
	Resets the shared JavaAnon reference, the replaced item might be deleted via JNI from dtor. More...

void	setJavaObject (const JavaAnonRef &objRef) noexcept
	Assigns a new shared JavaAnon reference, replaced item might be deleted via JNI from dtor. More...

virtual std::string	toString () const noexcept

Static Public Member Functions
static std::string	java_class () noexcept

static void	validateSecParam (const BTSecurityLevel sec_level, const SMPIOCapability io_cap, BTSecurityLevel &res_sec_level, SMPIOCapability &res_io_cap) noexcept
	Returns the validated security parameter BTSecurityLevel and SMPIOCapability in the designated references. More...

Public Attributes
BDAddressAndType	addressAndType
	Device's unique mac address and type tuple, might be its initially reported (resolvable) random address until pairing. More...

const uint64_t	ts_creation

BDAddressAndType	visibleAddressAndType
	Either the remote devices' initially reported (resolvable) random address or its (static) public identity address. More...

Additional Inherited Members
Protected Member Functions inherited from direct_bt::BTObject
	BTObject () noexcept

Protected Attributes inherited from direct_bt::BTObject
std::atomic_bool	instance_valid

Detailed Description

BTDevice represents one remote Bluetooth device.

Invariable remote BTDevice roles (see getRole()):

BTRole::Master: The remote device has discovered us and maybe is connected to us. The remote device acts as a GATTRole::Client.
BTRole::Slave: The remote device has advertised and maybe we are connected to it. The remote device acts as a GATTRole::Server.

Note the local BTAdapter's opposite role.

See also: BTAdapter; BTAdapter roles.; BTGattHandler roles.; Bluetooth Specification; Direct-BT Overview

Definition at line 80 of file BTDevice.hpp.

Member Typedef Documentation

◆ size_type

typedef jau::nsize_t direct_bt::BTDevice::size_type

Definition at line 304 of file BTDevice.hpp.

◆ ssize_type

typedef jau::snsize_t direct_bt::BTDevice::ssize_type

Definition at line 305 of file BTDevice.hpp.

◆ GattServiceList_t

typedef jau::darray<BTGattServiceRef, size_type> direct_bt::BTDevice::GattServiceList_t

Definition at line 1164 of file BTDevice.hpp.

Constructor & Destructor Documentation

◆ BTDevice() [1/2]

BTDevice::BTDevice	(	const BTDevice::ctor_cookie &	cc,
		BTAdapter &	adapter,
		EInfoReport const &	r
	)

Private ctor for private BTDevice::make_shared() intended for friends.

Definition at line 46 of file BTDevice.cpp.

◆ BTDevice() [2/2]

direct_bt::BTDevice::BTDevice ( const BTDevice & )

delete

◆ ~BTDevice()

BTDevice::~BTDevice ( )

overridenoexcept

Releases this instance after calling remove().

Definition at line 94 of file BTDevice.cpp.

Member Function Documentation

◆ validateSecParam()

void BTDevice::validateSecParam	(	const BTSecurityLevel	sec_level,
		const SMPIOCapability	io_cap,
		BTSecurityLevel &	res_sec_level,
		SMPIOCapability &	res_io_cap
	)

staticnoexcept

Returns the validated security parameter BTSecurityLevel and SMPIOCapability in the designated references.

Validation is performed as follows:

 if( BTSecurityLevel::UNSET < sec_level ) {
     if( BTSecurityLevel::NONE == sec_level ||
         BTSecurityLevel::ENC_ONLY == sec_level )
     {
         // No authentication, maybe encryption
         res_sec_level = sec_level;
         res_io_cap = SMPIOCapability::NO_INPUT_NO_OUTPUT;
     } else if( hasSMPIOCapabilityAnyIO( io_cap ) ) {
         // Authentication w/ IO
         res_sec_level = sec_level;
         res_io_cap = io_cap;
     } else if( SMPIOCapability::NO_INPUT_NO_OUTPUT == io_cap ) {
         // Fall back: auto -> encryption only
         res_sec_level = BTSecurityLevel::ENC_ONLY;
         res_io_cap = SMPIOCapability::NO_INPUT_NO_OUTPUT;
     } else {
         // Use auth w/ SMPIOCapability::UNSET
         res_sec_level = sec_level;
         res_io_cap = io_cap;
     }
 } else {
     res_sec_level = BTSecurityLevel::UNSET;
     res_io_cap = io_cap;
 }

Parameters

sec_level	user value
io_cap	user value
res_sec_level	validated return value
res_io_cap	validated return value

Definition at line 1864 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ operator=()

void direct_bt::BTDevice::operator= ( const BTDevice & )

delete

◆ get_java_class()

std::string direct_bt::BTDevice::get_java_class ( ) const

inlineoverridevirtualnoexcept

Implements jau::jni::JavaUplink.

Definition at line 324 of file BTDevice.hpp.

◆ java_class()

static std::string direct_bt::BTDevice::java_class ( )

inlinestaticnoexcept

Definition at line 327 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getAdapter()

BTAdapter & direct_bt::BTDevice::getAdapter ( ) const

inline

Returns the managing adapter.

Definition at line 332 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getSharedInstance()

std::shared_ptr< BTDevice > BTDevice::getSharedInstance ( ) const

noexcept

Returns the shared pointer of this instance managed by the adapter.

Definition at line 100 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getRole()

BTRole direct_bt::BTDevice::getRole ( ) const

inlinenoexcept

Return the fixed BTRole of this remote BTDevice.

See also: BTRole; BTDeviceRoles

Since: 2.4.0

Definition at line 343 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getLocalGATTRole()

GATTRole BTDevice::getLocalGATTRole ( ) const

noexcept

Return the local GATTRole operating for the remote BTDevice.

See also: BTGattHandlerRoles; BTDeviceRoles

Since: 2.4.0

Definition at line 104 of file BTDevice.cpp.

◆ getCreationTimestamp()

uint64_t direct_bt::BTDevice::getCreationTimestamp ( ) const

inlinenoexcept

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: BasicTypes::getCurrentMilliseconds()

Definition at line 358 of file BTDevice.hpp.

◆ getLastDiscoveryTimestamp()

uint64_t direct_bt::BTDevice::getLastDiscoveryTimestamp ( ) const

inlinenoexcept

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

See also: BasicTypes::getCurrentMilliseconds()

Definition at line 365 of file BTDevice.hpp.

◆ getLastUpdateTimestamp()

uint64_t direct_bt::BTDevice::getLastUpdateTimestamp ( ) const

inlinenoexcept

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

See also: BasicTypes::getCurrentMilliseconds()

Definition at line 372 of file BTDevice.hpp.

◆ getLastUpdateAge()

uint64_t direct_bt::BTDevice::getLastUpdateAge ( const uint64_t ts_now ) const

inlinenoexcept

See also: getLastUpdateTimestamp()

Definition at line 377 of file BTDevice.hpp.

◆ getAddressAndType()

constexpr BDAddressAndType const & direct_bt::BTDevice::getAddressAndType ( ) const

inlineconstexprnoexcept

Returns the devices' unique EUI48 address and 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

Definition at line 388 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getVisibleAddressAndType()

BDAddressAndType const & direct_bt::BTDevice::getVisibleAddressAndType ( ) const

inlinenoexcept

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()

Definition at line 399 of file BTDevice.hpp.

◆ getRSSI()

int8_t direct_bt::BTDevice::getRSSI ( ) const

inlinenoexcept

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()

Definition at line 421 of file BTDevice.hpp.

◆ getTxPower()

int8_t direct_bt::BTDevice::getTxPower ( ) const

inlinenoexcept

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()

Definition at line 436 of file BTDevice.hpp.

◆ getName()

std::string const BTDevice::getName ( ) const

noexcept

Returns the remote device name.

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

Definition at line 112 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getEIR()

EInfoReportRef BTDevice::getEIR ( )

noexcept

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

Definition at line 118 of file BTDevice.cpp.

◆ getEIRInd()

EInfoReportRef BTDevice::getEIRInd ( )

noexcept

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

Definition at line 123 of file BTDevice.cpp.

◆ getEIRScanRsp()

EInfoReportRef BTDevice::getEIRScanRsp ( )

noexcept

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

Definition at line 128 of file BTDevice.cpp.

◆ toString() [1/2]

std::string direct_bt::BTDevice::toString ( ) const

inlineoverridevirtualnoexcept

Reimplemented from jau::jni::JavaUplink.

Definition at line 470 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ toString() [2/2]

std::string BTDevice::toString ( bool includeDiscoveredServices ) const

noexcept

Definition at line 133 of file BTDevice.cpp.

◆ addStatusListener()

bool BTDevice::addStatusListener ( const AdapterStatusListenerRef & l )

noexcept

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

User needs to implement AdapterStatusListener::matchDevice() for the latter.

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

Returns true if the given listener is not element of the list and has been newly added, otherwise false.

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

Since: 2.3.0

See also: BTAdapter::addStatusListener(); BTAdapter::removeStatusListener(); BTAdapter::removeAllStatusListener(); removeStatusListener()

Definition at line 286 of file BTDevice.cpp.

◆ removeStatusListener()

bool BTDevice::removeStatusListener ( const AdapterStatusListenerRef & l )

noexcept

Remove the given listener from the list.

Returns true if the given listener is an element of the list and has been removed, otherwise false.

Since: 2.3.0

See also: BTAdapter::removeStatusListener(); BTAdapter::removeStatusListener(); BTAdapter::removeAllStatusListener(); addStatusListener()

Definition at line 290 of file BTDevice.cpp.

◆ getConnectionInfo()

std::shared_ptr< ConnectionInfo > BTDevice::getConnectionInfo ( )

noexcept

Retrieves the current connection info for this device and returns the ConnectionInfo reference if successful, otherwise returns nullptr.

Before this method returns, the internal rssi and tx_power will be updated if any changed and therefore all BTAdapterStatusListener's deviceUpdated(..) method called for notification.

Definition at line 294 of file BTDevice.cpp.

◆ getConnected()

bool direct_bt::BTDevice::getConnected ( )

inlinenoexcept

Return true if the device has been successfully connected, otherwise false.

Definition at line 526 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ connectLE()

HCIStatusCode BTDevice::connectLE	(	const uint16_t	le_scan_interval = `24`,
		const uint16_t	le_scan_window = `24`,
		const uint16_t	conn_interval_min = `8`,
		const uint16_t	conn_interval_max = `12`,
		const uint16_t	conn_latency = `0`,
		const uint16_t	conn_supervision_timeout = `getHCIConnSupervisorTimeout(0, 15)`
	)

noexcept

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 addressType 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(..), or if failed via AdapterStatusListener::deviceDisconnected(..).

The device is tracked by the managing adapter.

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.

The associated BTAdapter's HCIHandler instance is used to connect, see HCIHandler::le_create_conn().

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]. See Range of [0 - getHCIMaxConnLatency()].
conn_supervision_timeout	in units of 10ms, default value >= 10 x conn_interval_max; Value range [0xA-0x0C80] for [100ms - 32s]. We use 500ms minimum, i.e. getHCIConnSupervisorTimeout(0, 15, ::HCIConstInt::LE_CONN_MIN_TIMEOUT_MS).

Returns: HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

Definition at line 321 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ connectBREDR()

HCIStatusCode BTDevice::connectBREDR	(	const uint16_t	pkt_type = `HCI_DM1 \| HCI_DM3 \| HCI_DM5 \| HCI_DH1 \| HCI_DH3 \| HCI_DH5`,
		const uint16_t	clock_offset = `0x0000`,
		const uint8_t	role_switch = `0x01`
	)

noexcept

Establish a HCI BDADDR_BREDR connection to this device.

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

If this device's addressType is not BDADDR_BREDR, 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(..), or if failed via AdapterStatusListener::deviceDisconnected(..).

The device is tracked by the managing adapter.

The associated BTAdapter's HCIHandler instance is used to connect, see HCIHandler::create_conn().

Returns: HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

Definition at line 523 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ connectDefault()

HCIStatusCode BTDevice::connectDefault ( )

noexcept

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(..), or if failed via AdapterStatusListener::deviceDisconnected(..).

The device is tracked by the managing adapter.

See connectLE() and connectBREDR() for more details.

Returns: HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

Definition at line 563 of file BTDevice.cpp.

◆ getConnectionHandle()

uint16_t direct_bt::BTDevice::getConnectionHandle ( ) const

inlinenoexcept

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

Definition at line 622 of file BTDevice.hpp.

◆ getConnectedLE_PHY()

HCIStatusCode BTDevice::getConnectedLE_PHY	(	LE_PHYs &	resTx,
		LE_PHYs &	resRx
	)

noexcept

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

resTx	reference for the resulting transmitter LE_PHYs bit
resRx	reference for the resulting receiver LE_PHYs bit

Returns: HCIStatusCode

See also: getTxPhys(); getRxPhys(); getConnectedLE_PHY(); setConnectedLE_PHY(); BTAdapter::setDefaultLE_PHY()

Since: 2.4.0

Definition at line 2425 of file BTDevice.cpp.

◆ getTxPhys()

LE_PHYs direct_bt::BTDevice::getTxPhys ( ) const

inlinenoexcept

Return the Tx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY()

See also: getTxPhys(); getRxPhys(); getConnectedLE_PHY(); setConnectedLE_PHY(); BTAdapter::setDefaultLE_PHY()

Since: 2.4.0

Definition at line 651 of file BTDevice.hpp.

◆ getRxPhys()

LE_PHYs direct_bt::BTDevice::getRxPhys ( ) const

inlinenoexcept

Return the Rx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getConnectedLE_PHY()

See also: getTxPhys(); getRxPhys(); getConnectedLE_PHY(); setConnectedLE_PHY(); BTAdapter::setDefaultLE_PHY()

Since: 2.4.0

Definition at line 663 of file BTDevice.hpp.

◆ setConnectedLE_PHY()

HCIStatusCode BTDevice::setConnectedLE_PHY	(	const LE_PHYs	Tx,
		const LE_PHYs	Rx
	)

noexcept

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
BT Core Spec v5.2: Vol 4, Part E, 7.7.65.12 LE PHY Update Complete event

Parameters

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

Returns

See also: getTxPhys(); getRxPhys(); getConnectedLE_PHY(); setConnectedLE_PHY(); BTAdapter::setDefaultLE_PHY()

Since: 2.4.0

Definition at line 2449 of file BTDevice.cpp.

◆ disconnect()

HCIStatusCode BTDevice::disconnect ( const HCIStatusCode reason = HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION )

noexcept

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(..).

The device will be removed from the managing adapter's connected devices when AdapterStatusListener::deviceDisconnected(..) has been received.

An open GATTHandler 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!

The associated BTAdapter's HCIHandler instance is used to disconnect, see HCIHandler::disconnect().

Returns: HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

Definition at line 2488 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ isPrePaired()

bool direct_bt::BTDevice::isPrePaired ( ) const

inlinenoexcept

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

See also: uploadKeys()

Since: 3.2.3

Definition at line 718 of file BTDevice.hpp.

◆ getResponderSMPPassKey()

std::uint32_t BTDevice::getResponderSMPPassKey ( ) const

noexcept

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()

Definition at line 2568 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getResponderSMPPassKeyString()

std::string direct_bt::BTDevice::getResponderSMPPassKeyString ( ) const

inlinenoexcept

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

'012345'.

Definition at line 732 of file BTDevice.hpp.

◆ getAvailableSMPKeys()

SMPKeyType BTDevice::getAvailableSMPKeys ( const bool responder ) const

noexcept

Returns the available SMPKeyType mask 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: SMPKeyType mask result

See also: SMPPairingState::COMPLETED; AdapterStatusListener::deviceReady()

Definition at line 1547 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setSMPKeyBin()

bool BTDevice::setSMPKeyBin ( const SMPKeyBin & bin )

noexcept

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 SMPKeyBin::isValid() and initiator or responder LTK available, the following procedure will be applied to this 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 pairing is currently in progress

See also: isPrePaired(); setLongTermKey(); setIdentityResolvingKey(); setSignatureResolvingKey(); setLinkKey(); uploadKeys()

Since: 2.4.0

Definition at line 1556 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ uploadKeys() [1/3]

HCIStatusCode BTDevice::uploadKeys ( )

noexcept

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(); setIdentityResolvingKey(); setSignatureResolvingKey(); setLinkKey(); setSMPKeyBin()

Since: 2.4.0

Definition at line 1649 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ uploadKeys() [2/3]

HCIStatusCode direct_bt::BTDevice::uploadKeys	(	const SMPKeyBin &	bin,
		const BTSecurityLevel	req_min_level
	)

inlinenoexcept

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(); uploadKeys()

Since: 2.4.0

Definition at line 800 of file BTDevice.hpp.

◆ uploadKeys() [3/3]

HCIStatusCode direct_bt::BTDevice::uploadKeys	(	const std::string &	smp_key_bin_path,
		const BTSecurityLevel	req_min_level,
		const bool	verbose_
	)

inlinenoexcept

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(); setSMPKeyBin(); uploadKeys()

Since: 2.4.0

Definition at line 820 of file BTDevice.hpp.

◆ getLongTermKey()

SMPLongTermKey BTDevice::getLongTermKey ( const bool responder ) const

noexcept

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. SMPLongTermKeyInfo::enc_size will be zero if invalid.

See also: SMPPairingState::COMPLETED; AdapterStatusListener::deviceReady()

Definition at line 1726 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setLongTermKey()

void BTDevice::setLongTermKey ( const SMPLongTermKey & ltk )

noexcept

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(); uploadKeys()

Since: 2.4.0

Definition at line 1731 of file BTDevice.cpp.

◆ getIdentityResolvingKey()

SMPIdentityResolvingKey BTDevice::getIdentityResolvingKey ( const bool responder ) const

noexcept

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 (LL slave), otherwise the initiator's (LL master).

Returns: the resulting key

See also: SMPPairingState::COMPLETED; AdapterStatusListener::deviceReady()

Definition at line 1744 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setIdentityResolvingKey()

void BTDevice::setIdentityResolvingKey ( const SMPIdentityResolvingKey & irk )

noexcept

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(); uploadKeys()

Since: 2.4.0

Definition at line 1749 of file BTDevice.cpp.

◆ matches_irk()

bool BTDevice::matches_irk ( const BDAddressAndType & rpa )

noexcept

Returns true if this remote device's IRK matches the given random private address (rpa)

Parameters

rpa	random private address

See also: getIdentityResolvingKey()

Definition at line 1764 of file BTDevice.cpp.

◆ getSignatureResolvingKey()

SMPSignatureResolvingKey BTDevice::getSignatureResolvingKey ( const bool responder ) const

noexcept

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()

Definition at line 1775 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setSignatureResolvingKey()

void BTDevice::setSignatureResolvingKey ( const SMPSignatureResolvingKey & csrk )

noexcept

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(); uploadKeys()

Since: 2.4.0

Definition at line 1780 of file BTDevice.cpp.

◆ getLinkKey()

SMPLinkKey BTDevice::getLinkKey ( const bool responder ) const

noexcept

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()

Since: 2.4.0

Definition at line 1793 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setLinkKey()

void BTDevice::setLinkKey ( const SMPLinkKey & lk )

noexcept

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(); uploadKeys()

Since: 2.4.0

Definition at line 1798 of file BTDevice.cpp.

◆ unpair()

HCIStatusCode BTDevice::unpair ( )

noexcept

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().
when a BTRole::Slave BTDevice is disconnected, see AdapterStatusListener::deviceDisconnected().
when a BTRole::Master BTDevice gets connected, see AdapterStatusListener::deviceConnected().

Returns: HCIStatusCode::SUCCESS or an appropriate error status.

See also: AdapterStatusListener::deviceFound(); AdapterStatusListener::deviceDisconnected(); AdapterStatusListener::deviceConnected()

Definition at line 2572 of file BTDevice.cpp.

◆ getConnSecurityLevel()

BTSecurityLevel BTDevice::getConnSecurityLevel ( ) const

noexcept

Return the BTSecurityLevel, determined when the connection is established.

See also: BTSecurityLevel; SMPIOCapability; getConnIOCapability(); setConnSecurity(); setConnSecurityAuto()

Definition at line 1811 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getConnIOCapability()

SMPIOCapability BTDevice::getConnIOCapability ( ) const

noexcept

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

See also: BTSecurityLevel; SMPIOCapability; getConnSecurityLevel(); setConnSecurity(); setConnSecurityAuto()

Definition at line 1816 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setConnSecurity()

bool BTDevice::setConnSecurity	(	const BTSecurityLevel	sec_level,
		const SMPIOCapability	io_cap = `SMPIOCapability::UNSET`
	)

noexcept

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

Parameter are validated using validateSecParam().

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

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

Parameters

[in]	sec_level	BTSecurityLevel to be applied.
[in]	io_cap	SMPIOCapability to be applied, defaults to SMPIOCapability::UNSET

See also: BTSecurityLevel; SMPIOCapability; getConnSecurityLevel(); getConnIOCapability(); setConnSecurityAuto()

Definition at line 1896 of file BTDevice.cpp.

◆ setConnSecurityAuto()

bool BTDevice::setConnSecurityAuto ( const SMPIOCapability iocap_auto )

noexcept

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 AdapterStatusListener::deviceConnected() and AdapterStatusListener::deviceDisconnected() callbacks are not delivered while negotiating. This avoids any interference by the user application.

Parameters

auth_io_cap user SMPIOCapability choice for negotiation

See also: isConnSecurityAutoEnabled(); BTSecurityLevel; SMPIOCapability; setConnSecurity()

Definition at line 1923 of file BTDevice.cpp.

◆ isConnSecurityAutoEnabled()

bool BTDevice::isConnSecurityAutoEnabled ( ) const

noexcept

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

See also: setConnSecurityAuto()

Definition at line 1963 of file BTDevice.cpp.

◆ setPairingPINCode()

HCIStatusCode BTDevice::setPairingPINCode ( const std::string & pinCode )

noexcept

Definition at line 1968 of file BTDevice.cpp.

◆ setPairingPINCodeNegative()

HCIStatusCode BTDevice::setPairingPINCodeNegative ( )

noexcept

Definition at line 1989 of file BTDevice.cpp.

◆ setPairingPasskey()

HCIStatusCode BTDevice::setPairingPasskey ( const uint32_t passkey )

noexcept

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 AdapterStatusListener::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(); setPairingPasskey(); setPairingNumericComparison(); getPairingMode(); getPairingState()

Definition at line 2010 of file BTDevice.cpp.

◆ setPairingPasskeyNegative()

HCIStatusCode BTDevice::setPairingPasskeyNegative ( )

noexcept

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 AdapterStatusListener::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() 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(); setPairingPasskey(); setPairingNumericComparison(); getPairingMode(); getPairingState()

Definition at line 2031 of file BTDevice.cpp.

◆ setPairingNumericComparison()

HCIStatusCode BTDevice::setPairingNumericComparison ( const bool equal )

noexcept

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 AdapterStatusListener::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(); setPairingPasskey(); setPairingNumericComparison(); getPairingMode(); getPairingState()

Definition at line 2052 of file BTDevice.cpp.

◆ getPairingMode()

PairingMode BTDevice::getPairingMode ( ) const

noexcept

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 AdapterStatusListener::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(); setPairingPasskey(); setPairingNumericComparison(); getPairingMode(); getPairingState()

Definition at line 2073 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getPairingState()

SMPPairingState BTDevice::getPairingState ( ) const

noexcept

Returns the current SMPPairingState.

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

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(); setPairingPasskey(); setPairingNumericComparison(); getPairingMode(); getPairingState()

Definition at line 2078 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ remove()

void BTDevice::remove ( )

noexcept

Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared references from the Adapter: connected-devices, discovered-devices and shared-devices.

All added AdapterStatusListener associated with this instance will be removed via BTAdapter::removeAllStatusListener().

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

See also: BTAdapter::removeAllStatusListener()

Definition at line 2588 of file BTDevice.cpp.

◆ getGattHandler()

std::shared_ptr< BTGattHandler > BTDevice::getGattHandler ( )

noexcept

Returns the connected GATTHandler or nullptr, see connectGATT(), getGattServices() and disconnect().

Returns

See also: connectGATT(); getGattServices(); disconnect()

Definition at line 2235 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getGattServices()

BTDevice::GattServiceList_t BTDevice::getGattServices ( )

noexcept

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 GattGenericAccessSvc, 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 (GATTRole::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 GattGenericAccessSvc is extracted from the services, see getGattGenericAccess().

A GATT connection will be created via connectGATT() if not established yet.

See also: getGattGenericAccess()

Definition at line 2240 of file BTDevice.cpp.

◆ getGattGenericAccess()

std::shared_ptr< GattGenericAccessSvc > BTDevice::getGattGenericAccess ( )

Returns the shared GenericAccess instance, retrieved by getGattServices() or nullptr if not available.

Returns

See also: getGattServices()

Definition at line 2290 of file BTDevice.cpp.

◆ findGattService()

BTGattServiceRef BTDevice::findGattService ( const jau::uuid_t & service_uuid )

noexcept

Find a BTGattService by its service_uuid.

It will check objects of a connected device using getGattServices().

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

@parameter service_uuid the jau::uuid_t of the desired BTGattService

Returns: The matching service or null if not found

See also: findGattChar()

Definition at line 2299 of file BTDevice.cpp.

◆ findGattChar() [1/2]

BTGattCharRef BTDevice::findGattChar	(	const jau::uuid_t &	service_uuid,
		const jau::uuid_t &	char_uuid
	)

noexcept

Find a BTGattChar by its service_uuid and char_uuid.

It will check objects of this connected device using getGattServices().

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

@parameter service_uuid the jau::uuid_t of the intermediate BTGattService @parameter char_uuid the jau::uuid_t of the desired BTGattChar, within the intermediate BTGattService.

Returns: The matching characteristic or null if not found

Since: 2.4.0

See also: findGattService()

Definition at line 2309 of file BTDevice.cpp.

◆ findGattChar() [2/2]

BTGattCharRef BTDevice::findGattChar ( const jau::uuid_t & char_uuid )

noexcept

Find a BTGattChar by its char_uuid only.

It will check objects of this connected device using getGattServices().

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 jau::uuid_t of the desired BTGattChar, within the intermediate BTGattService.

Returns: The matching characteristic or null if not found

Since: 2.4.0

See also: findGattService()

Definition at line 2317 of file BTDevice.cpp.

◆ sendNotification()

bool BTDevice::sendNotification	(	const uint16_t	char_value_handle,
		const jau::TROOctets &	value
	)

noexcept

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

Definition at line 2330 of file BTDevice.cpp.

◆ sendIndication()

bool BTDevice::sendIndication	(	const uint16_t	char_value_handle,
		const jau::TROOctets &	value
	)

noexcept

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

Definition at line 2343 of file BTDevice.cpp.

◆ pingGATT()

bool BTDevice::pingGATT ( )

noexcept

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, the GATTHandler will initiate disconnect due to the occurring IO error. A disconnect will finally being issued.

GATT services must have been initialized via getGattServices(), otherwise false is being returned.

Returns: true if successful, otherwise false in case no GATT services exists or is not connected .. etc.

Definition at line 2357 of file BTDevice.cpp.

◆ addCharListener() [1/2]

bool BTDevice::addCharListener ( const BTGattCharListenerRef & l )

noexcept

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

Convenience delegation call to GATTHandler

To enable the actual BLE notification and/or indication, one needs to call BTGattChar::configNotificationIndication(bool, bool, bool[]) or BTGattChar::enableNotificationOrIndication(bool enabledState[2]).

Parameters

listener A BTGattCharListener instance, listening to all BluetoothGattCharacteristic events of this device

Returns: true if the given listener is not element of the list and has been newly added, otherwise false.

Exceptions

IllegalStateException if the GATTHandler is null, i.e. not connected

Definition at line 2367 of file BTDevice.cpp.

◆ addCharListener() [2/2]

bool BTDevice::addCharListener	(	const BTGattCharListenerRef &	l,
		const BTGattCharRef &	d
	)

noexcept

Please use BTGattChar::addCharListener() for clarity, merely existing here to allow JNI access.

Definition at line 2376 of file BTDevice.cpp.

◆ removeCharListener()

bool BTDevice::removeCharListener ( const BTGattCharListenerRef & l )

noexcept

Remove the given BTGattCharListener from the listener list.

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

Definition at line 2385 of file BTDevice.cpp.

◆ removeAllAssociatedCharListener() [1/2]

BTDevice::size_type BTDevice::removeAllAssociatedCharListener ( const BTGattCharRef & associatedCharacteristic )

noexcept

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

Implementation tests all listener's BTGattCharListener::match(const BTGattChar & characteristic) to match with the given associated characteristic.

Parameters

associatedCharacteristic the match criteria to remove any BTGattCharListener from the list

Returns: number of removed listener.

Definition at line 2395 of file BTDevice.cpp.

◆ removeAllAssociatedCharListener() [2/2]

BTDevice::size_type BTDevice::removeAllAssociatedCharListener ( const BTGattChar * associatedCharacteristic )

noexcept

Definition at line 2405 of file BTDevice.cpp.

◆ removeAllCharListener()

BTDevice::size_type BTDevice::removeAllCharListener ( )

noexcept

Remove all BTGattCharListener from the list.

Returns: number of removed listener.

Definition at line 2415 of file BTDevice.cpp.

Member Data Documentation

◆ ts_creation

const uint64_t direct_bt::BTDevice::ts_creation

Definition at line 307 of file BTDevice.hpp.

◆ visibleAddressAndType

BDAddressAndType direct_bt::BTDevice::visibleAddressAndType

Either the remote devices' initially reported (resolvable) random address or its (static) public identity address.

Definition at line 309 of file BTDevice.hpp.

◆ addressAndType

BDAddressAndType direct_bt::BTDevice::addressAndType

Device's unique mac address and type tuple, might be its initially reported (resolvable) random address until pairing.

Definition at line 311 of file BTDevice.hpp.

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

api/direct_bt/BTDevice.hpp
src/direct_bt/BTDevice.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ size_type

◆ ssize_type

◆ GattServiceList_t

Constructor & Destructor Documentation

◆ BTDevice() [1/2]

◆ BTDevice() [2/2]

◆ ~BTDevice()

Member Function Documentation

◆ validateSecParam()

◆ operator=()

◆ get_java_class()

◆ java_class()

◆ getAdapter()

◆ getSharedInstance()

◆ getRole()

◆ getLocalGATTRole()

◆ getCreationTimestamp()

◆ getLastDiscoveryTimestamp()

◆ getLastUpdateTimestamp()

◆ getLastUpdateAge()

◆ getAddressAndType()

◆ getVisibleAddressAndType()

◆ getRSSI()

◆ getTxPower()

◆ getName()

◆ getEIR()

◆ getEIRInd()

◆ getEIRScanRsp()

◆ toString() [1/2]

◆ toString() [2/2]

◆ addStatusListener()

◆ removeStatusListener()

◆ getConnectionInfo()

◆ getConnected()

◆ connectLE()

◆ connectBREDR()

◆ connectDefault()

◆ getConnectionHandle()

◆ getConnectedLE_PHY()

◆ getTxPhys()

◆ getRxPhys()

◆ setConnectedLE_PHY()

◆ disconnect()

◆ isPrePaired()

◆ getResponderSMPPassKey()

◆ getResponderSMPPassKeyString()

◆ getAvailableSMPKeys()

◆ setSMPKeyBin()

◆ uploadKeys() [1/3]

◆ uploadKeys() [2/3]

◆ uploadKeys() [3/3]

◆ getLongTermKey()

◆ setLongTermKey()

◆ getIdentityResolvingKey()

◆ setIdentityResolvingKey()

◆ matches_irk()

◆ getSignatureResolvingKey()

◆ setSignatureResolvingKey()

◆ getLinkKey()

◆ setLinkKey()

◆ unpair()

◆ getConnSecurityLevel()

◆ getConnIOCapability()

◆ setConnSecurity()

◆ setConnSecurityAuto()

◆ isConnSecurityAutoEnabled()

◆ setPairingPINCode()

◆ setPairingPINCodeNegative()

◆ setPairingPasskey()

◆ setPairingPasskeyNegative()

◆ setPairingNumericComparison()

◆ getPairingMode()

◆ getPairingState()