Representing a Gatt Characteristic object from the GATTRole::Client perspective. More...

#include <BTGattChar.hpp>

Inheritance diagram for direct_bt::BTGattChar:

Collaboration diagram for direct_bt::BTGattChar:

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

typedef jau::nsize_t	size_type

typedef jau::snsize_t	ssize_type

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

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

bool	addCharListener (const BTGattCharListenerRef &l, bool enabledState[2]) noexcept
	Add the given BTGattCharListener to the listener list if not already present and if enabling the notification or indication for this characteristic at BLE level was successful. More...

void	clearDescriptors () noexcept

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

bool	disableIndicationNotification () noexcept
	BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration. More...

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

std::shared_ptr< BTGattDesc >	findGattDesc (const jau::uuid_t &desc_uuid) noexcept
	Find a BTGattDesc by its desc_uuid. More...

std::string	get_java_class () const noexcept override

BTGattDescRef	getClientCharConfig () const noexcept
	Return the Client Characteristic Configuration BTGattDescRef if available or nullptr. More...

BTDeviceRef	getDeviceUnchecked () const noexcept

BTGattHandlerRef	getGattHandlerUnchecked () const noexcept

BTGattServiceRef	getServiceUnchecked () const noexcept

BTGattDescRef	getUserDescription () const noexcept
	Return the User Description BTGattDescRef if available or nullptr. More...

bool	hasProperties (const PropertyBitVal v) const noexcept

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

size_type	removeAllAssociatedCharListener (bool shallDisableIndicationNotification) noexcept
	Removes all associated BTGattCharListener and and `BTGattCharListener` from the listener list. More...

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

std::string	toString () const noexcept override

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

bool	writeValueNoResp (const jau::TROOctets &value) noexcept
	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
	~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

Public Attributes
ssize_type	clientCharConfigIndex = -1

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

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

const PropertyBitVal	properties

ssize_type	userDescriptionIndex = -1

const uint16_t	value_handle
	Characteristics Value Handle. More...

std::unique_ptr< const jau::uuid_t >	value_type

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

Representing a Gatt Characteristic object from the GATTRole::Client perspective.

A list of shared BTGattChar instances is available from BTGattService via BTGattService::characteristicList.

See Direct-BT Overview.

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3 Characteristic Definition

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

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

Definition at line 94 of file BTGattChar.hpp.

Member Typedef Documentation

◆ size_type

typedef jau::nsize_t direct_bt::BTGattChar::size_type

Definition at line 117 of file BTGattChar.hpp.

◆ ssize_type

typedef jau::snsize_t direct_bt::BTGattChar::ssize_type

Definition at line 118 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 105 of file BTGattChar.hpp.

Constructor & Destructor Documentation

◆ BTGattChar()

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

inlinenoexcept

Definition at line 151 of file BTGattChar.hpp.

Member Function Documentation

◆ get_java_class()

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

inlineoverridevirtualnoexcept

Implements jau::jni::JavaUplink.

Definition at line 156 of file BTGattChar.hpp.

◆ java_class()

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

inlinestaticnoexcept

Definition at line 159 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ getServiceUnchecked()

BTGattServiceRef direct_bt::BTGattChar::getServiceUnchecked ( ) const

inlinenoexcept

Definition at line 163 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ getGattHandlerUnchecked()

BTGattHandlerRef BTGattChar::getGattHandlerUnchecked ( ) const

noexcept

Definition at line 173 of file BTGattChar.cpp.

◆ getDeviceUnchecked()

BTDeviceRef BTGattChar::getDeviceUnchecked ( ) const

noexcept

Definition at line 181 of file BTGattChar.cpp.

◆ hasProperties()

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

inlinenoexcept

Definition at line 167 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ findGattDesc()

std::shared_ptr< BTGattDesc > BTGattChar::findGattDesc ( const jau::uuid_t & desc_uuid )

noexcept

Find a BTGattDesc by its desc_uuid.

@parameter desc_uuid the UUID of the desired BTGattDesc

Returns: The matching descriptor or null if not found

Definition at line 103 of file BTGattChar.cpp.

◆ toString()

std::string BTGattChar::toString ( ) const

overridevirtualnoexcept

Reimplemented from jau::jni::JavaUplink.

Definition at line 114 of file BTGattChar.cpp.

◆ clearDescriptors()

void direct_bt::BTGattChar::clearDescriptors ( )

inlinenoexcept

Definition at line 179 of file BTGattChar.hpp.

◆ getClientCharConfig()

BTGattDescRef direct_bt::BTGattChar::getClientCharConfig ( ) const

inlinenoexcept

Return the Client Characteristic Configuration BTGattDescRef if available or nullptr.

The BTGattDesc::Type::CLIENT_CHARACTERISTIC_CONFIGURATION has been indexed while retrieving the GATT database from the server.

Definition at line 191 of file BTGattChar.hpp.

◆ getUserDescription()

BTGattDescRef direct_bt::BTGattChar::getUserDescription ( ) const

inlinenoexcept

Return the User Description BTGattDescRef if available or nullptr.

The BTGattDesc::Type::CHARACTERISTIC_USER_DESCRIPTION has been indexed while retrieving the GATT database from the server.

Definition at line 204 of file BTGattChar.hpp.

Here is the caller graph for this function:

◆ configNotificationIndication()

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

noexcept

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.

See also: enableNotificationOrIndication(); disableIndicationNotification()

Definition at line 189 of file BTGattChar.cpp.

Here is the caller graph for this function:

◆ enableNotificationOrIndication()

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

noexcept

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.

See also: configNotificationIndication(); disableIndicationNotification()

Definition at line 244 of file BTGattChar.cpp.

◆ disableIndicationNotification()

bool BTGattChar::disableIndicationNotification ( )

noexcept

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

Method will attempt to disable notification and indication on the BLE level.

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

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.

See also: configNotificationIndication(); enableNotificationOrIndication()

Since: 2.4.0

Definition at line 254 of file BTGattChar.cpp.

◆ addCharListener() [1/2]

bool BTGattChar::addCharListener ( const BTGattCharListenerRef & l )

noexcept

Add the given BTGattCharListener 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 BTGattCharListener callback method.

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

Convenience delegation call to BTGattHandler via BTDevice

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

Definition at line 259 of file BTGattChar.cpp.

◆ addCharListener() [2/2]

bool BTGattChar::addCharListener	(	const BTGattCharListenerRef &	l,
		bool	enabledState[2]
	)

noexcept

Add the given BTGattCharListener 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 BTGattCharListener 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.

Parameters

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

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

Definition at line 278 of file BTGattChar.cpp.

◆ removeCharListener()

bool BTGattChar::removeCharListener ( const BTGattCharListenerRef & l )

noexcept

Remove the given associated BTGattCharListener from the listener list if present.

To disables the notification and/or indication for this characteristic at BLE level use disableIndicationNotification() when desired.

Parameters

l

Returns

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

Since: 2.4.0

Definition at line 285 of file BTGattChar.cpp.

◆ removeAllAssociatedCharListener()

BTGattChar::size_type BTGattChar::removeAllAssociatedCharListener ( bool shallDisableIndicationNotification )

noexcept

Removes all associated BTGattCharListener and and BTGattCharListener from the listener list.

Also disables the notification and/or indication for this characteristic at BLE level if disableIndicationNotification == true.

Returns the number of removed event listener.

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

Parameters

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

Definition at line 294 of file BTGattChar.cpp.

◆ readValue()

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

noexcept

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, false is returned.

Definition at line 306 of file BTGattChar.cpp.

◆ writeValue()

bool BTGattChar::writeValue ( const jau::TROOctets & value )

noexcept

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, false is returned.

Definition at line 322 of file BTGattChar.cpp.

◆ writeValueNoResp()

bool BTGattChar::writeValueNoResp ( const jau::TROOctets & value )

noexcept

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, false is returned.

Definition at line 339 of file BTGattChar.cpp.

Member Data Documentation

◆ 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 126 of file BTGattChar.hpp.

◆ properties

const PropertyBitVal direct_bt::BTGattChar::properties

Definition at line 129 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 137 of file BTGattChar.hpp.

◆ value_type

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

Definition at line 140 of file BTGattChar.hpp.

◆ descriptorList

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

List of Characteristic Descriptions as shared reference.

Definition at line 143 of file BTGattChar.hpp.

◆ clientCharConfigIndex

ssize_type direct_bt::BTGattChar::clientCharConfigIndex = -1

Definition at line 146 of file BTGattChar.hpp.

◆ userDescriptionIndex

ssize_type direct_bt::BTGattChar::userDescriptionIndex = -1

Definition at line 149 of file BTGattChar.hpp.

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

api/direct_bt/BTGattChar.hpp
src/direct_bt/BTGattChar.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ size_type

◆ ssize_type

Member Enumeration Documentation

◆ PropertyBitVal

Constructor & Destructor Documentation

◆ BTGattChar()

Member Function Documentation

◆ get_java_class()

◆ java_class()

◆ getServiceUnchecked()

◆ getGattHandlerUnchecked()

◆ getDeviceUnchecked()

◆ hasProperties()

◆ findGattDesc()

◆ toString()

◆ clearDescriptors()

◆ getClientCharConfig()

◆ getUserDescription()

◆ configNotificationIndication()

◆ enableNotificationOrIndication()

◆ disableIndicationNotification()

◆ addCharListener() [1/2]

◆ addCharListener() [2/2]

◆ removeCharListener()

◆ removeAllAssociatedCharListener()

◆ readValue()

◆ writeValue()

◆ writeValueNoResp()

Member Data Documentation

◆ handle

◆ properties

◆ value_handle

◆ value_type

◆ descriptorList

◆ clientCharConfigIndex

◆ userDescriptionIndex