MozillaWiki

B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic: Difference between revisions

Page Discussion

B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic (view source)

Revision as of 09:30, 9 September 2015

264 bytes added ,  9 September 2015
revise descriptor of readValue in GattCharacteristic
(revise descriptor of readValue in GattCharacteristic)
 
(48 intermediate revisions by 4 users not shown)
Line 3: Line 3:


== Interfaces ==
== Interfaces ==
[[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#BluetoothGattCharacteristic|BluetoothGattCharacteristic]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#BluetoothGattCharacteristic|BluetoothGattCharacteristic]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattPermissions|GattPermissions]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattCharacteristicProperties|GattCharacteristicProperties]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#WriteType|WriteType]]


=== BluetoothGattCharacteristic ===
=== BluetoothGattCharacteristic ===
  [CheckPermissions="bluetooth"]
  [CheckPermissions="bluetooth"]
  interface BluetoothGattCharacteristic
  interface BluetoothGattCharacteristic
  {
  {  
   // Permission
   readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattService#BluetoothGattService|BluetoothGattService]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#service|service]];
  const unsigned short PERMISSION_READ              = 0x0001;
   [Cached, Pure] readonly attribute sequence<[[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattDescriptor#BluetoothGattDescriptor|BluetoothGattDescriptor]]> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#descriptors|descriptors]];
   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
   readonly attribute DOMString [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#uuid|uuid]];
  const unsigned short PROPERTY_BROADCAST        = 0x0001;
   readonly attribute unsigned short [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#instanceId|instanceId]];
   const unsigned short PROPERTY_READ              = 0x0002;
   readonly attribute ArrayBuffer? [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#value|value]];
   const unsigned short PROPERTY_WRITE_NO_RESPONSE = 0x0004;
   [Cached, Constant] readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattPermissions|GattPermissions]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#permissions_2|permissions]];
   const unsigned short PROPERTY_WRITE            = 0x0008;
   [Cached, Constant] readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattCharacteristicProperties|GattCharacteristicProperties]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#properties_2|properties]];
   const unsigned short PROPERTY_NOTIFY            = 0x0010;
   [Cached, Pure]              attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#WriteType|WriteType]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeType|writeType]];
   const unsigned short PROPERTY_INDICATE          = 0x0020;
  const unsigned short PROPERTY_SIGNED_WRITE      = 0x0040;
  const unsigned short PROPERTY_EXTENDED_PROPS    = 0x0080;
   
   
  // Write Type
   [NewObject] Promise<ArrayBuffer> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#readValue.28.29|readValue()]];
  const unsigned short WRITE_TYPE_NO_RESPONSE    = 0x0001;
   [NewObject] Promise<void> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeValue.28ArrayBuffer value.29|writeValue(ArrayBuffer value)]];
  const unsigned short WRITE_TYPE_DEFAULT        = 0x0002;
   [NewObject] Promise<void> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#startNotifications.28.29|startNotifications()]];
  const unsigned short WRITE_TYPE_SIGNED          = 0x0004;
   [NewObject] Promise<void> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#stopNotifications.28.29|stopNotifications()]];
   [NewObject] Promise<[[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattDescriptor#BluetoothGattDescriptor|BluetoothGattDescriptor]]> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#addDescriptor.28DOMString_uuid.2C_GattPermissions_permissions.2C_ArrayBuffer_value.29|addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value)]];
  readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattService#BluetoothGattService|BluetoothGattService]]                  [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#service|service]];
};
  [Cached, Pure]
 
  readonly attribute sequence<[[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattDescriptor#BluetoothGattDescriptor|BluetoothGattDescriptor]]>    [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#descriptors|descriptors]];
=== GattPermissions ===
  readonly attribute DOMString                            [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#uuid|uuid]];
dictionary GattPermissions
  readonly attribute unsigned short                        [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#instanceId|instanceId]];
{
  readonly attribute unsigned short                        [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#permissions|permissions]];
  boolean read = false;
  readonly attribute unsigned short                        [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#properties_2|properties]];
  boolean readEncrypted = false;
            attribute unsigned short                        [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeType|writeType]];
  boolean readEncryptedMITM = false;
  readonly attribute ArrayBuffer?                          [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#value|value]];
  boolean write = false;
  boolean writeEncrypted = false;
   [NewObject, Throws]
  boolean writeEncryptedMITM = false;
  Promise<ArrayBuffer> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#readValue.28.29|readValue()]];
  boolean writeSigned = false;
   [NewObject, Throws]
  boolean writeSignedMITM = false;
  Promise<ArrayBuffer> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeValue.28ArrayBuffer value.29|writeValue(ArrayBuffer value)]];
};
   [NewObject, Throws]
 
  Promise<void> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#startNotification.28.29|startNotifications()]];
=== GattCharacteristicProperties ===
   [NewObject, Throws]
dictionary GattCharacteristicProperties
  Promise<void> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#stopNotification.28.29|stopNotifications()]];
{
   [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattDescriptor#BluetoothGattDescriptor|BluetoothGattDescriptor]]? [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#findDescriptor.28DOMString uuid.29|findDescriptor(DOMString uuid)]];
  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;
  };
  };


== Properties ==
== GattCharacteristicProperties ==
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#service|BluetoothGattCharacteristic.service]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#service|BluetoothGattCharacteristic.service]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#descriptors|BluetoothGattCharacteristic.descriptors]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#descriptors|BluetoothGattCharacteristic.descriptors]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#uuid|BluetoothGattCharacteristic.uuid]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#uuid|BluetoothGattCharacteristic.uuid]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#instanceId|BluetoothGattCharacteristic.instanceId]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#instanceId|BluetoothGattCharacteristic.instanceId]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#permissions|BluetoothGattCharacteristic.permissions]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#properties|BluetoothGattCharacteristic.properties]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeType|BluetoothGattCharacteristic.writeType]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#value|BluetoothGattCharacteristic.value]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#value|BluetoothGattCharacteristic.value]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#permissions_2|BluetoothGattCharacteristic.permissions]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#properties_3|BluetoothGattCharacteristic.properties]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#writeType_2|BluetoothGattCharacteristic.writeType]]


=== service ===
=== service ===
Line 109: Line 117:
: 0
: 0


=== permissions ===
=== value ===


; Description
; Description
: A bit mask which describes the security level required for read/write accesses of this characteristic.
: 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
; Value Type
: unsigned short
: ArrayBuffer or null


; Default Value
; Default Value
: 0
: null pointer


=== properties ===
=== permissions ===


; Description
; Description
: A bit mask which describes how the characteristic value can be used.
: A bit mask which describes allowed operations on the characteristic.


; Value Type
; Value Type
: unsigned short
: dictionary [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattPermissions|GattPermissions]]


; Default Value
; Default Value
: 0
: 0


=== writeType ===
=== properties ===


; Description
; Description
: The type of write operation.
: A bit mask which describes how to use the characteristic value.


; Value Type
; Value Type
: unsigned short
: dictionary [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattCharacteristicProperties|GattCharacteristicProperties]]


; Default Value
; Default Value
: 0
: 0


=== value ===
=== writeType ===


; Description
; Description
: The cached value of this characteristic.
: The type of write operation.
: This value can be updated via readValue() method or via characteristic notification or indication from the remote device.


; Value Type
; Value Type
: ArrayBuffer or null
: dictionary [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#WriteType|WriteType]]


; Default Value
; Default Value
: null pointer
: 0


== Methods ==
== Methods ==
Line 159: Line 166:
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#startNotifications.28.29|BluetoothGattCharacteristic.startNotifications()]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#startNotifications.28.29|BluetoothGattCharacteristic.startNotifications()]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#stopNotifications.28.29|BluetoothGattCharacteristic.stopNotifications()]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#stopNotifications.28.29|BluetoothGattCharacteristic.stopNotifications()]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#findDescriptor.28DOMString uuid.29|BluetoothGattCharacteristic.findDescriptor(DOMString uuid)]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#addDescriptor.28DOMString_uuid.2C_GattPermissions_permissions.2C_ArrayBuffer_value.29|addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value)]]


=== readValue() ===
=== readValue() ===


; Description
; Description
: Read the characteristic value from the remote device. The cached value property will also be updated after retrieving the value.
: 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
; 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.
: 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) ===
=== writeValue(ArrayBuffer value) ===


; Description
; Description
: Write the characteristic value to the remote device.
: 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 [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#value|value]].


; Parameter
; Parameter
: ''value''
: ''value''
:: Desired value to be written to the remote device.
:: Desired value to be written to the GATT server.


; Return
; 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.
: A Promise to indicate whether the operation is resolved or rejected.


=== startNotifications() ===
=== startNotifications() ===
Line 197: Line 204:
: 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.
: 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.


=== findDescriptor(DOMString uuid) ===
=== addDescriptor(DOMString uuid, GattPermissions permissions, ArrayBuffer value) ===


; Description
; Description
: The method finds a descriptor of this characteristic from the descriptors property by the given UUID. When multiple descriptors with the same UUID exist, the first one is returned.
: Adds a descriptor to this characteristic.


; Parameters
; Parameter
: ''uuid''
: ''uuid''
:: UUID DOMString of the descriptor to seek for.
:: UUID of the descriptor to add.
: ''permissions''
:: [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#GattPermissions|GattPermissions]] of the descriptor to add.
: ''value''
:: The initial value of this descriptor.


; Return
; Return
: The first descriptor with the given uuid in descriptors property.  
: A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns the added [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattDescriptor#BluetoothGattDescriptor|BluetoothGattDescriptor]] object, and property [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic#descriptors|descriptors]] is also updated with the added descriptor.
: 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);
    }
  }
}
Joliu
120

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/1014418...1094381"