src/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.
   7 namespace bluetoothLowEnergy {
   8   // Values representing the possible properties of a characteristic.
   9   enum CharacteristicProperty {broadcast, read, writeWithoutResponse, write,
  10                                notify, indicate, authenticatedSignedWrites,
  11                                extendedProperties, reliableWrite,
  12                                writeableAuxiliaries};
  13
  14   // Represents a peripheral's Bluetooth GATT Service, a collection of
  15   // characteristics and relationships to other services that encapsulate
  16   // the behavior of part of a device.
  17   dictionary Service {
  18     // The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.
  19     DOMString uuid;
  20
  21     // Indicates whether the type of this service is primary or secondary.
  22     boolean isPrimary;
  23
  24     // Indicates whether this service represents a local service hosted by the
  25     // application and available to other peripherals, or a remote service
  26     // hosted and received from a remote peripheral.
  27     boolean isLocal;
  28
  29     // Returns the identifier assigned to this service. Use the instance ID to
  30     // distinguish between services from a peripheral with the same UUID and
  31     // to make function calls that take in a service identifier. Present, if
  32     // this instance represents a remote service.
  33     DOMString? instanceId;
  34
  35     // The device address of the remote peripheral that the GATT service belongs
  36     // to. Present, if this instance represents a remote service.
  37     DOMString? deviceAddress;
  38   };
  39
  40   // Represents a GATT characteristic, which is a basic data element that
  41   // provides further information about a peripheral's service.
  42   dictionary Characteristic {
  43     // The UUID of the characteristic, e.g.
  44     // 00002a37-0000-1000-8000-00805f9b34fb.
  45     DOMString uuid;
  46
  47     // Indicates whether this characteristic represents a local characteristic
  48     // hosted by the application and available to other peripherals, or a remote
  49     // characteristic hosted and received from a remote peripheral.
  50     boolean isLocal;
  51
  52     // The GATT service this characteristic belongs to.
  53     Service service;
  54
  55     // The properties of this characteristic.
  56     CharacteristicProperty[] properties;
  57
  58     // Returns the identifier assigned to this characteristic. Use the instance
  59     // ID to distinguish between characteristics from a peripheral with the same
  60     // UUID and to make function calls that take in a characteristic identifier.
  61     // Present, if this instance represents a remote characteristic.
  62     DOMString? instanceId;
  63
  64     // The currently cached characteristic value. This value gets updated when
  65     // the value of the characteristic is read, written, or updated via a
  66     // notification or indication. For local characteristics, this is the value
  67     // that will be returned upon requests from remote peripherals by default.
  68     ArrayBuffer? value;
  69   };
  70
  71   // Represents a GATT characteristic descriptor, which provides further
  72   // information about a characteristic's value.
  73   dictionary Descriptor {
  74     // The UUID of the characteristic descriptor, e.g.
  75     // 00002902-0000-1000-8000-00805f9b34fb.
  76     DOMString uuid;
  77
  78     // Indicates whether this descriptor represents a local descriptor
  79     // hosted by the application and available to other peripherals, or a remote
  80     // descriptor hosted and received from a remote peripheral.
  81     boolean isLocal;
  82
  83     // The GATT characteristic this descriptor belongs to.
  84     Characteristic characteristic;
  85
  86     // Returns the identifier assigned to this descriptor. Use the instance ID
  87     // to distinguish between descriptors from a peripheral with the same UUID
  88     // and to make function calls that take in a descriptor identifier. Present,
  89     // if this instance represents a remote characteristic.
  90     DOMString? instanceId;
  91
  92     // The currently cached descriptor value. This value gets updated when
  93     // the value of the descriptor is read or written. For local descriptors,
  94     // this is the value that will be returned upon requests from remote
  95     // peripherals by default.
  96     ArrayBuffer? value;
  97   };
  98
  99   callback CharacteristicCallback = void(Characteristic result);
 100   callback CharacteristicsCallback = void(Characteristic[] result);
 101   callback DescriptorCallback = void(Descriptor result);
 102   callback DescriptorsCallback = void(Descriptor[] result);
 103   callback ResultCallback = void();
 104   callback ServiceCallback = void(Service result);
 105   callback ServicesCallback = void(Service[] result);
 106
 107   // These functions all report failures via chrome.runtime.lastError.
 108   interface Functions {
 109     // Get the GATT service with the given instance ID.
 110     // |serviceId| : The instance ID of the requested GATT service.
 111     // |callback| : Called with the requested Service object.
 112     static void getService(DOMString serviceId, ServiceCallback callback);
 113
 114     // Get all the GATT services that were discovered on the remote device with
 115     // the given device address.
 116     // |deviceAddress| : The Bluetooth Address of the remote device whose GATT
 117     // services should be returned.
 118     // |callback| : Called with the list of requested Service objects.
 119     static void getServices(DOMString deviceAddress, ServicesCallback callback);
 120
 121     // Get the GATT characteristic with the given instance ID that belongs to
 122     // the given GATT service, if the characteristic exists.
 123     // |characteristicId| : The instance ID of the requested GATT
 124     // characteristic.
 125     // |callback| : Called with the requested Characteristic object.
 126     static void getCharacteristic(DOMString characteristicId,
 127                                   CharacteristicCallback callback);
 128
 129     // Get a list of all discovered GATT characteristics that belong to the
 130     // given service.
 131     // |serviceId| : The instance ID of the GATT service whose characteristics
 132     // should be returned.
 133     // |callback| : Called with the list of characteristics that belong to the
 134     // given service.
 135     static void getCharacteristics(DOMString serviceId,
 136                                    CharacteristicsCallback callback);
 137
 138     // Get a list of GATT services that are included by the given service.
 139     // |serviceId| : The instance ID of the GATT service whose included
 140     // services should be returned.
 141     // |callback| : Called with the list of GATT services included from the
 142     // given service.
 143     static void getIncludedServices(DOMString serviceId,
 144                                     ServicesCallback callback);
 145
 146     // Get the GATT characteristic descriptor with the given instance ID.
 147     // |descriptorId| : The instance ID of the requested GATT characteristic
 148     // descriptor.
 149     // |callback| : Called with the requested Descriptor object.
 150     static void getDescriptor(DOMString descriptorId,
 151                               DescriptorCallback callback);
 152
 153     // Get a list of GATT characteristic descriptors that belong to the given
 154     // characteristic.
 155     // |characteristicId| : The instance ID of the GATT characteristic whose
 156     // descriptors should be returned.
 157     // |callback| : Called with the list of descriptors that belong to the given
 158     // characteristic.
 159     static void getDescriptors(DOMString characteristicId,
 160                                DescriptorsCallback callback);
 161
 162     // Retrieve the value of a specified characteristic from a remote
 163     // peripheral. This function will fail if the characteristic is local.
 164     // |characteristicId| : The instance ID of the GATT characteristic whose
 165     // value should be read from the remote device.
 166     // |callback| : Called with the Characteristic object whose value was
 167     // requested. The <code>value</code> field of the returned Characteristic
 168     // object contains the result of the read request.
 169     static void readCharacteristicValue(DOMString characteristicId,
 170                                         CharacteristicCallback callback);
 171
 172     // Write the value of a specified characteristic from a remote peripheral.
 173     // This function will fail if the characteristic is local.
 174     // |characteristicId| : The instance ID of the GATT characteristic whose
 175     // value should be written to.
 176     // |value| : The value that should be sent to the remote characteristic as
 177     // part of the write request.
 178     // |callback| : Called when the write request has completed.
 179     static void writeCharacteristicValue(DOMString characteristicId,
 180                                          ArrayBuffer value,
 181                                          ResultCallback callback);
 182
 183     // Retrieve the value of a specified characteristic descriptor from a remote
 184     // peripheral. This function will fail if the descriptor is local.
 185     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 186     // whose value should be read from the remote device.
 187     // |callback| : Called with the Descriptor object whose value was requested.
 188     // The <code>value</code> field of the returned Descriptor object contains
 189     // the result of the read request.
 190     static void readDescriptorValue(DOMString descriptorId,
 191                                     DescriptorCallback callback);
 192
 193     // Write the value of a specified characteristic descriptor from a remote
 194     // peripheral. This function will fail if the descriptor is local.
 195     // |descriptorId| : The instance ID of the GATT characteristic descriptor
 196     // whose value should be written to.
 197     // |value| : The value that should be sent to the remote descriptor as part
 198     // of the write request.
 199     // |callback| : Called when the write request has completed.
 200     static void writeDescriptorValue(DOMString descriptorId,
 201                                      ArrayBuffer value,
 202                                      ResultCallback callback);
 203   };
 204
 205   interface Events {
 206     // Fired whan a new GATT service has been discovered on a remote device.
 207     // |service| : The GATT service that was added.
 208     static void onServiceAdded(Service service);
 209
 210     // Fired when the state of a remote GATT service changes. This involves any
 211     // characteristics and/or descriptors that get added or removed from the
 212     // service, as well as "ServiceChanged" notifications from the remote
 213     // device.
 214     // |service| : The GATT service whose state has changed.
 215     static void onServiceChanged(Service service);
 216
 217     // Fired when a GATT service that was previously discovered on a remote
 218     // device has been removed.
 219     // |service| : The GATT service that was removed.
 220     static void onServiceRemoved(Service service);
 221
 222     // Fired when the value of a remote GATT characteristic changes, either as
 223     // a result of a read or write request, or a value change notification or
 224     // indication.
 225     // |characteristic| : The GATT characteristic whose value has changed.
 226     static void onCharacteristicValueChanged(Characteristic characteristic);
 227   };
 228 };