Provides access to Bluetooth GATT characteristic. More...

Inheritance diagram for org.direct_bt.BTGattChar:

Collaboration diagram for org.direct_bt.BTGattChar:

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

Public Member Functions
BTGattDesc	find (final String UUID, final long timeoutMS)
	Find a BluetoothGattDescriptor. More...

BTGattDesc	find (final String UUID)
	Find a BluetoothGattDescriptor. More...

byte[]	readValue () throws BTException
	Reads the value of this characteristic. 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	enableNotificationOrIndication (final boolean enabledState[]) throws IllegalStateException
	BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration. More...

boolean	addCharListener (final Listener listener) throws IllegalStateException
	Add the given BTGattChar.Listener to the listener list if not already present. More...

boolean	addCharListener (final Listener listener, final boolean enabledState[]) throws IllegalStateException
	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 (final boolean disableIndicationNotification)
	Disables the notification and/or indication for this characteristic BLE level if. More...

void	disableValueNotifications ()
	Disables notifications of the value and unregisters the callback object passed through the corresponding enable method. More...

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

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

BTGattService	getService ()
	Returns the service to which this characteristic belongs to. 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...

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

Public Member Functions inherited from org.direct_bt.BTObject
BTType	getBluetoothType ()
	Returns the BluetoothType of this object. More...

boolean	equals (Object obj)

int	hashCode ()

void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...

Detailed Description

Provides access to Bluetooth GATT characteristic.

See also: Bluetooth Specification; BlueZ GATT API

Definition at line 39 of file BTGattChar.java.

Member Function Documentation

◆ addCharListener() [1/2]

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

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

Implementation wraps given BTGattChar.Listener into a BTGattCharListener to restrict the listener to listen only to this BTGattChar instance.

Parameters

listener A BTGattChar.Listener instance, listening to this BTGattChar's events

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

Exceptions

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

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

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ addCharListener() [2/2]

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

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(boolean[]) to enable either.

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

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

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: enableNotificationOrIndication(boolean[]); configNotificationIndication(boolean, boolean, boolean[]); addCharListener(Listener); #removeCharListener(Listener, boolean); removeAllAssociatedCharListener(boolean)

Since: 2.0.0

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

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ disableValueNotifications()

void org.direct_bt.BTGattChar.disableValueNotifications ( )

Disables notifications of the value and unregisters the callback object passed through the corresponding enable method.

It disables notifcations at BLE level for this characteristic.

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

Since: 2.0.0

Implemented in jau.direct_bt.DBTGattChar.

◆ find() [1/2]

BTGattDesc org.direct_bt.BTGattChar.find ( final String UUID )

Find a BluetoothGattDescriptor.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattDescriptor you are waiting for

Returns: An object matching the UUID or null if not found before timeout expires or event is canceled.

Implemented in jau.direct_bt.DBTGattChar.

◆ find() [2/2]

BTGattDesc org.direct_bt.BTGattChar.find	(	final String	UUID,
		final long	timeoutMS
	)

Find a BluetoothGattDescriptor.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattDescriptor you are waiting for @parameter timeoutMS the function will return after timeout time in milliseconds, a value of zero means wait forever. If object is not found during this time null will be returned.

Returns: An object matching the UUID or null if not found before timeout expires or event is canceled.

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.

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

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

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

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

◆ removeAllAssociatedCharListener()

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

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

disableIndicationNotification if true, disables the notification and/or indication for this characteristic using configNotificationIndication(boolean, boolean, boolean[])

Returns: number of removed listener.

See also: configNotificationIndication(boolean, boolean, boolean[]); BTDevice::removeAllAssociatedCharListener(BTGattChar); addCharListener(Listener); addCharListener(Listener, boolean[]); #removeCharListener(Listener, boolean)

Since: 2.0.0

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

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.

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

/usr/local/projects/direct_bt/java/org/direct_bt/BTGattChar.java

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ addCharListener() [1/2]

◆ addCharListener() [2/2]

◆ configNotificationIndication()

◆ disableValueNotifications()

◆ enableNotificationOrIndication()

◆ find() [1/2]

◆ find() [2/2]

◆ getDescriptors()

◆ getNotifying()

◆ getProperties()

◆ getService()

◆ getUUID()

◆ readValue()

◆ removeAllAssociatedCharListener()

◆ writeValue()