chrome/common/extensions/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                                writeableAuxiliaries};
  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     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     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, written, or updated via a
  68     // notification or indication. For local characteristics, this is the value
  69     // that will be returned upon requests from remote peripherals by default.
  70     ArrayBuffer? value;
  71   };
  72
  73   // Represents a GATT characteristic descriptor, which provides further
  74   // information about a characteristic's value.
  75   dictionary Descriptor {
  76     // The UUID of the characteristic descriptor, e.g.
  77     // 00002902-0000-1000-8000-00805f9b34fb.
  78     DOMString uuid;
  79
  80     // Indicates whether this descriptor represents a local descriptor
  81     // hosted by the application and available to other peripherals, or a remote
  82     // descriptor hosted and received from a remote peripheral.
  83     boolean isLocal;
  84
  85     // The GATT characteristic this descriptor belongs to.
  86     Characteristic characteristic;
  87
  88     // Returns the identifier assigned to this descriptor. Use the instance ID
  89     // to distinguish between descriptors from a peripheral with the same UUID
  90     // and to make function calls that take in a descriptor identifier. Present,
  91     // if this instance represents a remote characteristic.
  92     DOMString? instanceId;
  93
  94     // The currently cached descriptor value. This value gets updated when
  95     // the value of the descriptor is read or written. For local descriptors,
  96     // this is the value that will be returned upon requests from remote
  97     // peripherals by default.
  98     ArrayBuffer? value;
  99   };
 100
 101   callback CharacteristicCallback = void(Characteristic result);
 102   callback CharacteristicsCallback = void(Characteristic[] result);
 103   callback DescriptorCallback = void(Descriptor result);
 104   callback DescriptorsCallback = void(Descriptor[] result);
 105   callback ResultCallback = void();
 106   callback ServiceCallback = void(Service result);
 107   callback ServicesCallback = void(Service[] result);
 108
 109   // These functions all report failures via chrome.runtime.lastError.
 110   interface Functions {
 111     // Get the GATT service with the given instance ID.
 112     // |serviceId| : The instance ID of the requested GATT service.
 113     // |callback| : Called with the requested Service object.
 114     static void getService(DOMString serviceId, ServiceCallback callback);
 115
 116     // Get all the GATT services that were discovered on the remote device with
 117     // the given device address.
 118     // |deviceAddress| : The Bluetooth Address of the remote device whose GATT
 119     // services should be returned.
 120     // |callback| : Called with the list of requested Service objects.
 121     static void getServices(DOMString deviceAddress, ServicesCallback callback);
 122
 123     // Get the GATT characteristic with the given instance ID that belongs to
 124     // the given GATT service, if the characteristic exists.
 125     // |characteristicId| : The instance ID of the requested GATT
 126     // characteristic.
 127     // |callback| : Called with the requested Characteristic object.
 128     static void getCharacteristic(DOMString characteristicId,
 129                                   CharacteristicCallback callback);
 130
 131     // Get a list of all discovered GATT characteristics that belong to the
 132     // given service.
 133     // |serviceId| : The instance ID of the GATT service whose characteristics
 134     // should be returned.
 135     // |callback| : Called with the list of characteristics that belong to the
 136     // given service.
 137     static void getCharacteristics(DOMString serviceId,
 138                                    CharacteristicsCallback callback);
 139
 140     // Get a list of GATT services that are included by the given service.
 141     // |serviceId| : The instance ID of the GATT service whose included
 142     // services should be returned.
 143     // |callback| : Called with the list of GATT services included from the
 144     // given service.
 145     static void getIncludedServices(DOMString serviceId,
 146                                     ServicesCallback callback);
 147
 148     // Get the GATT characteristic descriptor with the given instance ID.
 149     // |descriptorId| : The instance ID of the requested GATT characteristic
 150     // descriptor.
 151     // |callback| : Called with the requested Descriptor object.
 152     static void getDescriptor(DOMString descriptorId,
 153                               DescriptorCallback callback);
 154
 155     // Get a list of GATT characteristic descriptors that belong to the given
 156     // characteristic.
 157     // |characteristicId| : The instance ID of the GATT characteristic whose
 158     // descriptors should be returned.
 159     // |callback| : Called with the list of descriptors that belong to the given
 160     // characteristic.
 161     static void getDescriptors(DOMString characteristicId,
 162                                DescriptorsCallback callback);
 163
 164     // Retrieve the value of a specified characteristic from a remote
 165     // peripheral. This function will fail if the characteristic is local.
 166     // |characteristicId| : The instance ID of the GATT characteristic whose
 167     // value should be read from the remote device.
 168     // |callback| : Called with the Characteristic object whose value was
 169     // requested. The <code>value</code> field of the returned Characteristic
 170     // object contains the result of the read request.
 171     static void readCharacteristicValue(DOMString characteristicId,
 172                                         CharacteristicCallback callback);
 173
 174     // Write the value of a specified characteristic from a remote peripheral.
 175     // This function will fail if the characteristic is local.
 176     // |characteristicId| : The instance ID of the GATT characteristic whose
 177     // value should be written to.
 178     // |value| : The value that should be sent to the remote characteristic as
 179     // part of the write request.
 180     // |callback| : Called when the write request has completed.
 181     static void writeCharacteristicValue(DOMString characteristicId,
 182                                          ArrayBuffer value,
 183                                          ResultCallback callback);
 184
 185     // Retrieve the value of a specified characteristic descriptor from a remote
 186     // peripheral. This function will fail if the descriptor is local.
 187     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 188     // whose value should be read from the remote device.
 189     // |callback| : Called with the Descriptor object whose value was requested.
 190     // The <code>value</code> field of the returned Descriptor object contains
 191     // the result of the read request.
 192     static void readDescriptorValue(DOMString descriptorId,
 193                                     DescriptorCallback callback);
 194
 195     // Write the value of a specified characteristic descriptor from a remote
 196     // peripheral. This function will fail if the descriptor is local.
 197     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 198     // whose value should be written to.
 199     // |value| : The value that should be sent to the remote descriptor as part
 200     // of the write request.
 201     // |callback| : Called when the write request has completed.
 202     static void writeDescriptorValue(DOMString descriptorId,
 203                                      ArrayBuffer value,
 204                                      ResultCallback callback);
 205   };
 206
 207   interface Events {
 208     // Fired whan a new GATT service has been discovered on a remote device.
 209     // |service| : The GATT service that was added.
 210     static void onServiceAdded(Service service);
 211
 212     // Fired when the state of a remote GATT service changes. This involves any
 213     // characteristics and/or descriptors that get added or removed from the
 214     // service, as well as "ServiceChanged" notifications from the remote
 215     // device.
 216     // |service| : The GATT service whose state has changed.
 217     static void onServiceChanged(Service service);
 218
 219     // Fired when a GATT service that was previously discovered on a remote
 220     // device has been removed.
 221     // |service| : The GATT service that was removed.
 222     static void onServiceRemoved(Service service);
 223
 224     // Fired when the value of a remote GATT characteristic changes, either as
 225     // a result of a read or write request, or a value change notification or
 226     // indication.
 227     // |characteristic| : The GATT characteristic whose value has changed.
 228     static void onCharacteristicValueChanged(Characteristic characteristic);
 229
 230     // Fired when the value of a remote GATT characteristic descriptor changes,
 231     // usually as a result of a read or write request.
 232     // |descriptor| : The GATT characteristic descriptor whose value has
 233     // changed.
 234     static void onDescriptorValueChanged(Descriptor descriptor);
 235   };
 236 };