Representing a Gatt Characteristic object from the GATT client perspective. More...

Inheritance diagram for org.direct_bt.BTGattChar:

Collaboration diagram for org.direct_bt.BTGattChar:

Public Member Functions
boolean	addCharListener (final BTGattCharListener listener) throws IllegalStateException
	Add the given BTGattCharListener to the listener list if not already present. More...

boolean	addCharListener (final BTGattCharListener listener, final boolean enabledState[]) throws IllegalStateException
	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...

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

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

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

BTGattDesc	findGattDesc (final String desc_uuid)
	Find a `BTGattDesc` by its desc_uuid. More...

BTGattDesc	getClientCharConfig ()
	Return the Client Characteristic Configuration BTGattDesc if available or null. More...

List< BTGattDesc >	getDescriptors ()
	Returns a list of BluetoothGattDescriptors this characteristic exposes. More...

boolean	getNotifying (final boolean enabledState[])
	Returns true if notification for changes of this characteristic are activated. More...

GattCharPropertySet	getProperties ()
	Returns the properties of this characteristic. More...

BTGattService	getService ()
	Returns the service to which this characteristic belongs to. More...

BTGattDesc	getUserDescription ()
	Return the User Description BTGattDesc if available or null. More...

String	getUUID ()
	Get the UUID of this characteristic. More...

byte[]	readValue () throws BTException
	Reads the value of this characteristic. More...

int	removeAllAssociatedCharListener (final boolean shallDisableIndicationNotification)
	Disables the notification and/or indication for this characteristic BLE level if `disableIndicationNotification == true` and removes all associated `BTGattChar.Listener` or `BTGattCharListener` from the listener list, which are associated with this characteristic instance. More...

boolean	removeCharListener (final BTGattCharListener listener)
	Remove the given associated `BTGattCharListener` from the listener list if present. More...

String	toString ()

boolean	writeValue (byte[] argValue, boolean withResponse) throws BTException
	Writes the value of this characteristic, using one of the following methods depending on `withResponse @endiliteral.` More...

Public Member Functions inherited from org.direct_bt.BTObject
void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...

boolean	equals (Object obj)

int	hashCode ()

Detailed Description

Representing a Gatt Characteristic object from the GATT client perspective.

A list of shared BTGattChar instances is available from BTGattService via BTGattService::getChars().

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.

See DBGattChar.UUID16 for selected standard GATT characteristic numbers in UUID16 format and BTUtils#toUUID128(String) for their conversion to UUID128.

Definition at line 48 of file BTGattChar.java.

Member Function Documentation

◆ findGattDesc()

BTGattDesc org.direct_bt.BTGattChar.findGattDesc ( final String desc_uuid )

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

Implemented in jau.direct_bt.DBTGattChar.

◆ getClientCharConfig()

BTGattDesc org.direct_bt.BTGattChar.getClientCharConfig ( )

Return the Client Characteristic Configuration BTGattDesc if available or null.

The BTGattDesc#UUID128#CCC_DESC has been indexed while retrieving the GATT database from the server.

Implemented in jau.direct_bt.DBTGattChar.

◆ getUserDescription()

BTGattDesc org.direct_bt.BTGattChar.getUserDescription ( )

Return the User Description BTGattDesc if available or null.

The BTGattDesc#UUID128#USER_DESC has been indexed while retrieving the GATT database from the server.

Implemented in jau.direct_bt.DBTGattChar.

◆ configNotificationIndication()

boolean org.direct_bt.BTGattChar.configNotificationIndication	(	final boolean	enableNotification,
		final boolean	enableIndication,
		final boolean	enabledState[]
	)		throws IllegalStateException

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 GATTDescriptor 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 GATTHandler is null, i.e. not connected

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ enableNotificationOrIndication()

boolean org.direct_bt.BTGattChar.enableNotificationOrIndication ( final boolean enabledState[] ) throws IllegalStateException

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 GATTDescriptor 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 GATTHandler is null, i.e. not connected

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ disableIndicationNotification()

boolean org.direct_bt.BTGattChar.disableIndicationNotification ( ) throws IllegalStateException

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.

Exceptions

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

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTGattChar.

Here is the caller graph for this function:

◆ addCharListener() [1/2]

boolean org.direct_bt.BTGattChar.addCharListener ( final BTGattCharListener listener ) throws IllegalStateException

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

Occurring notifications and indications for this characteristic, if enabled via configNotificationIndication(boolean, boolean, boolean[]) or enableNotificationOrIndication(boolean[]), 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.

Parameters

listener A BTGattCharListener} instance, listening to this BTGattChar's events

Returns: if successful, true is being returned, otherwise false.

Exceptions

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

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTGattChar.

◆ addCharListener() [2/2]

boolean org.direct_bt.BTGattChar.addCharListener	(	final BTGattCharListener	listener,
		final boolean	enabledState[]
	)		throws IllegalStateException

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(boolean[]) 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

listener	A `BTGattChar.Listener` instance, listening to this `BTGattChar`'s events
enabledState	array of size 2, holding the resulting enabled state for notification and indication using `enableNotificationOrIndication(boolean[])`

Returns: if successful, true is being returned, otherwise false.

Exceptions

IllegalStateException	if the `BTDevice`'s GATTHandler is null, i.e. not connected
IllegalStateException	if the given `BTGattChar.Listener` is already in use, i.e. added.

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTGattChar.

◆ removeCharListener()

boolean org.direct_bt.BTGattChar.removeCharListener ( final BTGattCharListener listener )

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

listener returned BTGattCharListener from addCharListener(Listener) ...

Returns: true if successful, otherwise false.

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTGattChar.

Here is the caller graph for this function:

◆ removeAllAssociatedCharListener()

int org.direct_bt.BTGattChar.removeAllAssociatedCharListener ( final boolean shallDisableIndicationNotification )

Disables the notification and/or indication for this characteristic BLE level if disableIndicationNotification == true and removes all associated BTGattChar.Listener or BTGattCharListener from the listener list, which are associated with this characteristic instance.

If the DBTDevice's GATTHandler is null, i.e. not connected, false is being returned.

Parameters

shallDisableIndicationNotification if true, disables the notification and/or indication for this characteristic using disableIndicationNotification()

Returns: number of removed listener.

See also: disableIndicationNotification(); enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(BTGattCharListener) #see addCharListener(BTGattCharListener, boolean[]); removeCharListener(BTGattCharListener); removeAllAssociatedCharListener(boolean)

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ getUUID()

String org.direct_bt.BTGattChar.getUUID ( )

Get the UUID of this characteristic.

Returns: The 128 byte UUID of this characteristic, NULL if an error occurred

Implemented in jau.direct_bt.DBTGattChar.

◆ getService()

BTGattService org.direct_bt.BTGattChar.getService ( )

Returns the service to which this characteristic belongs to.

Returns: The service.

Implemented in jau.direct_bt.DBTGattChar.

◆ getNotifying()

boolean org.direct_bt.BTGattChar.getNotifying ( final boolean enabledState[] )

Returns true if notification for changes of this characteristic are activated.

Parameters

enabledState array of size 2, storage for the current enabled state for notification and indication.

Returns: True if either notification or indication is enabled

Implemented in jau.direct_bt.DBTGattChar.

◆ getProperties()

GattCharPropertySet org.direct_bt.BTGattChar.getProperties ( )

Returns the properties of this characteristic.

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

Implemented in jau.direct_bt.DBTGattChar.

◆ getDescriptors()

List< BTGattDesc > org.direct_bt.BTGattChar.getDescriptors ( )

Returns a list of BluetoothGattDescriptors this characteristic exposes.

Returns: A list of BluetoothGattDescriptors exposed by this characteristic NULL if an error occurred

Implemented in jau.direct_bt.DBTGattChar.

◆ readValue()

byte[] org.direct_bt.BTGattChar.readValue ( ) throws BTException

Reads the value of this characteristic.

Returns: A std::vector<unsgined char> containing the value of this characteristic.

Implemented in jau.direct_bt.DBTGattChar.

◆ writeValue()

boolean org.direct_bt.BTGattChar.writeValue	(	byte[]	argValue,
		boolean	withResponse
	)		throws BTException

Writes the value of this characteristic, using one of the following methods depending on withResponse @endiliteral.

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

Parameters

[in]	arg_value	The data as vector<uchar> to be written packed in a GBytes struct
	withResponse	if `true` a subsequent ATT_WRITE_RSP is expected, otherwise not.

Returns: TRUE if value was written successfully

Since: 2.0.0 @implNote withResponse parameter has been added since 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ toString()

String org.direct_bt.BTGattChar.toString ( )

Implemented in jau.direct_bt.DBTGattChar.

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

java/org/direct_bt/BTGattChar.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ findGattDesc()

◆ getClientCharConfig()

◆ getUserDescription()

◆ configNotificationIndication()

◆ enableNotificationOrIndication()

◆ disableIndicationNotification()

◆ addCharListener() [1/2]

◆ addCharListener() [2/2]

◆ removeCharListener()

◆ removeAllAssociatedCharListener()

◆ getUUID()

◆ getService()

◆ getNotifying()

◆ getProperties()

◆ getDescriptors()

◆ readValue()

◆ writeValue()

◆ toString()