#include <BTGattChar.hpp>

Inheritance diagram for direct_bt::BTGattChar:

Collaboration diagram for direct_bt::BTGattChar:

Classes
class	Listener
	BTGattChar event listener for notification and indication events. More...

Public Types
enum	PropertyBitVal : uint8_t { NONE = 0, Broadcast = (1 << 0), Read = (1 << 1), WriteNoAck = (1 << 2), WriteWithAck = (1 << 3), Notify = (1 << 4), Indicate = (1 << 5), AuthSignedWrite = (1 << 6), ExtProps = (1 << 7) }
	BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.1.1 Characteristic Properties. More...

Public Member Functions
	BTGattChar (const BTGattServiceRef &service_, const uint16_t service_handle_, const uint16_t handle_, const PropertyBitVal properties_, const uint16_t value_handle_, std::unique_ptr< const uuid_t > &&value_type_) noexcept

std::string	get_java_class () const noexcept override

std::shared_ptr< BTGattService >	getServiceUnchecked () const noexcept

std::shared_ptr< BTGattService >	getServiceChecked () const

std::shared_ptr< BTGattHandler >	getGattHandlerUnchecked () const noexcept

std::shared_ptr< BTGattHandler >	getGattHandlerChecked () const

std::shared_ptr< BTDevice >	getDeviceUnchecked () const noexcept

std::shared_ptr< BTDevice >	getDeviceChecked () const

bool	hasProperties (const PropertyBitVal v) const noexcept

std::string	toString () const noexcept override

void	clearDescriptors () noexcept

BTGattDescRef	getClientCharConfig () noexcept

bool	configNotificationIndication (const bool enableNotification, const bool enableIndication, bool enabledState[2])
	BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration. More...

bool	enableNotificationOrIndication (bool enabledState[2])
	BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration. More...

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

bool	addCharListener (std::shared_ptr< Listener > l, bool enabledState[2])
	Add the given BTGattChar::Listener to the listener list if not already present and if enabling the notification or indication for this characteristic at BLE level was successful. More...

int	removeAllAssociatedCharListener (bool disableIndicationNotification)
	Disables the notification and/or indication for this characteristic at BLE level if `disableIndicationNotification == true` and removes all associated BTGattChar::Listener and BTGattCharListener from the listener list. More...

bool	readValue (POctets &res, int expectedLength=-1)
	BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.1 Read Characteristic Value. More...

bool	writeValue (const TROOctets &value)
	BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.3 Write Characteristic Value. More...

bool	writeValueNoResp (const TROOctets &value)
	BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.1 Write Characteristic Value Without Response. 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	getPropertiesString (const PropertyBitVal properties) noexcept
	Returns string values as defined in https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt More...

static jau::darray< std::unique_ptr< std::string > >	getPropertiesStringList (const PropertyBitVal properties) noexcept

static std::string	java_class () noexcept

Public Attributes
const uint16_t	service_handle
	Characteristics's Service Handle - key to service's handle range, retrieved from Characteristics data. More...

const uint16_t	handle
	Characteristic Handle of this instance. More...

const PropertyBitVal	properties

const uint16_t	value_handle
	Characteristics Value Handle. More...

std::unique_ptr< const uuid_t >	value_type

jau::darray< BTGattDescRef >	descriptorList
	List of Characteristic Descriptions as shared reference. More...

int	clientCharConfigIndex = -1

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

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.1 Characteristic Declaration Attribute Value

handle -> CDAV value

BT Core Spec v5.2: Vol 3, Part G GATT: 4.6.1 Discover All Characteristics of a Service

Here the handle is a service's characteristics-declaration and the value the Characteristics Property, Characteristics Value Handle and Characteristics UUID.

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

Definition at line 75 of file BTGattChar.hpp.

Member Enumeration Documentation

◆ PropertyBitVal

enum direct_bt::BTGattChar::PropertyBitVal : uint8_t

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.1.1 Characteristic Properties.

Enumerator
NONE
Broadcast
Read
WriteNoAck
WriteWithAck
Notify
Indicate
AuthSignedWrite
ExtProps

Definition at line 86 of file BTGattChar.hpp.

Constructor & Destructor Documentation

◆ BTGattChar()

direct_bt::BTGattChar::BTGattChar	(	const BTGattServiceRef &	service_,
		const uint16_t	service_handle_,
		const uint16_t	handle_,
		const PropertyBitVal	properties_,
		const uint16_t	value_handle_,
		std::unique_ptr< const uuid_t > &&	value_type_
	)

inlinenoexcept

Definition at line 197 of file BTGattChar.hpp.

Member Function Documentation

◆ addCharListener() [1/2]

bool BTGattChar::addCharListener ( std::shared_ptr< Listener > l )

Add the given BTGattChar::Listener to the listener list if not already present.

Occurring notifications and indications for this characteristic, if enabled via configNotificationIndication(bool, bool, bool[]) or enableNotificationOrIndication(bool[]), will call the respective BTGattChar::Listener callback method.

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

Implementation wraps given BTGattChar::Listener into an AssociatedBTGattCharListener to restrict the listener to listen only to this BTGattChar instance.

Convenience delegation call to BTGattHandler via BTDevice

Exceptions

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

See also: BTGattChar::enableNotificationOrIndication(); BTGattChar::configNotificationIndication(); BTGattChar::addCharListener(); BTGattChar::removeCharListener(); BTGattChar::removeAllAssociatedCharListener()

Examples: dbt_scanner00.cpp, and dbt_scanner10.cpp.

Definition at line 285 of file BTGattChar.cpp.

Here is the caller graph for this function:

◆ addCharListener() [2/2]

bool BTGattChar::addCharListener	(	std::shared_ptr< Listener >	l,
		bool	enabledState[2]
	)

Add the given BTGattChar::Listener to the listener list if not already present and if enabling the notification or indication for this characteristic at BLE level was successful.

Notification and/or indication configuration is only performed per characteristic if changed.

Implementation will enable notification if available, otherwise indication will be enabled if available.
Implementation uses enableNotificationOrIndication(bool[]) to enable either.

Occurring notifications and indications for this characteristic will call the respective BTGattChar::Listener callback method.

Returns true if enabling the notification and/or indication was successful and if the given listener is not element of the list and has been newly added, otherwise false.

Implementation wraps given BTGattChar::Listener into an AssociatedBTGattCharListener to restrict the listener to listen only to this BTGattChar instance.

Parameters

enabledState array of size 2, holding the resulting enabled state for notification and indication using enableNotificationOrIndication(bool[])

Exceptions

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

See also: BTGattChar::enableNotificationOrIndication(); BTGattChar::configNotificationIndication(); BTGattChar::addCharListener(); BTGattChar::removeCharListener(); BTGattChar::removeAllAssociatedCharListener()

Definition at line 289 of file BTGattChar.cpp.

◆ clearDescriptors()

void direct_bt::BTGattChar::clearDescriptors ( )

inlinenoexcept

Definition at line 220 of file BTGattChar.hpp.

Here is the call graph for this function:

◆ configNotificationIndication()

bool BTGattChar::configNotificationIndication	(	const bool	enableNotification,
		const bool	enableIndication,
		bool	enabledState[2]
	)

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration.

Method enables notification and/or indication for this characteristic at BLE level.

Implementation masks this Characteristic properties PropertyBitVal::Notify and PropertyBitVal::Indicate with the respective user request parameters, hence removes unsupported requests.

Notification and/or indication configuration is only performed per characteristic if changed.

It is recommended to utilize notification over indication, as its link-layer handshake and higher potential bandwidth may deliver material higher performance.

Parameters

enableNotification
enableIndication
enabledState	array of size 2, holding the resulting enabled state for notification and indication.

Returns: false if this characteristic has no PropertyBitVal::Notify or PropertyBitVal::Indication present, or there is no BTGattDesc of type ClientCharacteristicConfiguration, or if the operation has failed. Otherwise returns true.

Exceptions

IllegalStateException if notification or indication is set to be enabled and the BTDevice's's BTGattHandler is null, i.e. not connected

Examples: dbt_scanner00.cpp.

Definition at line 186 of file BTGattChar.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ enableNotificationOrIndication()

bool BTGattChar::enableNotificationOrIndication ( bool enabledState[2] )

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration.

Method will attempt to enable notification on the BLE level, if available, otherwise indication if available.

Notification and/or indication configuration is only performed per characteristic if changed.

It is recommended to utilize notification over indication, as its link-layer handshake and higher potential bandwidth may deliver material higher performance.

Parameters

enabledState array of size 2, holding the resulting enabled state for notification and indication.

Returns: false if this characteristic has no PropertyBitVal::Notify or PropertyBitVal::Indication present, or there is no BTGattDesc of type ClientCharacteristicConfiguration, or if the operation has failed. Otherwise returns true.

Exceptions

IllegalStateException if notification or indication is set to be enabled and the BTDevice's's BTGattHandler is null, i.e. not connected

Definition at line 241 of file BTGattChar.cpp.

◆ get_java_class()

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

inlineoverridevirtualnoexcept

Implements jau::JavaUplink.

Definition at line 202 of file BTGattChar.hpp.

Here is the call graph for this function:

◆ getClientCharConfig()

BTGattDescRef direct_bt::BTGattChar::getClientCharConfig ( )

inlinenoexcept

Examples: dbt_scanner01.cpp.

Definition at line 225 of file BTGattChar.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getDeviceChecked()

std::shared_ptr< BTDevice > BTGattChar::getDeviceChecked ( ) const

Definition at line 182 of file BTGattChar.cpp.

◆ getDeviceUnchecked()

std::shared_ptr< BTDevice > BTGattChar::getDeviceUnchecked ( ) const

noexcept

Definition at line 174 of file BTGattChar.cpp.

Here is the call graph for this function:

◆ getGattHandlerChecked()

std::shared_ptr< BTGattHandler > BTGattChar::getGattHandlerChecked ( ) const

Definition at line 170 of file BTGattChar.cpp.

◆ getGattHandlerUnchecked()

std::shared_ptr< BTGattHandler > BTGattChar::getGattHandlerUnchecked ( ) const

noexcept

Definition at line 162 of file BTGattChar.cpp.

Here is the call graph for this function:

◆ getPropertiesString()

std::string BTGattChar::getPropertiesString ( const PropertyBitVal properties )

staticnoexcept

Returns string values as defined in https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt

org.bluez.GattCharacteristic1 :: array{string} Flags [read-only]

Definition at line 76 of file BTGattChar.cpp.

Here is the call graph for this function:

◆ getPropertiesStringList()

jau::darray< std::unique_ptr< std::string > > BTGattChar::getPropertiesStringList ( const PropertyBitVal properties )

staticnoexcept

Definition at line 93 of file BTGattChar.cpp.

Here is the call graph for this function:

◆ getServiceChecked()

std::shared_ptr< BTGattService > BTGattChar::getServiceChecked ( ) const

Definition at line 154 of file BTGattChar.cpp.

◆ getServiceUnchecked()

std::shared_ptr<BTGattService> direct_bt::BTGattChar::getServiceUnchecked ( ) const

inlinenoexcept

Definition at line 209 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ hasProperties()

bool direct_bt::BTGattChar::hasProperties ( const PropertyBitVal v ) const

inlinenoexcept

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

Definition at line 216 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ java_class()

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

inlinestaticnoexcept

Definition at line 205 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ readValue()

bool BTGattChar::readValue	(	POctets &	res,
		int	expectedLength = `-1`
	)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.1 Read Characteristic Value.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.3 Read Long Characteristic Value

If expectedLength = 0, then only one ATT_READ_REQ/RSP will be used.

If expectedLength < 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used until the response returns zero. This is the default parameter.

If expectedLength > 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used if required until the response returns zero.

Convenience delegation call to BTGattHandler via BTDevice

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

Examples: dbt_scanner00.cpp, and dbt_scanner10.cpp.

Definition at line 304 of file BTGattChar.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ removeAllAssociatedCharListener()

int BTGattChar::removeAllAssociatedCharListener ( bool disableIndicationNotification )

Disables the notification and/or indication for this characteristic at BLE level if disableIndicationNotification == true and removes all associated BTGattChar::Listener and BTGattCharListener from the listener list.

Returns the number of removed event listener.

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

Parameters

disableIndicationNotification if true, disables the notification and/or indication for this characteristic using BTGattChar::enableNotificationOrIndication() BTGattChar::configNotificationIndication() BTGattChar::addCharListener() BTGattChar::removeCharListener() BTGattChar::removeAllAssociatedCharListener()

Definition at line 296 of file BTGattChar.cpp.

◆ toString()

std::string BTGattChar::toString ( ) const

overridevirtualnoexcept

Reimplemented from direct_bt::BTObject.

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

Definition at line 106 of file BTGattChar.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeValue()

bool BTGattChar::writeValue ( const TROOctets & value )

BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.3 Write Characteristic Value.

Convenience delegation call to BTGattHandler via BTDevice

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

Definition at line 315 of file BTGattChar.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeValueNoResp()

bool BTGattChar::writeValueNoResp ( const TROOctets & value )

BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.1 Write Characteristic Value Without Response.

Convenience delegation call to BTGattHandler via BTDevice

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

Examples: dbt_scanner10.cpp.

Definition at line 327 of file BTGattChar.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ clientCharConfigIndex

int direct_bt::BTGattChar::clientCharConfigIndex = -1

Definition at line 195 of file BTGattChar.hpp.

◆ descriptorList

jau::darray<BTGattDescRef> direct_bt::BTGattChar::descriptorList

List of Characteristic Descriptions as shared reference.

Examples: dbt_scanner10.cpp.

Definition at line 192 of file BTGattChar.hpp.

◆ handle

const uint16_t direct_bt::BTGattChar::handle

Characteristic Handle of this instance.

Attribute handles are unique for each device (server) (BT Core Spec v5.2: Vol 3, Part F Protocol..: 3.2.2 Attribute Handle).

Definition at line 175 of file BTGattChar.hpp.

◆ properties

const PropertyBitVal direct_bt::BTGattChar::properties

Definition at line 178 of file BTGattChar.hpp.

◆ service_handle

const uint16_t direct_bt::BTGattChar::service_handle

Characteristics's Service Handle - key to service's handle range, retrieved from Characteristics data.

Attribute handles are unique for each device (server) (BT Core Spec v5.2: Vol 3, Part F Protocol..: 3.2.2 Attribute Handle).

Definition at line 167 of file BTGattChar.hpp.

◆ value_handle

const uint16_t direct_bt::BTGattChar::value_handle

Characteristics Value Handle.

Attribute handles are unique for each device (server) (BT Core Spec v5.2: Vol 3, Part F Protocol..: 3.2.2 Attribute Handle).

Definition at line 186 of file BTGattChar.hpp.

◆ value_type

std::unique_ptr<const uuid_t> direct_bt::BTGattChar::value_type

Examples: dbt_scanner10.cpp.

Definition at line 189 of file BTGattChar.hpp.

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

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ PropertyBitVal

Constructor & Destructor Documentation

◆ BTGattChar()

Member Function Documentation

◆ addCharListener() [1/2]

◆ addCharListener() [2/2]

◆ clearDescriptors()

◆ configNotificationIndication()

◆ enableNotificationOrIndication()

◆ get_java_class()

◆ getClientCharConfig()

◆ getDeviceChecked()

◆ getDeviceUnchecked()

◆ getGattHandlerChecked()

◆ getGattHandlerUnchecked()

◆ getPropertiesString()

◆ getPropertiesStringList()

◆ getServiceChecked()

◆ getServiceUnchecked()

◆ hasProperties()

◆ java_class()

◆ readValue()

◆ removeAllAssociatedCharListener()

◆ toString()

◆ writeValue()

◆ writeValueNoResp()

Member Data Documentation

◆ clientCharConfigIndex

◆ descriptorList

◆ handle

◆ properties

◆ service_handle

◆ value_handle

◆ value_type