Android APIs
public class

BluetoothGattCharacteristic

extends Object
java.lang.Object
   ↳ android.bluetooth.BluetoothGattCharacteristic

Class Overview

Represents a Bluetooth GATT Characteristic

A GATT characteristic is a basic data element used to construct a GATT service, BluetoothGattService. The characteristic contains a value as well as additional information and optional GATT descriptors, BluetoothGattDescriptor.

Summary

Constants
int FORMAT_FLOAT Characteristic value format type float (32-bit float)
int FORMAT_SFLOAT Characteristic value format type sfloat (16-bit float)
int FORMAT_SINT16 Characteristic value format type sint16
int FORMAT_SINT32 Characteristic value format type sint32
int FORMAT_SINT8 Characteristic value format type sint8
int FORMAT_UINT16 Characteristic value format type uint16
int FORMAT_UINT32 Characteristic value format type uint32
int FORMAT_UINT8 Characteristic value format type uint8
int PERMISSION_READ Characteristic read permission
int PERMISSION_READ_ENCRYPTED Characteristic permission: Allow encrypted read operations
int PERMISSION_READ_ENCRYPTED_MITM Characteristic permission: Allow reading with man-in-the-middle protection
int PERMISSION_WRITE Characteristic write permission
int PERMISSION_WRITE_ENCRYPTED Characteristic permission: Allow encrypted writes
int PERMISSION_WRITE_ENCRYPTED_MITM Characteristic permission: Allow encrypted writes with man-in-the-middle protection
int PERMISSION_WRITE_SIGNED Characteristic permission: Allow signed write operations
int PERMISSION_WRITE_SIGNED_MITM Characteristic permission: Allow signed write operations with man-in-the-middle protection
int PROPERTY_BROADCAST Characteristic proprty: Characteristic is broadcastable.
int PROPERTY_EXTENDED_PROPS Characteristic property: Characteristic has extended properties
int PROPERTY_INDICATE Characteristic property: Characteristic supports indication
int PROPERTY_NOTIFY Characteristic property: Characteristic supports notification
int PROPERTY_READ Characteristic property: Characteristic is readable.
int PROPERTY_SIGNED_WRITE Characteristic property: Characteristic supports write with signature
int PROPERTY_WRITE Characteristic property: Characteristic can be written.
int PROPERTY_WRITE_NO_RESPONSE Characteristic property: Characteristic can be written without response.
int WRITE_TYPE_DEFAULT Write characteristic, requesting acknoledgement by the remote device
int WRITE_TYPE_NO_RESPONSE Wrtite characteristic without requiring a response by the remote device
int WRITE_TYPE_SIGNED Write characteristic including authentication signature
Fields
protected List<BluetoothGattDescriptor> mDescriptors List of descriptors included in this characteristic.
Public Constructors
BluetoothGattCharacteristic(UUID uuid, int properties, int permissions)
Create a new BluetoothGattCharacteristic.
Public Methods
boolean addDescriptor(BluetoothGattDescriptor descriptor)
Adds a descriptor to this characteristic.
BluetoothGattDescriptor getDescriptor(UUID uuid)
Returns a descriptor with a given UUID out of the list of descriptors for this characteristic.
List<BluetoothGattDescriptor> getDescriptors()
Returns a list of descriptors for this characteristic.
Float getFloatValue(int formatType, int offset)
Return the stored value of this characteristic.
int getInstanceId()
Returns the instance ID for this characteristic.
Integer getIntValue(int formatType, int offset)
Return the stored value of this characteristic.
int getPermissions()
Returns the permissions for this characteristic.
int getProperties()
Returns the properties of this characteristic.
BluetoothGattService getService()
Returns the service this characteristic belongs to.
String getStringValue(int offset)
Return the stored value of this characteristic.
UUID getUuid()
Returns the UUID of this characteristic
byte[] getValue()
Get the stored value for this characteristic.
int getWriteType()
Gets the write type for this characteristic.
boolean setValue(int value, int formatType, int offset)
Set the locally stored value of this characteristic.
boolean setValue(byte[] value)
Updates the locally stored value of this characteristic.
boolean setValue(String value)
Set the locally stored value of this characteristic.
boolean setValue(int mantissa, int exponent, int formatType, int offset)
Set the locally stored value of this characteristic.
void setWriteType(int writeType)
Set the write type for this characteristic

Setting the write type of a characteristic determines how the writeCharacteristic(BluetoothGattCharacteristic) function write this characteristic.

[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int FORMAT_FLOAT

Added in API level 18

Characteristic value format type float (32-bit float)

Constant Value: 52 (0x00000034)

public static final int FORMAT_SFLOAT

Added in API level 18

Characteristic value format type sfloat (16-bit float)

Constant Value: 50 (0x00000032)

public static final int FORMAT_SINT16

Added in API level 18

Characteristic value format type sint16

Constant Value: 34 (0x00000022)

public static final int FORMAT_SINT32

Added in API level 18

Characteristic value format type sint32

Constant Value: 36 (0x00000024)

public static final int FORMAT_SINT8

Added in API level 18

Characteristic value format type sint8

Constant Value: 33 (0x00000021)

public static final int FORMAT_UINT16

Added in API level 18

Characteristic value format type uint16

Constant Value: 18 (0x00000012)

public static final int FORMAT_UINT32

Added in API level 18

Characteristic value format type uint32

Constant Value: 20 (0x00000014)

public static final int FORMAT_UINT8

Added in API level 18

Characteristic value format type uint8

Constant Value: 17 (0x00000011)

public static final int PERMISSION_READ

Added in API level 18

Characteristic read permission

Constant Value: 1 (0x00000001)

public static final int PERMISSION_READ_ENCRYPTED

Added in API level 18

Characteristic permission: Allow encrypted read operations

Constant Value: 2 (0x00000002)

public static final int PERMISSION_READ_ENCRYPTED_MITM

Added in API level 18

Characteristic permission: Allow reading with man-in-the-middle protection

Constant Value: 4 (0x00000004)

public static final int PERMISSION_WRITE

Added in API level 18

Characteristic write permission

Constant Value: 16 (0x00000010)

public static final int PERMISSION_WRITE_ENCRYPTED

Added in API level 18

Characteristic permission: Allow encrypted writes

Constant Value: 32 (0x00000020)

public static final int PERMISSION_WRITE_ENCRYPTED_MITM

Added in API level 18

Characteristic permission: Allow encrypted writes with man-in-the-middle protection

Constant Value: 64 (0x00000040)

public static final int PERMISSION_WRITE_SIGNED

Added in API level 18

Characteristic permission: Allow signed write operations

Constant Value: 128 (0x00000080)

public static final int PERMISSION_WRITE_SIGNED_MITM

Added in API level 18

Characteristic permission: Allow signed write operations with man-in-the-middle protection

Constant Value: 256 (0x00000100)

public static final int PROPERTY_BROADCAST

Added in API level 18

Characteristic proprty: Characteristic is broadcastable.

Constant Value: 1 (0x00000001)

public static final int PROPERTY_EXTENDED_PROPS

Added in API level 18

Characteristic property: Characteristic has extended properties

Constant Value: 128 (0x00000080)

public static final int PROPERTY_INDICATE

Added in API level 18

Characteristic property: Characteristic supports indication

Constant Value: 32 (0x00000020)

public static final int PROPERTY_NOTIFY

Added in API level 18

Characteristic property: Characteristic supports notification

Constant Value: 16 (0x00000010)

public static final int PROPERTY_READ

Added in API level 18

Characteristic property: Characteristic is readable.

Constant Value: 2 (0x00000002)

public static final int PROPERTY_SIGNED_WRITE

Added in API level 18

Characteristic property: Characteristic supports write with signature

Constant Value: 64 (0x00000040)

public static final int PROPERTY_WRITE

Added in API level 18

Characteristic property: Characteristic can be written.

Constant Value: 8 (0x00000008)

public static final int PROPERTY_WRITE_NO_RESPONSE

Added in API level 18

Characteristic property: Characteristic can be written without response.

Constant Value: 4 (0x00000004)

public static final int WRITE_TYPE_DEFAULT

Added in API level 18

Write characteristic, requesting acknoledgement by the remote device

Constant Value: 2 (0x00000002)

public static final int WRITE_TYPE_NO_RESPONSE

Added in API level 18

Wrtite characteristic without requiring a response by the remote device

Constant Value: 1 (0x00000001)

public static final int WRITE_TYPE_SIGNED

Added in API level 18

Write characteristic including authentication signature

Constant Value: 4 (0x00000004)

Fields

protected List<BluetoothGattDescriptor> mDescriptors

Added in API level 18

List of descriptors included in this characteristic.

Public Constructors

public BluetoothGattCharacteristic (UUID uuid, int properties, int permissions)

Added in API level 18

Create a new BluetoothGattCharacteristic.

Requires BLUETOOTH permission.

Parameters
uuid The UUID for this characteristic
properties Properties of this characteristic
permissions Permissions for this characteristic

Public Methods

public boolean addDescriptor (BluetoothGattDescriptor descriptor)

Added in API level 18

Adds a descriptor to this characteristic.

Requires BLUETOOTH permission.

Parameters
descriptor Descriptor to be added to this characteristic.
Returns
  • true, if the descriptor was added to the characteristic

public BluetoothGattDescriptor getDescriptor (UUID uuid)

Added in API level 18

Returns a descriptor with a given UUID out of the list of descriptors for this characteristic.

Returns
  • GATT descriptor object or null if no descriptor with the given UUID was found.

public List<BluetoothGattDescriptor> getDescriptors ()

Added in API level 18

Returns a list of descriptors for this characteristic.

Returns
  • Descriptors for this characteristic

public Float getFloatValue (int formatType, int offset)

Added in API level 18

Return the stored value of this characteristic.

See getValue() for details.

Parameters
formatType The format type used to interpret the characteristic value.
offset Offset at which the float value can be found.
Returns
  • Cached value of the characteristic at a given offset or null if the requested offset exceeds the value size.

public int getInstanceId ()

Added in API level 18

Returns the instance ID for this characteristic.

If a remote device offers multiple characteristics with the same UUID, the instance ID is used to distuinguish between characteristics.

Returns
  • Instance ID of this characteristic

public Integer getIntValue (int formatType, int offset)

Added in API level 18

Return the stored value of this characteristic.

The formatType parameter determines how the characteristic value is to be interpreted. For example, settting formatType to FORMAT_UINT16 specifies that the first two bytes of the characteristic value at the given offset are interpreted to generate the return value.

Parameters
formatType The format type used to interpret the characteristic value.
offset Offset at which the integer value can be found.
Returns
  • Cached value of the characteristic or null of offset exceeds value size.

public int getPermissions ()

Added in API level 18

Returns the permissions for this characteristic.

Returns
  • Permissions of this characteristic

public int getProperties ()

Added in API level 18

Returns the properties of this characteristic.

The properties contain a bit mask of property flags indicating the features of this characteristic.

Returns
  • Properties of this characteristic

public BluetoothGattService getService ()

Added in API level 18

Returns the service this characteristic belongs to.

Returns
  • The asscociated service

public String getStringValue (int offset)

Added in API level 18

Return the stored value of this characteristic.

See getValue() for details.

Parameters
offset Offset at which the string value can be found.
Returns
  • Cached value of the characteristic

public UUID getUuid ()

Added in API level 18

Returns the UUID of this characteristic

Returns
  • UUID of this characteristic

public byte[] getValue ()

Added in API level 18

Get the stored value for this characteristic.

This function returns the stored value for this characteristic as retrieved by calling readCharacteristic(BluetoothGattCharacteristic). The cached value of the characteristic is updated as a result of a read characteristic operation or if a characteristic update notification has been received.

Returns
  • Cached value of the characteristic

public int getWriteType ()

Added in API level 18

Gets the write type for this characteristic.

Returns
  • Write type for this characteristic

public boolean setValue (int value, int formatType, int offset)

Added in API level 18

Set the locally stored value of this characteristic.

See setValue(byte[]) for details.

Parameters
value New value for this characteristic
formatType Integer format type used to transform the value parameter
offset Offset at which the value should be placed
Returns
  • true if the locally stored value has been set

public boolean setValue (byte[] value)

Added in API level 18

Updates the locally stored value of this characteristic.

This function modifies the locally stored cached value of this characteristic. To send the value to the remote device, call writeCharacteristic(BluetoothGattCharacteristic) to send the value to the remote device.

Parameters
value New value for this characteristic
Returns
  • true if the locally stored value has been set, false if the requested value could not be stored locally.

public boolean setValue (String value)

Added in API level 18

Set the locally stored value of this characteristic.

See setValue(byte[]) for details.

Parameters
value New value for this characteristic
Returns
  • true if the locally stored value has been set

public boolean setValue (int mantissa, int exponent, int formatType, int offset)

Added in API level 18

Set the locally stored value of this characteristic.

See setValue(byte[]) for details.

Parameters
mantissa Mantissa for this characteristic
exponent exponent value for this characteristic
formatType Float format type used to transform the value parameter
offset Offset at which the value should be placed
Returns
  • true if the locally stored value has been set

public void setWriteType (int writeType)

Added in API level 18

Set the write type for this characteristic

Setting the write type of a characteristic determines how the writeCharacteristic(BluetoothGattCharacteristic) function write this characteristic.

Parameters
writeType The write type to for this characteristic. Can be one of: WRITE_TYPE_DEFAULT, WRITE_TYPE_NO_RESPONSE or WRITE_TYPE_SIGNED.