B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter

From MozillaWiki
Jump to navigation Jump to search

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

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

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

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

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

Retrieved from "https://wiki.mozilla.org/index.php?title=B2G/Bluetooth/WebBluetooth-v2/BluetoothAdapter&oldid=947086"