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

From MozillaWiki
Jump to navigation Jump to search
m (Fix link to BluetoothGatt)
 
(72 intermediate revisions by 2 users not shown)
Line 2: Line 2:
'''BluetoothDevice''' provides information regarding a given remote bluetooth device.
'''BluetoothDevice''' provides information regarding a given remote bluetooth device.


== Interface ==
== Interfaces ==
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDevice|BluetoothDevice]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDevice|BluetoothDevice]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceAttribute|BluetoothDeviceAttribute]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceAttribute|BluetoothDeviceAttribute]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceType|BluetoothDeviceType]]


=== BluetoothDevice ===
=== BluetoothDevice ===
[CheckPermissions="bluetooth"]
  interface BluetoothDevice: EventTarget
  interface BluetoothDevice: EventTarget
  {
  {
   readonly attribute DOMString             [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#address|address]];
   readonly attribute DOMString [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#address|address]];
   readonly attribute BluetoothClassOfDevice [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#cod|cod]];
   readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothClassOfDevice|BluetoothClassOfDevice]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#cod|cod]];
   readonly attribute DOMString             [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#name|name]];
   readonly attribute DOMString [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#name|name]];
   readonly attribute boolean               [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#paired|paired]];
   readonly attribute boolean [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#paired|paired]];
   readonly attribute any                    [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#uuids|uuids]]; // array of DOMString
   [Cached, Pure] readonly attribute sequence<DOMString> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#uuids|uuids]];
  readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceType|BluetoothDeviceType]] [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#type|type]];
  readonly attribute [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt#BluetoothGatt|BluetoothGatt]]? [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#gatt|gatt]];
   
   
  attribute EventHandler [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#onattributechanged|onattributechanged]];
            attribute EventHandler [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#onattributechanged|onattributechanged]];
   
   
   // DOMString[]
   [NewObject] Promise<sequence<DOMString>> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]];
  Promise<any> [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]];
  };
  };
=== BluetoothDeviceType ===
enum BluetoothDeviceType
{
  "unknown",
  "classic",
  "le",
  "dual",
}


=== BluetoothDeviceAttribute ===
=== BluetoothDeviceAttribute ===
  enum BluetoothDeviceAttribute
  enum BluetoothDeviceAttribute
  {
  {
  "unknown",
   "cod",
   "cod",
   "name",
   "name",
Line 36: Line 49:
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#paired|BluetoothDevice.paired]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#paired|BluetoothDevice.paired]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#uuids|BluetoothDevice.uuids]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#uuids|BluetoothDevice.uuids]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#type|BluetoothDevice.type]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#gatt|BluetoothDevice.gatt]]


=== address ===
=== address ===
Line 49: Line 64:


; Sample
; Sample
  var address = ''instanceOfBluetoothDevice''.address;
  var address = device.address;


=== cod ===
=== cod ===
Line 63: Line 78:


; Sample
; Sample
  var cod = ''instanceOfBluetoothDevice''.cod;
  var cod = device.cod;
   
   
  var majorDeviceClass = cod.BluetoothMajorDeviceClass;
  var majorDeviceClass = cod.BluetoothMajorDeviceClass;
Line 81: Line 96:


; Sample
; Sample
  var name = ''instanceOfBluetoothDevice''.name;
  var name = device.name;


=== paired ===
=== paired ===
Line 95: Line 110:


; Sample
; Sample
  var paired = ''instanceOfBluetoothDevice''.paired;
  var paired = device.paired;


=== uuids ===
=== uuids ===


; Description
; Description
: The <tt>uuids</tt> property stores the cached UUID list of each bluetooth service that the remote device provides. If the up-to-date UUID list is required, call [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]] to update this attribute.
: [Cached, Pure]
: The property stores the cached UUID list of services that the remote device provides. If applications require the up-to-date UUID list is required, call [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]] to update this property. This property is marked with [Cached] because the same JS Array object is returned until a [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]] call happens, and marked with [Pure] rather than [Constant] because uuids is updated once [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#fetchUuids.28.29|fetchUuids()]] executes.


; Value type
; Value type
: An array of DOMString
: sequence<DOMString>


; Default value
; Default value
Line 109: Line 125:


; Sample
; Sample
  var uuids = ''instanceOfBluetoothDevice''.uuids;
  var uuids = device.uuids;
 
=== type ===
 
; Description
: The type property indicates the device type of the remote device.
 
; Value type
: [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceType|BluetoothDeviceType]]
 
; Default value
: BluetoothDeviceType.unknown
 
; Sample
var type = device.type;
 
=== gatt ===
 
; Description
: The gatt property is an object to conduct GATT client operations on this remote LE device. This property will be a null pointer for devices of type classic or unknown.
 
; Value type
: [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt#BluetoothGatt|BluetoothGatt]]
 
; Default value
: Null pointer
 
; Sample
var gatt = device.gatt;


== Event Handlers ==
== Event Handlers ==
Line 121: Line 165:
; Paramter
; Paramter
: ''aAttributeEvent''
: ''aAttributeEvent''
:: The event is a [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAttributeEvent|BluetoothAttributeEvent]] with property [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAttributeEvent#attr|attr]] as a [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceAttribute|BluetoothDeviceAttribute]].
:: The event is a [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAttributeEvent#Interface|BluetoothAttributeEvent]] with property [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAttributeEvent#attrs|attrs]] that contains changed [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#BluetoothDeviceAttribute|BluetoothDeviceAttributes]].


; Sample
; Sample
  function bt_onAttributeChanged(evt) {
  device.onattributechanged = function onDeviceAttributeChanged(evt) {
   var attr = evt.attr;
   for (var i in evt.attrs) {
  var value = evt.value;
    switch (evt.attrs[i]) {
      case 'name':
  switch (attr) {
        console.log("device name changed to", device.name);
    case BluetoothDeviceAttribute.name:
        break;
      // do your things here
      case 'paired':
      break;
        console.log("device paired changed to", device.paired);
    case BluetoothDeviceAttribute.uuids:
        break;
      // do your things here
      default:
      break;
        break;
    default:
    }
      break;
   }
   }
  }
  }
''instanceOfBluetoothDevice''.onattributechanged = bt_onAttributeChanged;


== Methods ==
== Methods ==
Line 148: Line 189:


; Description
; Description
: The method fetches the up-to-date UUID list of each bluetooth service that the device provides.
: The method fetches the up-to-date UUID list of services that the device provides. If the fetchUuids operation succeeds, an [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#onattributechanged|onattributechanged]] would be triggered right before the Promise is resolved to indicate [[B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice#uuids|device.uuids]] has changed.  


; Return
; Return
: A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a DOMString array.
: A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a DOMString array representing the updated list of UUIDs.


; Sample
; Sample
  var req = ''instanceOfBluetoothDevice''.fetchUuids();
  device.fetchUuids().then ( function onResolve(uuids) {
  console.log("Resolved with uuids:");
req.onsuccess = functions(e) {
  for (var i = 0; i < uuids.length; i++) { 
  var uuids = e.target.result;
    console.log("uuid", i, "is", uuids[i]);
   
  }
  // do your things here!
  }, function onReject(aReason) {
  }
  console.log("Rejected with this reason: " + aReason);
  });


== See also ==
== See also ==
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter|BluetoothAdapter]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter|BluetoothAdapter]]
* [[B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt|BluetoothGatt]]

Latest revision as of 15:53, 27 July 2015

Overview

BluetoothDevice provides information regarding a given remote bluetooth device.

Interfaces

BluetoothDevice

[CheckPermissions="bluetooth"]
interface BluetoothDevice: EventTarget
{
  readonly attribute DOMString address;
  readonly attribute BluetoothClassOfDevice cod;
  readonly attribute DOMString name;
  readonly attribute boolean paired;
  [Cached, Pure] readonly attribute sequence<DOMString> uuids;
  readonly attribute BluetoothDeviceType type;
  readonly attribute BluetoothGatt? gatt;

           attribute EventHandler onattributechanged;

  [NewObject] Promise<sequence<DOMString>> fetchUuids();
};

BluetoothDeviceType

enum BluetoothDeviceType
{
  "unknown",
  "classic",
  "le",
  "dual",
}

BluetoothDeviceAttribute

enum BluetoothDeviceAttribute
{
  "unknown",
  "cod",
  "name",
  "paired",
  "uuids"
}

Properties

address

Description
The address property provides the address of the device on the bluetooth micro-network.
Value type
DOMString
Default value
Empty string ("")
Sample
var address = device.address;

cod

Description
The cod property is a BluetoothClassOfDevice object that provides much information about the device's capabilities.
Value type
BluetoothClassOfDevice
Default value
A BluetoothClassOfDevice object whose attributes are default values.
Sample
var cod = device.cod;

var majorDeviceClass = cod.BluetoothMajorDeviceClass;
var majorServiceClass = cod.BluetoothMajorServiceClass;
var minorDeviceClass = cod.BluetoothMinorDeviceClass;

name

Description
The name property is the human readable name of the device.
Value type
DOMString
Default value
Empty string ("")
Sample
var name = device.name;

paired

Description
The paired property indicates whether this remote device is paired to current device's adapter (true) or not (false).
Value type
boolean
Default value
false
Sample
var paired = device.paired;

uuids

Description
[Cached, Pure]
The property stores the cached UUID list of services that the remote device provides. If applications require the up-to-date UUID list is required, call fetchUuids() to update this property. This property is marked with [Cached] because the same JS Array object is returned until a fetchUuids() call happens, and marked with [Pure] rather than [Constant] because uuids is updated once fetchUuids() executes.
Value type
sequence<DOMString>
Default value
An empty array (array with length = 0)
Sample
var uuids = device.uuids;

type

Description
The type property indicates the device type of the remote device.
Value type
BluetoothDeviceType
Default value
BluetoothDeviceType.unknown
Sample
var type = device.type;

gatt

Description
The gatt property is an object to conduct GATT client operations on this remote LE device. This property will be a null pointer for devices of type classic or unknown.
Value type
BluetoothGatt
Default value
Null pointer
Sample
var gatt = device.gatt;

Event Handlers

onattributechanged

Description
A handler to trigger when on of the remote device's properties has changed. Note access to the changed property in this event handler would get the updated value.
Paramter
aAttributeEvent
The event is a BluetoothAttributeEvent with property attrs that contains changed BluetoothDeviceAttributes.
Sample
device.onattributechanged = function onDeviceAttributeChanged(evt) {
  for (var i in evt.attrs) {
    switch (evt.attrs[i]) {
      case 'name':
        console.log("device name changed to", device.name);
        break;
      case 'paired':
        console.log("device paired changed to", device.paired);
        break;
      default:
        break;
    }
  }
}

Methods

fetchUuids()

Description
The method fetches the up-to-date UUID list of services that the device provides. If the fetchUuids operation succeeds, an onattributechanged would be triggered right before the Promise is resolved to indicate device.uuids has changed.
Return
A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a DOMString array representing the updated list of UUIDs.
Sample
device.fetchUuids().then ( function onResolve(uuids) {
  console.log("Resolved with uuids:");
  for (var i = 0; i < uuids.length; i++) {   
    console.log("uuid", i, "is", uuids[i]);
  }
}, function onReject(aReason) {
  console.log("Rejected with this reason: " + aReason);
});

See also