B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter

Overview

BluetoothAdapter handles all the operations requested by bluetooth networks. A bluetooth adapter is the physical interface used to interact with local bluetooth device. BluetoothAdapter is the most important interface in the whole WebBluetooth API because it manages all the interactions between the local bluetooth device and remote bluetooth devices.

Interface

• BluetoothAdapter
• BluetoothStartDiscoveryRequest
• BluetoothAdapterState
• BluetoothAdapterAttribute

BluetoothAdapter

interface BluetoothAdapter: EventTarget
{
  readonly attribute BluetoothAdapterState state;
  readonly attribute DOMString address;
  readonly attribute DOMString name;
  readonly attribute boolean discoverable;
  readonly attribute boolean discovering;

  attribute EventHandler onattributechanged;
  attribute EventHandler ondevicepaired;
  attribute EventHandler ondeviceunpaired;
  attribute EventHandler ondisplaypasskeyreq;
  attribute EventHandler onenterpasskeyreq;
  attribute EventHandler onpairingconfirmationreq;
  attribute EventHandler onpairingconsentreq;

  DOMRequest enable();
  DOMRequest disable();
  DOMRequest setName(DOMString aName);
  DOMRequest setDiscoverable(boolean aDiscoverable);
  DOMRequest startDiscovery();
  DOMRequest stopDiscovery();
  DOMRequest pair(DOMString aAddress);
  DOMRequest unpair(DOMString aAddress);
  DOMRequest getPairedDevices();
};

BluetoothAdapterState

enum BluetoothAdapterState
{
  "disabled",
  "disabling",
  "enabled",
  "enabling"
}

BluetoothAdapterAttribute

enum BluetoothAdapterAttribute
{
  "state",
  "address",
  "name",
  "discoverable",
  "discovering"
}

Properties

• BluetoothAdapter.state
• BluetoothAdapter.address
• BluetoothAdapter.name
• BluetoothAdapter.discoverable
• BluetoothAdapter.discovering

state

Description

The state of the local bluetooth adapter.

Value type

BluetoothAdapterState

Default value

BluetoothAdapterState.disabled

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var state = adapter.state;

address

Description

The address of the device's adapter on the bluetooth micro-network.

Value type

DOMString

Default value

Empty string ("")

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var address = adapter.address;

name

Description

The human readable name of the device's adapter.

Value type

DOMString

Default value

Empty string ("")

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var name = adapter.name;

discoverable

Description

Indicates if the device is discoverable (true) or not (false) by other bluetooth devices.

Value type

boolean

Default value

false

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var discoverable = adapter.discoverable;

discovering

Description

Indicates if the device is in the process of discovering (true) or not (false) surrounding bluetooth devices.

Value type

boolean

Default value

false

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var discovering = adapter.discovering;

Event Handlers

• BluetoothAdapter.onattributechanged
• BluetoothAdapter.ondevicepaired
• BluetoothAdapter.ondeviceunpaired
• BluetoothAdapter.ondisplaypasskeyreq
• BluetoothAdapter.onenterpasskeyreq
• BluetoothAdapter.onpairingconfirmationreq
• BluetoothAdapter.onpairingconsentreq

onattributechanged

Description

A handler to trigger when one of the local bluetooth adapter'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 attr as a BluetoothAdapterAttribute.

Sample

function bt_onAttributeChanged(evt) {
  var attr = evt.attr;
  var value = evt.value;

  switch (attr) {
    case BluetoothAdapterAttribute.state:
      // do your things here
      break
    case BluetoothAdapterAttribute.name:
      // do your things here
      break;
    case BluetoothAdapterAttribute.discoverable:
      // do your things here
      break;
    default:
      break;
  }
}

var adapter = navigator.mozBluetooth.getDefaultAdapter();
adapter.onattributechanged = bt_onAttributeChanged;

ondevicepaired

Description

A handler to trigger when a remote device gets paired with local bluetooth adapter.

Parameter

aDeviceEvent

The event is a BluetoothDeviceEvent with property device as the paired remote bluetooth device.

ondeviceunpaired

Description

A handler to trigger when a remote device gets unpaired from local bluetooth adapter.

Parameter

aDeviceEvent

The event is a BluetoothDeviceEvent with property address as the unpaired remote bluetooth device's address.

ondisplaypasskeyreq

Description

A handler to trigger when a remote bluetooth device requests to display passkey on the screen during pairing process.

Parameter

aPairingEvent

The event is a BluetoothPairingEvent with property address as the remote bluetooth device's address, and property passkey as the passkey to display.

onenterpasskeyreq

Description

A handler to trigger when a remote bluetooth device requests user enter PIN code or passkey during pairing process.

Parameter

aPairingEvent

The event is a BluetoothPairingEvent with property device as the remote bluetooth device and method setPasskey to reply the PIN code or passkey entered by user.

onpairingconfirmationreq

Description

A handler to trigger when a remote bluetooth device requests user confirm passkey during pairing process. Applications may prompt passkey to user for confirmation, or confirm the passkey for user proactively.

Parameter

aPairingEvent

The event is a BluetoothPairingEvent with property device as the remote bluetooth device, property passkey as the passkey to confirm, and method setPairingConfirmation to reply user confirmation.

onpairingconsentreq

Description

A handler to trigger when a remote bluetooth device requests user confirm pairing during pairing process. Applications may prompt user for confirmation or confirm for user proactively.

Parameter

aPairingEvent

The event is a BluetoothPairingEvent with property device as the remote bluetooth device.

Methods

• BluetoothAdapter.enable()
• BluetoothAdapter.disable()
• BluetoothAdapter.setName(DOMString aName)
• BluetoothAdapter.setDiscoverable(boolean aDiscoverable)
• BluetoothAdapter.startDiscovery()
• BluetoothAdapter.stopDiscovery()
• BluetoothAdapter.pair(DOMString aDeviceAddress)
• BluetoothAdapter.unpair(DOMString aDeviceAddress)
• BluetoothAdapter.getPairedDevices()

enable()

Description

The method turns on the local bluetooth adapter.

This is an asynchronous method and its result is returned via a DOMRequest. Once the method is called, adapter.state becomes enabling and a corresponding onattributechanged would be triggered. If the enable operation succeeds, 3 more onattributechanged would be triggered before DOMRequest's onsuccess: the first and second ones indicate the address and name has been updated (with random order), and the last one must indicate adapter.state becomes enabled. In other words, all adapter's properties must be updated value once adapter.state becomes enabled.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the enable operation has completed.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var req = adapter.enable();

req.onsuccess = function () {
  // do your things here
}
req.onerror = function () {
  // do your things here
}

disable()

Description

The method turns off the local bluetooth adapter.

This is an asynchronous method and its result is returned via a DOMRequest. Once the method is called, adapter.state becomes disabling and a corresponding onattributechanged would be triggered. If the disable operation succeeds, several onattributechanged would be triggered before DOMRequest's onsuccess: the first (N-1) ones indicate all properties except adapter.state become default value, and the last one must indicate adapter.state becomes disabled. In other words, all adapter's properties are reset to default value once adapter.state becomes disabled. Note the value of N ranges from 2 to 4, depending on whether adapter was discovering / discoverable.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the disable operation has completed. If the bluetooth adapter is currently disabled, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var req = adapter.disable();

req.onsuccess = function () {
  // do your things here
}
req.onerror = function () {
  // do your things here
}

setName(DOMString aName)

Description

The method sets the human-readable name of the local bluetooth adapter. This name is visible to remote bluetooth devices.

This is an asynchronous method and its result is returned via a DOMRequest. If the setName operation succeeds, an onattributechanged would be triggered before DOMRequest's onsuccess to indicate adapter.name has changed.

Parameters

aName

A DOMString representing the new name to set.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the name has been set. If the bluetooth adapter is currently disabled or aName is identical to current name attribute, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var name = "The name of bluetooth adapter";
var req = aAdapter.setName(name);

req.onsuccess = function () {
  // do your things here
}
req.onerror = function () {
  // do your things here
}

setDiscoverable(boolean aDiscoverable)

Description

The method changes the value of the bluetooth adapter's discoverable property.

This is an asynchronous method and the result is returned via a DOMRequest. If the setDiscoverable operation succeeds, an onattributechanged would be triggered before DOMRequest's onsuccess to indicate adapter.discoverable has changed.

Parameters

aDiscoverable

A boolean indicating if the device is discoverable (true) or not (false).

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the adapter could currently be discovered. If the bluetooth adapter is currently disabled or aDiscoverable is identical to current discoverable attribute, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var req = adapter.setDiscoverable(true);

req.onsuccess = function () {
  ...
}
req.onerror = function () {
  ...
}

startDiscovery()

Description

The method makes the device's adapter start seeking for remote devices. The discovery process may be terminated after discovering a period of time. If the startDiscovery operation succeeds, an onattributechanged event would be triggered before BluetoothStartDiscoveryRequest's onsuccess to indicate adapter.discovering becomes false.

Return

A BluetoothStartDiscoveryRequest which extends DOMRequest to handle the discovered devices. Its onsuccess is fired to indicate startDiscovery operation has completed, and ondevicefound is fired each time a remote bluetooth device is discovered. If the bluetooth adapter is currently disabled, the DOMRequest's onerror is fired.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var req = adapter.startDiscovery();

req.ondevicefound = function (evt) {
  var device = evt.device;
  // do your things here
}

req.onsuccess = function () {
  // do your things here
}
req.onerror = function (evt) {
  var error = evt.error.name;
  // do your things here
}

stopDiscovery()

Description

The method makes the device's adapter stop seeking for remote devices.

This is an asynchronous method and its result is returned via a DOMRequest. If the stopDiscovery operation succeeds, an onattributechanged would be triggered before DOMRequest's onsuccess to indicate adapter.discovering becomes false. Note adapter may still receive BluetoothStartDiscoveryRequest.ondevicefound event until DOMRequest's onsuccess is fired.

Return

A DOMRequest object to handle the success or error of the operation. If the bluetooth adapter is currently disabled, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.stopDiscovery();

req.onsuccess = function () {
  // do your things here
}
req.onerror = function () {
  // do your things here
}

pair(DOMString aDeviceAddress)

Description

The method starts pairing a remote device with the device's adapter.

Parameters

aDeviceAddress

A DOMString object representing the address of the device to pair with.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the pair operation has completed. Note the DOMRequest's onsuccess is returned after ondevicepaired event handler is triggered.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var req = adapter.pair('00:80:98:09:0B:5D');

req.onsuccess = function () {
  // do your things here
}
req.onerror = function () {
  // do your things here
}

unpair(DOMString aDeviceAddress)

Description

The method unpairs a remote device from the device's adapter.

Parameters

aDeviceAddress

A DOMString object representing the address of the device to unpair from.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, it means that the unpair operation has completed. Note the DOMRequest's onsuccess is returned after ondeviceunpaired event handler is triggered.

getPairedDevices()

Description

The method retrieves the list of all devices paired with the device's adapter.

Return

A DOMRequest object to handle the success or error of the operation. In case of success, the request's result is an array of BluetoothDevice objects.

Sample

var req = defaultAdapter.getPairedDevices();

req.onsuccess = function bt_getPairedSuccess() {
  var paired = req.result.slice();
  var length = paired.length;

  for (var i = 0; i < length; i++) {
    (function(device) {
      console.log(device.address);
    })(paired[i]);
  }
}

See also

• BluetoothManager
• BluetoothDevice