extensions/common/api/bluetooth_low_energy.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // The <code>chrome.bluetoothLowEnergy</code> API is used to communicate with
   6 // Bluetooth Smart (Low Energy) devices using the
   7 // <a href="https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx">
   8 // Generic Attribute Profile (GATT)</a>.
   9 namespace bluetoothLowEnergy {
  10   // Values representing the possible properties of a characteristic.
  11   enum CharacteristicProperty {broadcast, read, writeWithoutResponse, write,
  12                                notify, indicate, authenticatedSignedWrites,
  13                                extendedProperties, reliableWrite,
  14                                writableAuxiliaries};
  15
  16   // Represents a peripheral's Bluetooth GATT Service, a collection of
  17   // characteristics and relationships to other services that encapsulate
  18   // the behavior of part of a device.
  19   dictionary Service {
  20     // The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.
  21     DOMString uuid;
  22
  23     // Indicates whether the type of this service is primary or secondary.
  24     boolean isPrimary;
  25
  26     // Indicates whether this service represents a local service hosted by the
  27     // application and available to other peripherals, or a remote service
  28     // hosted and received from a remote peripheral.
  29     [nodoc] boolean isLocal;
  30
  31     // Returns the identifier assigned to this service. Use the instance ID to
  32     // distinguish between services from a peripheral with the same UUID and
  33     // to make function calls that take in a service identifier. Present, if
  34     // this instance represents a remote service.
  35     DOMString? instanceId;
  36
  37     // The device address of the remote peripheral that the GATT service belongs
  38     // to. Present, if this instance represents a remote service.
  39     DOMString? deviceAddress;
  40   };
  41
  42   // Represents a GATT characteristic, which is a basic data element that
  43   // provides further information about a peripheral's service.
  44   dictionary Characteristic {
  45     // The UUID of the characteristic, e.g.
  46     // 00002a37-0000-1000-8000-00805f9b34fb.
  47     DOMString uuid;
  48
  49     // Indicates whether this characteristic represents a local characteristic
  50     // hosted by the application and available to other peripherals, or a remote
  51     // characteristic hosted and received from a remote peripheral.
  52     [nodoc] boolean isLocal;
  53
  54     // The GATT service this characteristic belongs to.
  55     Service service;
  56
  57     // The properties of this characteristic.
  58     CharacteristicProperty[] properties;
  59
  60     // Returns the identifier assigned to this characteristic. Use the instance
  61     // ID to distinguish between characteristics from a peripheral with the same
  62     // UUID and to make function calls that take in a characteristic identifier.
  63     // Present, if this instance represents a remote characteristic.
  64     DOMString? instanceId;
  65
  66     // The currently cached characteristic value. This value gets updated when
  67     // the value of the characteristic is read or updated via a notification
  68     // or indication.
  69     ArrayBuffer? value;
  70   };
  71
  72   // Represents a GATT characteristic descriptor, which provides further
  73   // information about a characteristic's value.
  74   dictionary Descriptor {
  75     // The UUID of the characteristic descriptor, e.g.
  76     // 00002902-0000-1000-8000-00805f9b34fb.
  77     DOMString uuid;
  78
  79     // Indicates whether this descriptor represents a local descriptor
  80     // hosted by the application and available to other peripherals, or a remote
  81     // descriptor hosted and received from a remote peripheral.
  82     [nodoc] boolean isLocal;
  83
  84     // The GATT characteristic this descriptor belongs to.
  85     Characteristic characteristic;
  86
  87     // Returns the identifier assigned to this descriptor. Use the instance ID
  88     // to distinguish between descriptors from a peripheral with the same UUID
  89     // and to make function calls that take in a descriptor identifier. Present,
  90     // if this instance represents a remote characteristic.
  91     DOMString? instanceId;
  92
  93     // The currently cached descriptor value. This value gets updated when
  94     // the value of the descriptor is read.
  95     ArrayBuffer? value;
  96   };
  97
  98   // The connection properties specified during a call to $(ref:connect).
  99   dictionary ConnectProperties {
 100     // Flag indicating whether a connection to the device is left open when the
 101     // event page of the application is unloaded (see <a
 102     // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
 103     // Lifecycle</a>). The default value is <code>false.</code>
 104     boolean persistent;
 105   };
 106
 107   // Optional characteristic notification session properties specified during a
 108   // call to $(ref:startCharacteristicNotifications).
 109   dictionary NotificationProperties {
 110     // Flag indicating whether the app should receive notifications when the
 111     // event page of the application is unloaded (see <a
 112     // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
 113     // Lifecycle</a>). The default value is <code>false</code>.
 114     boolean persistent;
 115   };
 116
 117   callback CharacteristicCallback = void(Characteristic result);
 118   callback CharacteristicsCallback = void(Characteristic[] result);
 119   callback DescriptorCallback = void(Descriptor result);
 120   callback DescriptorsCallback = void(Descriptor[] result);
 121   callback ResultCallback = void();
 122   callback ServiceCallback = void(Service result);
 123   callback ServicesCallback = void(Service[] result);
 124
 125   // These functions all report failures via chrome.runtime.lastError.
 126   interface Functions {
 127     // Establishes a connection between the application and the device with the
 128     // given address. A device may be already connected and its GATT services
 129     // available without calling <code>connect</code>, however, an app that
 130     // wants to access GATT services of a device should call this function to
 131     // make sure that a connection to the device is maintained. If the device
 132     // is not connected, all GATT services of the device will be discovered
 133     // after a successful call to <code>connect</code>.
 134     // |deviceAddress| : The Bluetooth address of the remote device to which a
 135     // GATT connection should be opened.
 136     // |properties| : Connection properties (optional).
 137     // |callback| : Called when the connect request has completed.
 138     static void connect(DOMString deviceAddress,
 139                         optional ConnectProperties properties,
 140                         ResultCallback callback);
 141
 142     // Closes the app's connection to the device with the given address. Note
 143     // that this will not always destroy the physical link itself, since there
 144     // may be other apps with open connections.
 145     // |deviceAddress| : The Bluetooth address of the remote device.
 146     // |callback| : Called when the disconnect request has completed.
 147     static void disconnect(DOMString deviceAddress,
 148                            optional ResultCallback callback);
 149
 150     // Get the GATT service with the given instance ID.
 151     // |serviceId| : The instance ID of the requested GATT service.
 152     // |callback| : Called with the requested Service object.
 153     static void getService(DOMString serviceId, ServiceCallback callback);
 154
 155     // Get all the GATT services that were discovered on the remote device with
 156     // the given device address.
 157     // |deviceAddress| : The Bluetooth address of the remote device whose GATT
 158     // services should be returned.
 159     // |callback| : Called with the list of requested Service objects.
 160     static void getServices(DOMString deviceAddress, ServicesCallback callback);
 161
 162     // Get the GATT characteristic with the given instance ID that belongs to
 163     // the given GATT service, if the characteristic exists.
 164     // |characteristicId| : The instance ID of the requested GATT
 165     // characteristic.
 166     // |callback| : Called with the requested Characteristic object.
 167     static void getCharacteristic(DOMString characteristicId,
 168                                   CharacteristicCallback callback);
 169
 170     // Get a list of all discovered GATT characteristics that belong to the
 171     // given service.
 172     // |serviceId| : The instance ID of the GATT service whose characteristics
 173     // should be returned.
 174     // |callback| : Called with the list of characteristics that belong to the
 175     // given service.
 176     static void getCharacteristics(DOMString serviceId,
 177                                    CharacteristicsCallback callback);
 178
 179     // Get a list of GATT services that are included by the given service.
 180     // |serviceId| : The instance ID of the GATT service whose included
 181     // services should be returned.
 182     // |callback| : Called with the list of GATT services included from the
 183     // given service.
 184     static void getIncludedServices(DOMString serviceId,
 185                                     ServicesCallback callback);
 186
 187     // Get the GATT characteristic descriptor with the given instance ID.
 188     // |descriptorId| : The instance ID of the requested GATT characteristic
 189     // descriptor.
 190     // |callback| : Called with the requested Descriptor object.
 191     static void getDescriptor(DOMString descriptorId,
 192                               DescriptorCallback callback);
 193
 194     // Get a list of GATT characteristic descriptors that belong to the given
 195     // characteristic.
 196     // |characteristicId| : The instance ID of the GATT characteristic whose
 197     // descriptors should be returned.
 198     // |callback| : Called with the list of descriptors that belong to the given
 199     // characteristic.
 200     static void getDescriptors(DOMString characteristicId,
 201                                DescriptorsCallback callback);
 202
 203     // Retrieve the value of a specified characteristic from a remote
 204     // peripheral.
 205     // |characteristicId| : The instance ID of the GATT characteristic whose
 206     // value should be read from the remote device.
 207     // |callback| : Called with the Characteristic object whose value was
 208     // requested. The <code>value</code> field of the returned Characteristic
 209     // object contains the result of the read request.
 210     static void readCharacteristicValue(DOMString characteristicId,
 211                                         CharacteristicCallback callback);
 212
 213     // Write the value of a specified characteristic from a remote peripheral.
 214     // |characteristicId| : The instance ID of the GATT characteristic whose
 215     // value should be written to.
 216     // |value| : The value that should be sent to the remote characteristic as
 217     // part of the write request.
 218     // |callback| : Called when the write request has completed.
 219     static void writeCharacteristicValue(DOMString characteristicId,
 220                                          ArrayBuffer value,
 221                                          ResultCallback callback);
 222
 223     // Enable value notifications/indications from the specified characteristic.
 224     // Once enabled, an application can listen to notifications using the
 225     // $(ref:onCharacteristicValueChanged) event.
 226     // |characteristicId| : The instance ID of the GATT characteristic that
 227     // notifications should be enabled on.
 228     // |properties| : Notification session properties (optional).
 229     // |callback| : Called when the request has completed.
 230     static void startCharacteristicNotifications(
 231         DOMString characteristicId,
 232         optional NotificationProperties properties,
 233         ResultCallback callback);
 234
 235     // Disable value notifications/indications from the specified
 236     // characteristic. After a successful call, the application will stop
 237     // receiving notifications/indications from this characteristic.
 238     // |characteristicId| : The instance ID of the GATT characteristic on which
 239     // this app's notification session should be stopped.
 240     // |callback| : Called when the request has completed (optional).
 241     static void stopCharacteristicNotifications(
 242         DOMString characteristicId,
 243         optional ResultCallback callback);
 244
 245     // Retrieve the value of a specified characteristic descriptor from a remote
 246     // peripheral.
 247     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 248     // whose value should be read from the remote device.
 249     // |callback| : Called with the Descriptor object whose value was requested.
 250     // The <code>value</code> field of the returned Descriptor object contains
 251     // the result of the read request.
 252     static void readDescriptorValue(DOMString descriptorId,
 253                                     DescriptorCallback callback);
 254
 255     // Write the value of a specified characteristic descriptor from a remote
 256     // peripheral.
 257     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 258     // whose value should be written to.
 259     // |value| : The value that should be sent to the remote descriptor as part
 260     // of the write request.
 261     // |callback| : Called when the write request has completed.
 262     static void writeDescriptorValue(DOMString descriptorId,
 263                                      ArrayBuffer value,
 264                                      ResultCallback callback);
 265   };
 266
 267   interface Events {
 268     // Fired whan a new GATT service has been discovered on a remote device.
 269     // |service| : The GATT service that was added.
 270     static void onServiceAdded(Service service);
 271
 272     // Fired when the state of a remote GATT service changes. This involves any
 273     // characteristics and/or descriptors that get added or removed from the
 274     // service, as well as "ServiceChanged" notifications from the remote
 275     // device.
 276     // |service| : The GATT service whose state has changed.
 277     static void onServiceChanged(Service service);
 278
 279     // Fired when a GATT service that was previously discovered on a remote
 280     // device has been removed.
 281     // |service| : The GATT service that was removed.
 282     static void onServiceRemoved(Service service);
 283
 284     // Fired when the value of a remote GATT characteristic changes, either as
 285     // a result of a read request, or a value change notification/indication
 286     // This event will only be sent if the app has enabled notifications by
 287     // calling $(ref:startCharacteristicNotifications).
 288     // |characteristic| : The GATT characteristic whose value has changed.
 289     static void onCharacteristicValueChanged(Characteristic characteristic);
 290
 291     // Fired when the value of a remote GATT characteristic descriptor changes,
 292     // usually as a result of a read request. This event exists
 293     // mostly for convenience and will always be sent after a successful
 294     // call to $(ref:readDescriptorValue).
 295     // |descriptor| : The GATT characteristic descriptor whose value has
 296     // changed.
 297     static void onDescriptorValueChanged(Descriptor descriptor);
 298   };
 299 };