#include <BTDevice.hpp>

Inheritance diagram for direct_bt::BTDevice:

Collaboration diagram for direct_bt::BTDevice:

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

	BTDevice (const BTDevice &)=delete

void	operator= (const BTDevice &)=delete

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

std::string	get_java_class () const noexcept override

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

std::shared_ptr< BTDevice >	getSharedInstance () const noexcept
	Returns the shared pointer of this instance managed by the adapter. 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...

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	getLastUpdateTimestamp () const noexcept
	Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time. More...

uint64_t	getLastUpdateAge (const uint64_t ts_now) const noexcept

constexpr BDAddressAndType const &	getAddressAndType () const noexcept
	Returns the unique device EUI48 address and BDAddressType type. More...

int8_t	getRSSI () const noexcept
	Return RSSI of device as recognized at discovery and connect. More...

int8_t	getTxPower () const noexcept
	Return Tx Power of device as recognized at discovery and connect. More...

AppearanceCat	getAppearance () const noexcept
	Return AppearanceCat of device as recognized at discovery, connect and GATT discovery. More...

std::string const	getName () const noexcept

std::shared_ptr< ManufactureSpecificData > const	getManufactureSpecificData () const noexcept
	Return shared ManufactureSpecificData as recognized at discovery, pre GATT discovery. More...

jau::darray< std::shared_ptr< uuid_t > >	getAdvertisedServices () const noexcept
	Return a list of advertised services as recognized at discovery, pre GATT discovery. More...

std::string	toString () const noexcept override

std::string	toString (bool includeDiscoveredServices) const noexcept

bool	addStatusListener (std::shared_ptr< AdapterStatusListener > l)
	Add the given AdapterStatusListener to the list if not already present, intended to listen only for events matching this device. More...

bool	removeStatusListener (std::shared_ptr< AdapterStatusListener > l)
	Remove the given listener from the list. 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...

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

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

HCIStatusCode	connectLE (const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24, const uint16_t conn_interval_min=12, const uint16_t conn_interval_max=12, const uint16_t conn_latency=0, const uint16_t supervision_timeout=getHCIConnSupervisorTimeout(0, 15)) noexcept
	Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to 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...

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

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

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

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

HCIStatusCode	setLongTermKeyInfo (const SMPLongTermKeyInfo &ltk) noexcept
	Sets the long term ket (LTK) info of this device to reuse pre-paired encryption. More...

SMPSignatureResolvingKeyInfo	getSignatureResolvingKeyInfo (const bool responder) const noexcept
	Returns a copy of the Signature Resolving Key (LTK) info, valid after connection and SMP pairing has been completed. More...

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

HCIStatusCode	pair (const SMPIOCapability io_cap) noexcept
	Experimental only. More...

bool	setConnSecurityLevel (const BTSecurityLevel sec_level) noexcept
	Set the BTSecurityLevel used to connect to this device on the upcoming connection. More...

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

bool	setConnIOCapability (const SMPIOCapability io_cap) noexcept
	Sets the given SMPIOCapability used to connect to this device on the upcoming connection. More...

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

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

bool	setConnSecurityBest (const BTSecurityLevel sec_level, const SMPIOCapability io_cap) noexcept
	Convenience method to determine the best practice BTSecurityLevel and SMPIOCapability based on the given arguments, used to connect to this device on the upcoming connection. More...

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

bool	isConnSecurityAutoEnabled () const noexcept
	Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(), otherwise false. 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	setPairingNumericComparison (const bool equal) noexcept
	Method sets the numeric comparison result, see PairingMode::NUMERIC_COMPARE_ini. More...

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

SMPPairingState	getPairingState () const noexcept
	Returns the current SMPPairingState. 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...

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

jau::darray< std::shared_ptr< BTGattService > >	getGattServices () noexcept
	Returns a list of shared GATTService available on this device if successful, otherwise returns an empty list if an error occurred. More...

std::shared_ptr< BTGattService >	findGattService (std::shared_ptr< uuid_t > const &uuid)
	Returns the matching GATTService for the given uuid. More...

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

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

bool	addCharListener (std::shared_ptr< BTGattCharListener > l)
	Add the given BTGattCharListener to the listener list if not already present. More...

bool	removeCharListener (std::shared_ptr< BTGattCharListener > l) noexcept
	Remove the given BTGattCharListener from the listener list. More...

int	removeAllAssociatedCharListener (std::shared_ptr< BTGattChar > associatedCharacteristic) noexcept
	Remove all BTGattCharListener from the list, which are associated to the given BTGattChar. More...

int	removeAllAssociatedCharListener (const BTGattChar *associatedCharacteristic) noexcept

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

Public Member Functions inherited from direct_bt::BTObject
virtual	~BTObject () noexcept

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

Public Member Functions inherited from jau::JavaUplink
std::string	javaObjectToString () const noexcept

std::shared_ptr< JavaAnon >	getJavaObject () noexcept

void	setJavaObject (std::shared_ptr< JavaAnon > objRef) noexcept
	Assigns a new shared JavaAnon reference, replaced item might be deleted via JNI from dtor. More...

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

void	clearJavaObject () noexcept
	Clears the java reference, i.e. More...

virtual void	checkValid () const
	Throws an IllegalStateException if isValid() == false. More...

virtual	~JavaUplink () noexcept

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

Public Attributes
const uint64_t	ts_creation

const BDAddressAndType	addressAndType
	Device's unique mac address and type tuple. More...

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

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

Detailed Description

Definition at line 56 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 47 of file BTDevice.cpp.

Here is the call graph for this function:

◆ BTDevice() [2/2]

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

delete

◆ ~BTDevice()

BTDevice::~BTDevice ( )

noexcept

Releases this instance after calling remove().

Definition at line 82 of file BTDevice.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ addCharListener()

bool BTDevice::addCharListener ( std::shared_ptr< BTGattCharListener > l )

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 1599 of file BTDevice.cpp.

Here is the call graph for this function:

◆ addStatusListener()

bool BTDevice::addStatusListener ( std::shared_ptr< AdapterStatusListener > l )

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

Examples: dbt_scanner10.cpp.

Definition at line 248 of file BTDevice.cpp.

Here is the call graph for this function:

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 492 of file BTDevice.cpp.

Here is the call graph for this function:

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.

Examples: dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 532 of file BTDevice.cpp.

Here is the call graph for this function:

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 = `12`,
		const uint16_t	conn_interval_max = `12`,
		const uint16_t	conn_latency = `0`,
		const uint16_t	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 12 for 15ms; 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 HCIConstInt::LE_CONN_MIN_TIMEOUT_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.

Definition at line 283 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

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

Examples: dbt_scanner00.cpp, and dbt_scanner01.cpp.

Definition at line 1701 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findGattService()

std::shared_ptr< BTGattService > BTDevice::findGattService ( std::shared_ptr< uuid_t > const & uuid )

Returns the matching GATTService for the given uuid.

Implementation calls getGattService().

Definition at line 1563 of file BTDevice.cpp.

Here is the call graph for this function:

◆ get_java_class()

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

inlineoverridevirtualnoexcept

Implements jau::JavaUplink.

Definition at line 235 of file BTDevice.hpp.

Here is the call graph for this function:

◆ getAdapter()

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

inline

Returns the managing adapter.

Examples: dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 243 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getAddressAndType()

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

inlineconstexprnoexcept

Returns the unique device EUI48 address and BDAddressType type.

Since: 2.2.0

Examples: dbt_scanner10.cpp.

Definition at line 278 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getAdvertisedServices()

jau::darray< std::shared_ptr< uuid_t > > BTDevice::getAdvertisedServices ( ) const

noexcept

Return a list of advertised services as recognized at discovery, pre GATT discovery.

To receive a complete list of GATT services including characteristics etc, use getGattService().

Definition at line 136 of file BTDevice.cpp.

◆ getAppearance()

AppearanceCat direct_bt::BTDevice::getAppearance ( ) const

inlinenoexcept

Return AppearanceCat of device as recognized at discovery, connect and GATT discovery.

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

Definition at line 1107 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getConnected()

bool direct_bt::BTDevice::getConnected ( )

inlinenoexcept

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

Definition at line 359 of file BTDevice.hpp.

◆ getConnectedLE_PHY()

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

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 (we transfer the sequential value to this bitmask for unification)

Parameters

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

Returns: HCIStatusCode

Examples: dbt_scanner10.cpp.

Definition at line 1648 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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 466 of file BTDevice.hpp.

◆ 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 256 of file BTDevice.cpp.

Here is the call 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; setConnSecurityLevel(); getConnSecurityLevel(); setConnIOCapability(); setConnSecurity(); setConnSecurityBest()

Definition at line 1232 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getConnSecurityLevel()

BTSecurityLevel BTDevice::getConnSecurityLevel ( ) const

noexcept

Return the BTSecurityLevel, determined when the connection is established.

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(); setConnIOCapability(); getConnIOCapability(); setConnSecurity(); setConnSecurityBest()

Definition at line 1204 of file BTDevice.cpp.

Here is the caller graph for this function:

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

Examples: dbt_scanner00.cpp, and dbt_scanner01.cpp.

Definition at line 253 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getGattGenericAccess()

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

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

Examples: dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 1590 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getGattHandler()

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

noexcept

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

Examples: dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 1520 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getGattServices()

jau::darray< std::shared_ptr< BTGattService > > BTDevice::getGattServices ( )

noexcept

Returns a list of shared GATTService available on this device if successful, otherwise returns an empty list if an error occurred.

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

If this method has been called for the first time or no services has been detected yet, a list of GATTService will be discovered.
In case no GATT connection has been established it will be created via connectGATT().

Examples: dbt_scanner00.cpp, and dbt_scanner10.cpp.

Definition at line 1525 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

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

Examples: dbt_scanner10.cpp.

Definition at line 260 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ getLastUpdateAge()

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

inlinenoexcept

See also: getLastUpdateTimestamp()

Definition at line 272 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 267 of file BTDevice.hpp.

◆ getLongTermKeyInfo()

SMPLongTermKeyInfo BTDevice::getLongTermKeyInfo ( const bool responder ) const

noexcept

Returns a copy of the Long Term Key (LTK) info, 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 1116 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getManufactureSpecificData()

std::shared_ptr< ManufactureSpecificData > const BTDevice::getManufactureSpecificData ( ) const

noexcept

Return shared ManufactureSpecificData as recognized at discovery, pre GATT discovery.

Definition at line 130 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getName()

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

noexcept

Examples: dbt_scanner10.cpp.

Definition at line 124 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ 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 1373 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 1378 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getRSSI()

int8_t direct_bt::BTDevice::getRSSI ( ) const

inlinenoexcept

Return RSSI of device as recognized at discovery and connect.

Definition at line 281 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 90 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getSignatureResolvingKeyInfo()

SMPSignatureResolvingKeyInfo BTDevice::getSignatureResolvingKeyInfo ( const bool responder ) const

noexcept

Returns a copy of the Signature Resolving Key (LTK) info, 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()

Definition at line 1144 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ getTxPower()

int8_t direct_bt::BTDevice::getTxPower ( ) const

inlinenoexcept

Return Tx Power of device as recognized at discovery and connect.

Definition at line 284 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ 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 1299 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ java_class()

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

inlinestaticnoexcept

Definition at line 238 of file BTDevice.hpp.

Here is the caller graph for this function:

◆ operator=()

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

delete

◆ pair()

HCIStatusCode BTDevice::pair ( const SMPIOCapability io_cap )

noexcept

Experimental only.

  adapter.stopDiscovery(): Renders pairDevice(..) to fail: Busy!
  pairDevice(..) behaves quite instable within our connected workflow: Not used!

Definition at line 1149 of file BTDevice.cpp.

Here is the call graph for this function:

◆ 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 getGattService(), otherwise false is being returned.

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

Examples: dbt_scanner10.cpp.

Definition at line 1575 of file BTDevice.cpp.

Here is the call graph for this function:

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

Examples: dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 1784 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ removeAllAssociatedCharListener() [1/2]

int BTDevice::removeAllAssociatedCharListener ( const BTGattChar * associatedCharacteristic )

noexcept

Definition at line 1628 of file BTDevice.cpp.

Here is the call graph for this function:

◆ removeAllAssociatedCharListener() [2/2]

int BTDevice::removeAllAssociatedCharListener ( std::shared_ptr< BTGattChar > 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 1618 of file BTDevice.cpp.

Here is the call graph for this function:

◆ removeAllCharListener()

int BTDevice::removeAllCharListener ( )

noexcept

Remove all BTGattCharListener from the list.

Returns: number of removed listener.

Examples: dbt_scanner10.cpp.

Definition at line 1638 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ removeCharListener()

bool BTDevice::removeCharListener ( std::shared_ptr< BTGattCharListener > 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 1608 of file BTDevice.cpp.

Here is the call graph for this function:

◆ removeStatusListener()

bool BTDevice::removeStatusListener ( std::shared_ptr< AdapterStatusListener > l )

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 252 of file BTDevice.cpp.

Here is the call graph for this function:

◆ setConnIOCapability()

bool BTDevice::setConnIOCapability ( const SMPIOCapability io_cap )

noexcept

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

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

Parameters

[in] io_cap SMPIOCapability to be applied, SMPIOCapability::UNSET will be ignored and method fails.

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(); getConnSecurityLevel(); getConnIOCapability(); setConnSecurity(); setConnSecurityBest()

Definition at line 1209 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setConnSecurity()

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

noexcept

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

Method returns false if this device has already being connected, or 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.

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(); getConnSecurityLevel(); setConnIOCapability(); getConnIOCapability(); setConnSecurityBest()

Definition at line 1237 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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

Examples: dbt_scanner10.cpp.

Definition at line 1274 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setConnSecurityBest()

bool BTDevice::setConnSecurityBest	(	const BTSecurityLevel	sec_level,
		const SMPIOCapability	io_cap
	)

noexcept

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

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

<p<blockquote>

Method returns false if BTSecurityLevel::UNSET and SMPIOCapability::UNSET has been given, operation fails, this device has already being connected, or 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.

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(); getConnSecurityLevel(); setConnIOCapability(); getConnIOCapability(); setConnSecurityBest(); setConnSecurityAuto()

Examples: dbt_scanner10.cpp.

Definition at line 1258 of file BTDevice.cpp.

Here is the caller graph for this function:

◆ setConnSecurityLevel()

bool BTDevice::setConnSecurityLevel ( const BTSecurityLevel sec_level )

noexcept

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

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

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

Parameters

sec_level BTSecurityLevel to be applied, BTSecurityLevel::UNSET will be ignored and method fails.

See also: BTSecurityLevel; SMPIOCapability; getConnSecurityLevel(); setConnIOCapability(); getConnIOCapability(); setConnSecurity(); setConnSecurityBest()

Definition at line 1182 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setLongTermKeyInfo()

HCIStatusCode BTDevice::setLongTermKeyInfo ( const SMPLongTermKeyInfo & ltk )

noexcept

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

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

Parameters

ltk	the pre-paired encryption LTK

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

Definition at line 1121 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

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

Examples: dbt_scanner10.cpp.

Definition at line 1350 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

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

Examples: dbt_scanner10.cpp.

Definition at line 1304 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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 1327 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toString() [1/2]

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

inlineoverridevirtualnoexcept

Reimplemented from direct_bt::BTObject.

Examples: dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 303 of file BTDevice.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toString() [2/2]

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

noexcept

Definition at line 142 of file BTDevice.cpp.

Here is the call graph for this function:

◆ unpair()

HCIStatusCode BTDevice::unpair ( )

noexcept

Unpairs this device from the adapter while staying connected.

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

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

Examples: dbt_scanner10.cpp.

Definition at line 1772 of file BTDevice.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ addressAndType

const BDAddressAndType direct_bt::BTDevice::addressAndType

Device's unique mac address and type tuple.

Definition at line 222 of file BTDevice.hpp.

◆ ts_creation

const uint64_t direct_bt::BTDevice::ts_creation

Examples: dbt_scanner00.cpp, and dbt_scanner01.cpp.

Definition at line 220 of file BTDevice.hpp.

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

/usr/local/projects/direct_bt/api/direct_bt/BTDevice.hpp
/usr/local/projects/direct_bt/src/direct_bt/BTDevice.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BTDevice() [1/2]

◆ BTDevice() [2/2]

◆ ~BTDevice()

Member Function Documentation

◆ addCharListener()

◆ addStatusListener()

◆ connectBREDR()

◆ connectDefault()

◆ connectLE()

◆ disconnect()

◆ findGattService()

◆ get_java_class()

◆ getAdapter()

◆ getAddressAndType()

◆ getAdvertisedServices()

◆ getAppearance()

◆ getAvailableSMPKeys()

◆ getConnected()

◆ getConnectedLE_PHY()

◆ getConnectionHandle()

◆ getConnectionInfo()

◆ getConnIOCapability()

◆ getConnSecurityLevel()

◆ getCreationTimestamp()

◆ getGattGenericAccess()

◆ getGattHandler()

◆ getGattServices()

◆ getLastDiscoveryTimestamp()

◆ getLastUpdateAge()

◆ getLastUpdateTimestamp()

◆ getLongTermKeyInfo()

◆ getManufactureSpecificData()

◆ getName()

◆ getPairingMode()

◆ getPairingState()

◆ getRSSI()

◆ getSharedInstance()

◆ getSignatureResolvingKeyInfo()

◆ getTxPower()

◆ isConnSecurityAutoEnabled()

◆ java_class()

◆ operator=()

◆ pair()

◆ pingGATT()

◆ remove()

◆ removeAllAssociatedCharListener() [1/2]

◆ removeAllAssociatedCharListener() [2/2]

◆ removeAllCharListener()

◆ removeCharListener()

◆ removeStatusListener()

◆ setConnIOCapability()

◆ setConnSecurity()

◆ setConnSecurityAuto()

◆ setConnSecurityBest()

◆ setConnSecurityLevel()

◆ setLongTermKeyInfo()

◆ setPairingNumericComparison()

◆ setPairingPasskey()

◆ setPairingPasskeyNegative()

◆ toString() [1/2]

◆ toString() [2/2]

◆ unpair()

Member Data Documentation

◆ addressAndType

◆ ts_creation