MozillaWiki

B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic

< B2G‎ | Bluetooth‎ | WebBluetooth-v2
Revision as of 09:23, 11 September 2014 by Btian (talk | contribs) (→‎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

BluetoothGattCharacteristic

[CheckPermissions="bluetooth"]
interface BluetoothGattCharacteristic
{
  // Permission
  const unsigned short PERMISSION_READ              = 0x0001;
  const unsigned short PERMISSION_READ_ENCRYPTED    = 0x0002;
  const unsigned short PERMISSION_READ_ENC_MITM     = 0x0004;
  const unsigned short PERMISSION_WRITE             = 0x0010;
  const unsigned short PERMISSION_WRITE_ENCRYPTED   = 0x0020;
  const unsigned short PERMISSION_WRITE_ENC_MITM    = 0x0040;
  const unsigned short PERMISSION_WRITE_SIGNED      = 0x0080;
  const unsigned short PERMISSION_WRITE_SIGNED_MITM = 0x0100;

  // Property
  const unsigned short PROPERTY_BROADCAST         = 0x0001;
  const unsigned short PROPERTY_READ              = 0x0002;
  const unsigned short PROPERTY_WRITE_NO_RESPONSE = 0x0004;
  const unsigned short PROPERTY_WRITE             = 0x0008;
  const unsigned short PROPERTY_NOTIFY            = 0x0010;
  const unsigned short PROPERTY_INDICATE          = 0x0020;
  const unsigned short PROPERTY_SIGNED_WRITE      = 0x0040;
  const unsigned short PROPERTY_EXTENDED_PROPS    = 0x0080;

  // Write Type
  const unsigned short WRITE_TYPE_NO_RESPONSE     = 0x0001;
  const unsigned short WRITE_TYPE_DEFAULT         = 0x0002;
  const unsigned short WRITE_TYPE_SIGNED          = 0x0004;

  readonly attribute BluetoothGattService                  service;
  [Cached, Pure]
  readonly attribute sequence<BluetoothGattDescriptor>     descriptors;
  readonly attribute DOMString                             uuid;
  readonly attribute unsigned short                        instanceId;
  readonly attribute unsigned short                        permissions;
  readonly attribute unsigned short                        properties;
           attribute unsigned short                        writeType;
  readonly attribute ArrayBuffer?                          value;

  [NewObject, Throws]
  Promise<ArrayBuffer> readValue();
  [NewObject, Throws]
  Promise<ArrayBuffer> writeValue(ArrayBuffer value);
  [NewObject, Throws]
  Promise<void> startNotifications();
  [NewObject, Throws]
  Promise<void> stopNotifications();
  BluetoothGattDescriptor? findDescriptor(DOMString uuid);
};

Properties

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

permissions

Description
A bit mask which describes the security level required for read/write accesses of this characteristic.
Value Type
unsigned short
Default Value
0

properties

Description
A bit mask which describes how the characteristic value can be used.
Value Type
unsigned short
Default Value
0

writeType

Description
The type of write operation.
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

Methods

readValue()

Description
Read the characteristic value from the remote device.
The cached value property will also be updated after retrieving the valuethe remote device.
Returnthe remote device
A Promise to indicate whether the operation is resolved or rejected.
The Promise is resolved along with the value retrieved from the remote device.

writeValue(ArrayBuffer value)

Description
Write the characteristic value to the remote device.
Parameter
value
Desired value to be written to the remote device.
Return
A Promise to indicate whether the operation is resolved or rejected.
The Promise is resolved along with the characteristic value after this write operation.

startNotifications()

Description
Register notification/indication of this characteristic.
Return
A Promise to indicate whether the operation is resolved or rejected.
The Promise will be 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 will be rejected if there is no Client Characteristic Configuration descriptor (CCCD) for this characteristic.

findDescriptor(DOMString uuid)

Description
The method finds a descriptor of this characteristic from the descriptors property by the given UUID.
When there are multiple descriptors with the same UUID existed, the first one will be returned.
Parameters
uuid
UUID DOMString of the descriptor to seek for.
Return
The first descriptor with the given uuid in descriptors property.
A null pointer is returned if no descriptor is found by the given uuid.
Sample
const HEART_RATE_SERVICE = "0000180d-0000-1000-8000-00805f9b34fb";
const HEART_RATE_MEASUREMENT = "00002a37-0000-1000-8000-00805f9b34fb";
const CLIENT_CHAR_CONFIG = "00002902-0000-1000-8000-00805f9b34fb";

if (device.gatt) {
  // get heart rate service
  var heartRateService = device.gatt.findService(HEART_RATE_SERVICE));

  // get heart rate measurement characteristic from service
  if (heartRateService) {
    var heartRateMeasurement = 
      heartRateService.findCharacteristic(HEART_RATE_MEASUREMENT);

    // get Client Characteristic Configuration descriptor from characteristic
    if (heartRateMeasurement) {    
      var cccd = heartRateMeasurement.findDescriptor(CLIENT_CHAR_CONFIG);
    }
  }
}
Retrieved from "https://wiki.mozilla.org/index.php?title=B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic&oldid=1014172"