B2G/Bluetooth/WebBluetooth-v2/BluetoothGattServer

Overview

BluetoothGattServer provides bluetooth Generic Attribute Profile (GATT) server functionality to create Bluetooth Smart services and characteristics.

Interfaces

BluetoothGattServer

BluetoothGattServer

[CheckPermissions="bluetooth"]
interface BluetoothGattServer
{
  [Cached, Pure] readonly attribute sequence<BluetoothGattService> services;

  attribute EventHandler onconnectionstatechanged;
  attribute EventHandler onattributereadreq;
  attribute EventHandler onattributewritereq;
          
  [NewObject] Promise<void> connect(DOMString address);
  [NewObject] Promise<void> disconnect(DOMString address);
  [NewObject] Promise<void> addService(BluetoothGattService service);
  [NewObject] Promise<void> removeService(BluetoothGattService service);
  [NewObject] Promise<void> notifyCharacteristicChanged(DOMString address, BluetoothGattCharacteristic characteristic, bool confirm);
  [NewObject] Promise<void> sendResponse(DOMString address, unsigned short status, unsigned long requestId);
};

Properties

• BluetoothGattServer.services

services

Description

Array of services offered by this device.

Value Type

sequence<BluetoothGattService>

Default Value

Empty array (array with length = 0)

Event Handlers

• BluetoothGattServer.ondeviceconnectionstatechanged
• BluetoothGattServer.onattributereadreq
• BluetoothGattServer.onattributewritereq

onconnectionstatechanged

Description

A handler to trigger when a remote LE device has been connected or disconnected.

Argument

[CheckPermissions="bluetooth"]
interface BluetoothStatusChangedEvent : Event
{
  readonly attribute DOMString address;
  readonly attribute boolean status;
};

address

Address of the connected/disconnected remote LE device.

status

Whether the remote LE device is connected (true) or disconnected (false).

onattributereadreq

Description

A handler to trigger when a remote client has requested to read a local characteristic or descriptor.

Argument

[CheckPermissions="bluetooth"]
interface BluetoothGattAttributeEvent : Event
{
  readonly attribute DOMString address;
  readonly attribute unsigned long requestId;
  readonly attribute BluetoothGattCharacteristic? characteristic;
  readonly attribute BluetoothGattDescriptor? descriptor;
  readonly attribute ArrayBuffer? value;
  readonly attribute boolean needRsp;
};

address

Address of the remote client.

requestId

Request id of the attribute read request.

characteristic

The characteristic requested to read. Null if remote client requests to read a local descriptor.

descriptor

The descriptor requested to read. Null if remote client requests to read a local characteristic.

value

The new characteristic/descriptor value to be written in write requests. Null if the request was a read request.

needRsp

Indicate whether a response is needed or not. If needRsp is true, application needs to explicitly call sendResponse(DOMString address, unsigned short status, unsigned long requestId).

onattributewritereq

Description

A handler to trigger when a remote client has requested to write a local characteristic or descriptor.

Argument

[CheckPermissions="bluetooth"]
interface BluetoothGattAttributeEvent : Event
{
  readonly attribute DOMString address;
  readonly attribute unsigned long requestId;
  readonly attribute BluetoothGattCharacteristic? characteristic;
  readonly attribute BluetoothGattDescriptor? descriptor;
  readonly attribute ArrayBuffer? value;
  readonly attribute boolean needRsp;
};

address

Address of the remote client.

requestId

Request id of the attribute write request.

characteristic

The characteristic requested to write. Null if remote client requests to write a local descriptor.

descriptor

The descriptor requested to write. Null if remote client requests to write a local characteristic.

value

The new characteristic/descriptor value to be written in write requests. Null if the request was a read request.

needRsp

Indicate whether a response is needed or not. If needRsp is true, application needs to explicitly call sendResponse(DOMString address, unsigned_short status, unsigned long requestId).

Methods

• BluetoothGattServer.connect(DOMString address)
• BluetoothGattServer.disconnect(DOMString address)
• BluetoothGattServer.addService(BluetoothGattService service)
• BluetoothGattServer.removeService(BluetoothGattService service)
• BluetoothGattServer.notifyCharacteristicChanged(DOMString address, BluetoothGattCharacteristic characteristic, bool confirm)
• BluetoothGattServer.sendResponse(DOMString address, unsigned short status, unsigned long requestId)

connect(DOMString address)

Description

The method initiates a connection to remote LE device.

Parameter

address

The address of remote LE device to connect.

Return

A Promise to indicate whether the operation is resolved or rejected.

disconnect(DOMString address)

Description

The method disconnects the established connection of remote LE device.

Parameter

address

The address of remote LE device to disconnect.

Return

A Promise to indicate whether the operation is resolved or rejected.

addService(BluetoothGattService service)

Description

The method adds a service. If the service already exists in the GATT server, the promise will be rejected.

Parameter

service

The BluetoothGattService object to add.

Return

A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, property services is also updated with the added service.

removeService(BluetoothGattService service)

Description

The method removes a provided service. If the service doesn't exist in the GATT server, the promise will be rejected.

Parameter

service

The BluetoothGattService object to remove.

Return

A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, property services is also updated without the removed service.

notifyCharacteristicChanged(DOMString address, BluetoothGattCharacteristic characteristic, bool confirm)

Description

The method sends a notification/indication that a local characteristic has been updated.

Parameter

address

The address of remote LE device to notify.

characteristic

The updated characteristic.

confirm

Whether to request confirmation from the client (indication) or not (notification).

Return

A Promise to indicate whether the operation is resolved or rejected.

sendResponse(DOMString address, unsigned short status, unsigned long requestId)

Description

The method sends a response of a read or write request to a remote LE device.

Parameter

address

The address of remote LE device to notify.

status

The status of the request to reply. 0 for successful reply, otherwise, please see Bluetooth Core Specification vol 3, part F, 3.4.1.1 for defined error status codes.

requestId

The ID of the request to reply.

Return

A Promise to indicate whether the operation is resolved or rejected.