B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter

Overview

The BluetoothAdapter API is used to handle all the operations requested by Bluetooth networks. A bluetooth adapter is the physical interface which is used to interact with local Bluetooth device. In the whole Bluetooth API, it's the most important interface because it is used to manage all the interactions between local bluetooth device and remote bluetooth devices.

Interface

• BluetoothAdapter
• 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;

  DOMRequest enable();
  DOMRequest disable();
  DOMRequest setName(DOMString aName);
  DOMRequest setDiscoverable(boolean aDiscoverable);
  DOMRequest startDiscovery();
  DOMRequest stopDiscovery();
  DOMRequest pair(DOMString aAddress);
  DOMRequest unpair();
  DOMRequest setPasskey(DOMString aAddress, DOMString aPasskey);
  DOMRequest setPairingConfirmation(DOMString aAddress, boolean aConfirm);
  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 a property of the remote device is changed. Note in this event handler, access to the changed property also gets the updated value.

Paramter

aAttributeEvent

The event is a BluetoothAttributeEvent with attribute 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

aDevice

A BluetoothDevice object representing the paired device.

ondeviceunpaired

Description

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

Parameter

aAddress

The address of the unpaired device.

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

aAddressEvent

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

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 address as the remote bluetooth device's address, and property passkey as the passkey to confirm.

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

aAddressEvent

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

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.setPasskey(DOMString aDeviceAddress, DOMString aPasskey)
• BluetoothAdapter.setPairingConfirmation(DOMString aDeviceAddress, boolean aConfirm)
• BluetoothAdapter.getPairedDevices()

enable()

Description

Turns on the local bluetooth adapter.

DOMRequest onsucess will be returned after onattributechanged which indicates state of the adapter is enabled.

instanceOfBluetoothAdapter.state should be enabling when the function finish.

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 request = adapter.enable();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

disable()

Description

Turns off the local bluetooth adapter.

DOMRequest's onsucess is called after onattributechanged which indicates state of the adapter is disabled.

instanceOfBluetoothAdapter.state should be disabling when the function finish.

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 request = adapter.disable();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

setName(DOMString aName)

Description

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

DOMRequest onsucess will be returned after onattributechanged is fired with the new name.

Parameters

aName

A string 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 request = aAdapter.setName(name);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

setDiscoverable(boolean aDiscoverable)

Description

Changes the value of the discoverable attribute for the device's adapter.

DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is discoverable (true) or not (false).

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 request = adapter.setDiscoverable(true);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

startDiscovery()

Description

The startDiscovery method makes the device's adapter start seeking for remote devices. The discovery process may be terminated after discovering a period of time. An onattributechanged event would be fired in that case.

DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is discovering.

Return

A BluetoothStartDiscoveryRequest object which extends from DOMRequest to handle the discovered devices.

BluetoothStartDiscoveryRequest.ondevicefound

ondevicefound(BluetoothDevice aDevice) is a event listener which receive devicefound events.

The event occurs with parameter aDevice when a Bluetooth device is discovered in the surrounding area.

It may or may not be fired. It depends on if there is any discoverable Bluetooth devices around.

If the bluetooth adapter is currently disabled, the DOMRequest's onerror is called.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.startDiscovery();
request.ondevicefound = function (evt) {
  var device = evt.device;
  ...
}
request.onsuccess = function () {
  ...
}
request.onerror = function (evt) {
  var error = evt.error.name;
  ...
}

stopDiscovery()

Description

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

DOMRequest onsucess will be returned after onattributechanged which indicates the adapter is not discovering.

Adapter may still receive ondevicefound event until 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();
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

pair(DOMString aDeviceAddress)

Description

The pair 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 request = adapter.pair('00:80:98:09:0B:5D');
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

unpair(DOMString aDeviceAddress)

Description

The unpair 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.

setPasskey(DOMString aDeviceAddress, DOMString aPasskey)

Description

The setPasskey method replies the requested passkey when the device's adapter is pairing with a remote device.

Parameters

aDeviceAddress

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

aPasskey

A DOMString object representing the passkey code set by user.

Return

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

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
var request = adapter.setPasskey('00:80:98:09:0B:5D', '0000');
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note

This method is to reply onenterpasskeyreq. The passkey can be considered both PIN key reply (legacy pairing) and SSP passkey reply.

setPairingConfirmation(DOMString aDeviceAddress, boolean aConfirm)

Description

The setPairingConfirmation method replies the pairing confirmation when the device's adapter is pairing with a remote device.

Parameters

aDeviceAddress

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

aConfirm

A boolean indicating if user confirms pairing with the remote device (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 setPairingConfirmation operation has completed.

Sample

var adapter = navigator.mozBluetooth.getDefaultAdapter();
// when users press the confirmation button
var request = adapter.setPairingConfirmation('00:80:98:09:0B:5D', true);
request.onsuccess = function () {
  ...
}
request.onerror = function () {
  ...
}

Note

This method is to reply onpairingconfirmationreq event

getPairedDevices()

Description

The getPairedDevices 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