// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// The <code>chrome.bluetoothLowEnergy</code> API is used to communicate with
// Bluetooth Smart (Low Energy) devices using the
// <a href="https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx">
// Generic Attribute Profile (GATT)</a>.
namespace bluetoothLowEnergy {
// Values representing the possible properties of a characteristic.
// Characteristic permissions are inferred from these properties.
// Please see the Bluetooth 4.x spec to see the meaning of each individual
// property.
enum CharacteristicProperty {
broadcast, read, writeWithoutResponse, write, notify, indicate,
authenticatedSignedWrites, extendedProperties, reliableWrite,
writableAuxiliaries, encryptRead, encryptWrite, encryptAuthenticatedRead,
encryptAuthenticatedWrite
};
// Values representing possible permissions for a descriptor.
// Please see the Bluetooth 4.x spec to see the meaning of each individual
// permission.
enum DescriptorPermission {
read, write, encryptedRead, encryptedWrite, encryptedAuthenticatedRead,
encryptedAuthenticatedWrite
};
// Type of advertisement. If 'broadcast' is chosen, the sent advertisement
// type will be ADV_NONCONN_IND and the device will broadcast with a random
// MAC Address. If set to 'peripheral', the advertisement type will be
// ADV_IND or ADV_SCAN_IND and the device will broadcast with real Bluetooth
// Adapter's MAC Address.
enum AdvertisementType {broadcast, peripheral};
// Represents a bluetooth central device that is connected to the local GATT
// server.
dictionary Device {
// The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
DOMString address;
// The human-readable name of the device.
DOMString? name;
// The class of the device, a bit-field defined by
// http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
long? deviceClass;
};
// Represents a peripheral's Bluetooth GATT Service, a collection of
// characteristics and relationships to other services that encapsulate
// the behavior of part of a device.
dictionary Service {
// The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.
DOMString uuid;
// Indicates whether the type of this service is primary or secondary.
boolean isPrimary;
// Returns the identifier assigned to this service. Use the instance ID to
// distinguish between services from a peripheral with the same UUID and
// to make function calls that take in a service identifier. Present, if
// this instance represents a remote service.
DOMString? instanceId;
// The device address of the remote peripheral that the GATT service belongs
// to. Present, if this instance represents a remote service.
DOMString? deviceAddress;
};
// Represents a GATT characteristic, which is a basic data element that
// provides further information about a peripheral's service.
dictionary Characteristic {
// The UUID of the characteristic, e.g.
// 00002a37-0000-1000-8000-00805f9b34fb.
DOMString uuid;
// The GATT service this characteristic belongs to.
Service? service;
// The properties of this characteristic.
CharacteristicProperty[] properties;
// Returns the identifier assigned to this characteristic. Use the instance
// ID to distinguish between characteristics from a peripheral with the same
// UUID and to make function calls that take in a characteristic identifier.
// Present, if this instance represents a remote characteristic.
DOMString? instanceId;
// The currently cached characteristic value. This value gets updated when
// the value of the characteristic is read or updated via a notification
// or indication.
ArrayBuffer? value;
};
// Represents a GATT characteristic descriptor, which provides further
// information about a characteristic's value.
dictionary Descriptor {
// The UUID of the characteristic descriptor, e.g.
// 00002902-0000-1000-8000-00805f9b34fb.
DOMString uuid;
// The GATT characteristic this descriptor belongs to.
Characteristic? characteristic;
// The permissions of this descriptor.
DescriptorPermission[] permissions;
// Returns the identifier assigned to this descriptor. Use the instance ID
// to distinguish between descriptors from a peripheral with the same UUID
// and to make function calls that take in a descriptor identifier. Present,
// if this instance represents a remote characteristic.
DOMString? instanceId;
// The currently cached descriptor value. This value gets updated when
// the value of the descriptor is read.
ArrayBuffer? value;
};
// The connection properties specified during a call to $(ref:connect).
dictionary ConnectProperties {
// Flag indicating whether a connection to the device is left open when the
// event page of the application is unloaded (see <a
// href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
// Lifecycle</a>). The default value is <code>false.</code>
boolean persistent;
};
// Optional characteristic notification session properties specified during a
// call to $(ref:startCharacteristicNotifications).
dictionary NotificationProperties {
// Flag indicating whether the app should receive notifications when the
// event page of the application is unloaded (see <a
// href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
// Lifecycle</a>). The default value is <code>false</code>.
boolean persistent;
};
// Represents an entry of the "Manufacturer Specific Data" field of Bluetooth
// LE advertisement data.
dictionary ManufacturerData {
long id;
long[] data;
};
// Represents an entry of the "Service Data" field of Bluetooth LE advertisement
// data.
dictionary ServiceData {
DOMString uuid;
long[] data;
};
// Represents a Bluetooth LE advertisement instance.
dictionary Advertisement {
// Type of advertisement.
AdvertisementType type;
// List of UUIDs to include in the "Service UUIDs" field of the Advertising
// Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
DOMString[]? serviceUuids;
// List of manufacturer specific data to be included in "Manufacturer Specific
// Data" fields of the advertising data.
ManufacturerData[]? manufacturerData;
// List of UUIDs to include in the "Solicit UUIDs" field of the Advertising
// Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
DOMString[]? solicitUuids;
// List of service data to be included in "Service Data" fields of the advertising
// data.
ServiceData[]? serviceData;
};
// Represents a an attribute read/write request.
dictionary Request {
// Unique ID for this request. Use this ID when responding to this request.
long requestId;
// Device that send this request.
Device device;
// Value to write (if this is a write request).
ArrayBuffer? value;
};
// Represents a response to an attribute read/write request.
dictionary Response {
// Id of the request this is a response to.
long requestId;
// If this is an error response, this should be true.
boolean isError;
// Response value. Write requests and error responses will ignore this
// parameter.
ArrayBuffer? value;
};
// Represents a notification to be sent to a remote device.
dictionary Notification {
// New value of the characteristic.
ArrayBuffer value;
// Optional flag for sending an indication instead of a notification.
boolean? shouldIndicate;
};
callback CharacteristicCallback = void(Characteristic result);
callback CreateCharacteristicCallback = void(DOMString characteristicId);
callback CharacteristicsCallback = void(Characteristic[] result);
callback DescriptorCallback = void(Descriptor result);
callback CreateDescriptorCallback = void(DOMString descriptorId);
callback DescriptorsCallback = void(Descriptor[] result);
callback ResultCallback = void();
callback ServiceCallback = void(Service result);
callback CreateServiceCallback = void(DOMString serviceId);
callback ServicesCallback = void(Service[] result);
callback RegisterAdvertisementCallback = void (long advertisementId);
// These functions all report failures via chrome.runtime.lastError.
interface Functions {
// Establishes a connection between the application and the device with the
// given address. A device may be already connected and its GATT services
// available without calling <code>connect</code>, however, an app that
// wants to access GATT services of a device should call this function to
// make sure that a connection to the device is maintained. If the device
// is not connected, all GATT services of the device will be discovered
// after a successful call to <code>connect</code>.
// |deviceAddress|: The Bluetooth address of the remote device to which a
// GATT connection should be opened.
// |properties|: Connection properties (optional).
// |callback|: Called when the connect request has completed.
static void connect(
DOMString deviceAddress,
optional ConnectProperties properties,
ResultCallback callback);
// Closes the app's connection to the device with the given address. Note
// that this will not always destroy the physical link itself, since there
// may be other apps with open connections.
// |deviceAddress|: The Bluetooth address of the remote device.
// |callback|: Called when the disconnect request has completed.
static void disconnect(
DOMString deviceAddress,
optional ResultCallback callback);
// Get the GATT service with the given instance ID.
// |serviceId|: The instance ID of the requested GATT service.
// |callback|: Called with the requested Service object.
static void getService(
DOMString serviceId,
ServiceCallback callback);
// Create a locally hosted GATT service. This service can be registered
// to be available on a local GATT server.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |service|: The service to create.
// |callback|: Called with the created services's unique ID.
static void createService(
Service service,
CreateServiceCallback callback);
// Get all the GATT services that were discovered on the remote device with
// the given device address.
//
// <em>Note:</em> If service discovery is not yet complete on the device,
// this API will return a subset (possibly empty) of services. A work around
// is to add a time based delay and/or call repeatedly until the expected
// number of services is returned.
//
// |deviceAddress|: The Bluetooth address of the remote device whose GATT
// services should be returned.
// |callback|: Called with the list of requested Service objects.
static void getServices(
DOMString deviceAddress,
ServicesCallback callback);
// Get the GATT characteristic with the given instance ID that belongs to
// the given GATT service, if the characteristic exists.
// |characteristicId|: The instance ID of the requested GATT
// characteristic.
// |callback|: Called with the requested Characteristic object.
static void getCharacteristic(
DOMString characteristicId,
CharacteristicCallback callback);
// Create a locally hosted GATT characteristic. This characteristic must
// be hosted under a valid service. If the service ID is not valid, the
// lastError will be set.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |characteristic|: The characteristic to create.
// |serviceId|: ID of the service to create this characteristic for.
// |callback|: Called with the created characteristic's unique ID.
static void createCharacteristic(
Characteristic characteristic,
DOMString serviceId,
CreateCharacteristicCallback callback);
// Get a list of all discovered GATT characteristics that belong to the
// given service.
// |serviceId|: The instance ID of the GATT service whose characteristics
// should be returned.
// |callback|: Called with the list of characteristics that belong to the
// given service.
static void getCharacteristics(
DOMString serviceId,
CharacteristicsCallback callback);
// Get a list of GATT services that are included by the given service.
// |serviceId|: The instance ID of the GATT service whose included
// services should be returned.
// |callback|: Called with the list of GATT services included from the
// given service.
static void getIncludedServices(
DOMString serviceId,
ServicesCallback callback);
// Get the GATT characteristic descriptor with the given instance ID.
// |descriptorId|: The instance ID of the requested GATT characteristic
// descriptor.
// |callback|: Called with the requested Descriptor object.
static void getDescriptor(
DOMString descriptorId,
DescriptorCallback callback);
// Create a locally hosted GATT descriptor. This descriptor must
// be hosted under a valid characteristic. If the characteristic ID is not
// valid, the lastError will be set.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |descriptor|: The descriptor to create.
// |characteristicId|: ID of the characteristic to create this descriptor
// for.
// |callback|: Called with the created descriptor's unique ID.
static void createDescriptor(
Descriptor descriptor,
DOMString characteristicId,
CreateDescriptorCallback callback);
// Get a list of GATT characteristic descriptors that belong to the given
// characteristic.
// |characteristicId|: The instance ID of the GATT characteristic whose
// descriptors should be returned.
// |callback|: Called with the list of descriptors that belong to the given
// characteristic.
static void getDescriptors(
DOMString characteristicId,
DescriptorsCallback callback);
// Retrieve the value of a specified characteristic from a remote
// peripheral.
// |characteristicId|: The instance ID of the GATT characteristic whose
// value should be read from the remote device.
// |callback|: Called with the Characteristic object whose value was
// requested. The <code>value</code> field of the returned Characteristic
// object contains the result of the read request.
static void readCharacteristicValue(
DOMString characteristicId,
CharacteristicCallback callback);
// Write the value of a specified characteristic from a remote peripheral.
// |characteristicId|: The instance ID of the GATT characteristic whose
// value should be written to.
// |value|: The value that should be sent to the remote characteristic as
// part of the write request.
// |callback|: Called when the write request has completed.
static void writeCharacteristicValue(
DOMString characteristicId,
ArrayBuffer value,
ResultCallback callback);
// Enable value notifications/indications from the specified characteristic.
// Once enabled, an application can listen to notifications using the
// $(ref:onCharacteristicValueChanged) event.
// |characteristicId|: The instance ID of the GATT characteristic that
// notifications should be enabled on.
// |properties|: Notification session properties (optional).
// |callback|: Called when the request has completed.
static void startCharacteristicNotifications(
DOMString characteristicId,
optional NotificationProperties properties,
ResultCallback callback);
// Disable value notifications/indications from the specified
// characteristic. After a successful call, the application will stop
// receiving notifications/indications from this characteristic.
// |characteristicId|: The instance ID of the GATT characteristic on which
// this app's notification session should be stopped.
// |callback|: Called when the request has completed (optional).
static void stopCharacteristicNotifications(
DOMString characteristicId,
optional ResultCallback callback);
// Notify a remote device of a new value for a characteristic. If the
// shouldIndicate flag in the notification object is true, an indication
// will be sent instead of a notification. Note, the characteristic needs
// to correctly set the 'notify' or 'indicate' property during creation for
// this call to succeed.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |characteristicId|: The characteristic to send the notication for.
// |notifcation|: The notification to send.
// |callback|: Callback called once the notification or indication has
// been sent successfully.
static void notifyCharacteristicValueChanged(
DOMString characteristicId,
Notification notification,
ResultCallback callback);
// Retrieve the value of a specified characteristic descriptor from a remote
// peripheral.
// |descriptorId|: The instance ID of the GATT characteristic descriptor
// whose value should be read from the remote device.
// |callback|: Called with the Descriptor object whose value was requested.
// The <code>value</code> field of the returned Descriptor object contains
// the result of the read request.
static void readDescriptorValue(
DOMString descriptorId,
DescriptorCallback callback);
// Write the value of a specified characteristic descriptor from a remote
// peripheral.
// |descriptorId|: The instance ID of the GATT characteristic descriptor
// whose value should be written to.
// |value|: The value that should be sent to the remote descriptor as part
// of the write request.
// |callback|: Called when the write request has completed.
static void writeDescriptorValue(
DOMString descriptorId,
ArrayBuffer value,
ResultCallback callback);
// Register the given service with the local GATT server. If the service
// ID is invalid, the lastError will be set.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |serviceId|: Unique ID of a created service.
// |callback|: Callback with the result of the register operation.
static void registerService(
DOMString serviceId,
ResultCallback callback);
// Unregister the given service with the local GATT server. If the service
// ID is invalid, the lastError will be set.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |serviceId|: Unique ID of a current registered service.
// |callback|: Callback with the result of the register operation.
static void unregisterService(
DOMString serviceId,
ResultCallback callback);
// Remove the specified service, unregistering it if it was registered.
// If the service ID is invalid, the lastError will be set.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |serviceId|: Unique ID of a current registered service.
// |callback|: Callback called once the service is removed.
static void removeService(
DOMString serviceId,
optional ResultCallback callback);
// Create an advertisement and register it for advertising. To call this
// function, the app must have the bluetooth:low_energy and
// bluetooth:peripheral permissions set to true. Additionally this API
// is only available to auto launched apps in Kiosk Mode or by setting
// the '--enable-ble-advertising-in-apps' command-line switch.
// See https://developer.chrome.com/apps/manifest/bluetooth
// Note: On some hardware, central and peripheral modes at the same time is
// supported but on hardware that doesn't support this, making this call
// will switch the device to peripheral mode. In the case of hardware which
// does not support both central and peripheral mode, attempting to use the
// device in both modes will lead to undefined behavior or prevent other
// central-role applications from behaving correctly (including the
// discovery of Bluetooth Low Energy devices).
// |advertisement|: The advertisement to advertise.
// |callback|: Called once the registeration is done and we've started
// advertising. Returns the id of the created advertisement.
static void registerAdvertisement(
Advertisement advertisement,
RegisterAdvertisementCallback callback);
// Unregisters an advertisement and stops its advertising. If the
// advertisement fails to unregister the only way to stop advertising
// might be to restart the device.
// |advertisementId|: Id of the advertisement to unregister.
// |callback|: Called once the advertisement is unregistered and is no
// longer being advertised.
static void unregisterAdvertisement(
long advertisementId,
ResultCallback callback);
// Resets advertising on the current device. It will unregister and
// stop all existing advertisements.
// |callback|: Called once the advertisements are reset.
static void resetAdvertising(ResultCallback callback);
// Set's the interval betweeen two consecutive advertisements. Note:
// This is a best effort. The actual interval may vary non-trivially
// from the requested intervals. On some hardware, there is a minimum
// interval of 100ms. The minimum and maximum values cannot exceed the
// the range allowed by the Bluetooth 4.2 specification.
// |minInterval|: Minimum interval between advertisments (in
// milliseconds). This cannot be lower than 20ms (as per the spec).
// |maxInterval|: Maximum interval between advertisments (in
// milliseconds). This cannot be more than 10240ms (as per the spec).
// |callback|: Called once the interval has been set.
static void setAdvertisingInterval(
long minInterval,
long maxInterval,
ResultCallback callback);
// Sends a response for a characteristic or descriptor read/write
// request.
// This function is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |response|: The response to the request.
static void sendRequestResponse(Response response);
};
interface Events {
// Fired whan a new GATT service has been discovered on a remote device.
// |service|: The GATT service that was added.
static void onServiceAdded(Service service);
// Fired when the state of a remote GATT service changes. This involves any
// characteristics and/or descriptors that get added or removed from the
// service, as well as "ServiceChanged" notifications from the remote
// device.
// |service|: The GATT service whose state has changed.
static void onServiceChanged(Service service);
// Fired when a GATT service that was previously discovered on a remote
// device has been removed.
// |service|: The GATT service that was removed.
static void onServiceRemoved(Service service);
// Fired when the value of a remote GATT characteristic changes, either as
// a result of a read request, or a value change notification/indication
// This event will only be sent if the app has enabled notifications by
// calling $(ref:startCharacteristicNotifications).
// |characteristic|: The GATT characteristic whose value has changed.
static void onCharacteristicValueChanged(Characteristic characteristic);
// Fired when the value of a remote GATT characteristic descriptor changes,
// usually as a result of a read request. This event exists
// mostly for convenience and will always be sent after a successful
// call to $(ref:readDescriptorValue).
// |descriptor|: The GATT characteristic descriptor whose value has
// changed.
static void onDescriptorValueChanged(Descriptor descriptor);
// Fired when a connected central device requests to read the value of a
// characteristic registered on the local GATT server. Not responding
// to this request for a long time may lead to a disconnection.
// This event is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |request|: Request data for this request.
// |characteristic|: The GATT characteristic whose value is requested.
static void onCharacteristicReadRequest(
Request request, DOMString characteristicId);
// Fired when a connected central device requests to write the value of a
// characteristic registered on the local GATT server. Not responding
// to this request for a long time may lead to a disconnection.
// This event is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |request|: Request data for this request.
// |characteristic|: The GATT characteristic whose value is being written.
static void onCharacteristicWriteRequest(
Request request, DOMString characteristicId);
// Fired when a connected central device requests to read the value of a
// descriptor registered on the local GATT server. Not responding to
// this request for a long time may lead to a disconnection.
// This event is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |request|: Request data for this request.
// |descriptor|: The GATT descriptor whose value is requested.
static void onDescriptorReadRequest(
Request request, DOMString descriptorId);
// Fired when a connected central device requests to write the value of a
// descriptor registered on the local GATT server. Not responding to
// this request for a long time may lead to a disconnection.
// This event is only available if the app has both the
// bluetooth:low_energy and the bluetooth:peripheral permissions set to
// true. The peripheral permission may not be available to all apps.
// |request|: Request data for this request.
// |descriptor|: The GATT descriptor whose value is being written.
static void onDescriptorWriteRequest(
Request request, DOMString descriptorId);
};
};
Codebase Browser
chromium