B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic

Overview

BluetoothGattCharacteristic represents the characteristic of services. BluetoothGattCharacteristic consists of the characteristic definition, a characteristic value along with properties and configurations which indicate how to access the value, and a list of descriptors which provides related information of this characteristic value.

Interfaces

• BluetoothGattCharacteristic
• GattPermissions
• GattCharacteristicProperties
• WriteType

BluetoothGattCharacteristic

[CheckPermissions="bluetooth"]
interface BluetoothGattCharacteristic
{ 
  readonly attribute BluetoothGattService service;
  [Cached, Pure] readonly attribute sequence<BluetoothGattDescriptor> descriptors;

  readonly attribute DOMString uuid;
  readonly attribute unsigned short instanceId;
  readonly attribute ArrayBuffer? value;
  [Cached, Constant] readonly attribute GattPermissions permissions;
  [Cached, Constant] readonly attribute GattCharacteristicProperties properties;
  [Cached, Pure]              attribute WriteType writeType;

  [NewObject] Promise<ArrayBuffer> readValue();
  [NewObject] Promise<void> writeValue(ArrayBuffer value);
  [NewObject] Promise<void> startNotifications();
  [NewObject] Promise<void> stopNotifications();
  [NewObject] Promise<BluetoothGattDescriptor> addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value);
};

GattPermissions

dictionary GattPermissions
{
  boolean read = false;
  boolean readEncrypted = false;
  boolean readEncryptedMITM = false;
  boolean write = false;
  boolean writeEncrypted = false;
  boolean writeEncryptedMITM = false;
  boolean writeSigned = false;
  boolean writeSignedMITM = false;
};

GattCharacteristicProperties

dictionary GattCharacteristicProperties
{
  boolean broadcast = false;
  boolean read = false;
  boolean writeNoResponse = false;
  boolean write = false;
  boolean notify = false;
  boolean indicate = false;
  boolean signedWrite = false;
  boolean extendedProps = false;
};

WriteType

dictionary WriteType
{
  required boolean noResponse;
  required boolean default;
  required boolean signed;
};

GattCharacteristicProperties

• BluetoothGattCharacteristic.service
• BluetoothGattCharacteristic.descriptors
• BluetoothGattCharacteristic.uuid
• BluetoothGattCharacteristic.instanceId
• BluetoothGattCharacteristic.value
• BluetoothGattCharacteristic.permissions
• BluetoothGattCharacteristic.properties
• BluetoothGattCharacteristic.writeType

service

Description

The service which this characteristic belongs to.

Value Type

BluetoothGattService

Default Value

null pointer

descriptors

Description

A cached descriptor array of this characteristic.

Value Type

sequence<BluetoothGattDescriptor>

Default Value

Empty array (array with length = 0)

uuid

Description

This property stores the UUID of this characteristic.

Value Type

DOMString

Default Value

Empty string ("")

instanceId

Description

This property stores the instance id of this characteristic.

Value Type

unsigned short

Default Value

0

value

Description

The cached value of this characteristic. This value can be updated via readValue() method or via characteristic notification or indication from the remote device.

Value Type

ArrayBuffer or null

Default Value

null pointer

permissions

Description

A bit mask which describes allowed operations on the characteristic.

Value Type

dictionary GattPermissions

Default Value

0

properties

Description

A bit mask which describes how to use the characteristic value.

Value Type

dictionary GattCharacteristicProperties

Default Value

0

writeType

Description

The type of write operation.

Value Type

dictionary WriteType

Default Value

0

Methods

• BluetoothGattCharacteristic.readValue()
• BluetoothGattCharacteristic.writeValue(ArrayBuffer value)
• BluetoothGattCharacteristic.startNotifications()
• BluetoothGattCharacteristic.stopNotifications()
• addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value)

readValue()

Description

Read the characteristic value from either remote device (client role) or the local device (server role). In client mode, the cached value property will also be updated after retrieving the value from the remote GATT server.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is resolved along with the value retrieved from the remote device or local device.

writeValue(ArrayBuffer value)

Description

Write the characteristic value to the GATT server. If the local device is the GATT client, the value will be written to the remote GATT server. On the other hand, if the local device is the GATT server, the value will be written to value.

Parameter

value

Desired value to be written to the GATT server.

Return

A Promise to indicate whether the operation is resolved or rejected.

startNotifications()

Description

Register notification/indication of this characteristic.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is rejected if there is no Client Characteristic Configuration descriptor (CCCD) for this characteristic.

stopNotifications()

Description

Unregister notification/indication of this characteristic.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is rejected if there is no Client Characteristic Configuration descriptor (CCCD) for this characteristic.

addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value)

Description

Adds a descriptor to this characteristic.

Parameter

uuid

UUID of the descriptor to add.

permissions

GattPermissions of the descriptor to add.

value

The initial value of this descriptor.

Return

A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns the added BluetoothGattDescriptor object, and property descriptors is also updated with the added descriptor.