public class GattCharacteristic

Object
GattCharacteristic

A characteristic of a remote GattService – the unit of data exchange with a BLE peripheral. Read, write and subscribe operations are routed through the owning peripheral’s internal operation queue, so any number of calls may be issued concurrently; they execute in order.

Instances are constructed by the port during service discovery; application code never creates them.

Fields

`public static final int PROPERTY_BROADCAST = 1`	The characteristic supports broadcast (bit `0x01`).
`public static final int PROPERTY_READ = 2`	The characteristic can be read (bit `0x02`).
`public static final int PROPERTY_WRITE_WITHOUT_RESPONSE = 4`	The characteristic can be written without response (bit `0x04`).
`public static final int PROPERTY_WRITE = 8`	The characteristic can be written with response (bit `0x08`).
`public static final int PROPERTY_NOTIFY = 16`	The characteristic supports notifications (bit `0x10`).
`public static final int PROPERTY_INDICATE = 32`	The characteristic supports indications (bit `0x20`).
`public static final int PROPERTY_SIGNED_WRITE = 64`	The characteristic supports signed writes (bit `0x40`).
`public static final int PROPERTY_EXTENDED_PROPS = 128`	The characteristic has extended properties (bit `0x80`).

Constructors

public GattCharacteristic(GattService service, BluetoothUuid uuid, int properties, int instanceId) Constructed by ports during service discovery; not application API.

Methods

`public` `BluetoothUuid getUuid()`	The UUID identifying this characteristic.
`public` `GattService getService()`	The service this characteristic belongs to.
`public int getProperties()`	The raw `PROPERTY_*` bitmask as advertised by the peripheral.
`public int getInstanceId()`	Disambiguates multiple instances of the same characteristic UUID within one service.
`public boolean canRead()`	`true` when `PROPERTY_READ` is set.
`public boolean canWrite()`	`true` when `PROPERTY_WRITE` is set.
`public boolean canWriteWithoutResponse()`	`true` when `PROPERTY_WRITE_WITHOUT_RESPONSE` is set.
`public boolean canNotify()`	`true` when `PROPERTY_NOTIFY` is set.
`public boolean canIndicate()`	`true` when `PROPERTY_INDICATE` is set.
`public` `List<GattDescriptor> getDescriptors()`	The descriptors of this characteristic, in discovery order.
`public` `GattDescriptor getDescriptor(BluetoothUuid uuid)`	The first descriptor with the given UUID, or `null`.
`public void addDescriptor(GattDescriptor descriptor)`	Called by ports while building the discovered GATT database; not application API.
`public` `AsyncResource<byte[]> read()`	Reads the current value.
`public` `AsyncResource<Boolean> write(byte[] value)`	Writes the value with response.
`public` `AsyncResource<Boolean> writeWithoutResponse(byte[] value)`	Writes the value without response.
`public` `AsyncResource<Boolean> subscribe(GattNotificationListener l)`	Subscribes to value changes.
`public` `AsyncResource<Boolean> unsubscribe(GattNotificationListener l)`	Removes a listener added via `subscribe(GattNotificationListener)`.
`public boolean isSubscribed()`	`true` while notifications/indications are armed for this characteristic.
`public` `String toString()`	Returns a string representation of the object.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait, clone

Field details

PROPERTY_BROADCAST

public static final int PROPERTY_BROADCAST = 1

The characteristic supports broadcast (bit 0x01).

PROPERTY_READ

public static final int PROPERTY_READ = 2

The characteristic can be read (bit 0x02).

PROPERTY_WRITE_WITHOUT_RESPONSE

public static final int PROPERTY_WRITE_WITHOUT_RESPONSE = 4

The characteristic can be written without response (bit 0x04).

PROPERTY_WRITE

public static final int PROPERTY_WRITE = 8

The characteristic can be written with response (bit 0x08).

PROPERTY_NOTIFY

public static final int PROPERTY_NOTIFY = 16

The characteristic supports notifications (bit 0x10).

PROPERTY_INDICATE

public static final int PROPERTY_INDICATE = 32

The characteristic supports indications (bit 0x20).

PROPERTY_SIGNED_WRITE

public static final int PROPERTY_SIGNED_WRITE = 64

The characteristic supports signed writes (bit 0x40).

PROPERTY_EXTENDED_PROPS

public static final int PROPERTY_EXTENDED_PROPS = 128

The characteristic has extended properties (bit 0x80).

Constructor details

GattCharacteristic

public GattCharacteristic(GattService service, BluetoothUuid uuid, int properties, int instanceId)

Constructed by ports during service discovery; not application API.

Method details

getUuid

public BluetoothUuid getUuid()

The UUID identifying this characteristic.

getService

public GattService getService()

The service this characteristic belongs to.

getProperties

public int getProperties()

The raw PROPERTY_* bitmask as advertised by the peripheral.

getInstanceId

public int getInstanceId()

Disambiguates multiple instances of the same characteristic UUID within one service.

canRead

public boolean canRead()

true when PROPERTY_READ is set.

canWrite

public boolean canWrite()

true when PROPERTY_WRITE is set.

canWriteWithoutResponse

public boolean canWriteWithoutResponse()

true when PROPERTY_WRITE_WITHOUT_RESPONSE is set.

canNotify

public boolean canNotify()

true when PROPERTY_NOTIFY is set.

canIndicate

public boolean canIndicate()

true when PROPERTY_INDICATE is set.

getDescriptors

public List<GattDescriptor> getDescriptors()

The descriptors of this characteristic, in discovery order.

getDescriptor

public GattDescriptor getDescriptor(BluetoothUuid uuid)

The first descriptor with the given UUID, or null.

addDescriptor

public void addDescriptor(GattDescriptor descriptor)

Called by ports while building the discovered GATT database; not application API.

read

public AsyncResource<byte[]> read()

Reads the current value. Resolves with the raw bytes on the EDT or fails with a BluetoothException.

write

public AsyncResource<Boolean> write(byte[] value)

Writes the value with response. Resolves true on the EDT once the peripheral acknowledged the write.

writeWithoutResponse

public AsyncResource<Boolean> writeWithoutResponse(byte[] value)

Writes the value without response. Resolves true once the value was queued to the controller – there is no remote acknowledgement.

public AsyncResource<Boolean> subscribe(GattNotificationListener l)

Subscribes to value changes. The first listener triggers the CCCD write that arms notifications (indications are used when the characteristic only supports PROPERTY_INDICATE); the returned resource resolves true once armed. Additional listeners resolve immediately. Values stream to the listener on the EDT until unsubscribe(GattNotificationListener) or disconnection.

unsubscribe

public AsyncResource<Boolean> unsubscribe(GattNotificationListener l)

Removes a listener added via subscribe(GattNotificationListener). When the last listener is removed the CCCD is written to disarm notifications; the returned resource resolves once done.

isSubscribed

public boolean isSubscribed()

true while notifications/indications are armed for this characteristic.

toString

public String toString()

Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())