chrome/common/extensions/api/bluetooth.idl

   1 // Copyright (c) 2012 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 // Use the <code>chrome.bluetooth</code> API to connect to a Bluetooth
   6 // device. All functions report failures via chrome.runtime.lastError.
   7 namespace bluetooth {
   8   dictionary AdapterState {
   9     // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
  10     DOMString address;
  11
  12     // The human-readable name of the adapter.
  13     DOMString name;
  14
  15     // Indicates whether or not the adapter has power.
  16     boolean powered;
  17
  18     // Indicates whether or not the adapter is available (i.e. enabled).
  19     boolean available;
  20
  21     // Indicates whether or not the adapter is currently discovering.
  22     boolean discovering;
  23   };
  24
  25   dictionary Device {
  26     // The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
  27     DOMString address;
  28
  29     // The human-readable name of the device.
  30     DOMString? name;
  31
  32     // Indicates whether or not the device is paired with the system.
  33     boolean? paired;
  34
  35     // Indicates whether the device is currently connected to the system.
  36     boolean? connected;
  37   };
  38
  39   dictionary Profile {
  40     // Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
  41     DOMString uuid;
  42
  43     // Human-readable name of the Profile, e.g. "Health Device"
  44     DOMString? name;
  45
  46     // The RFCOMM channel id, used when the profile is to be exported to remote
  47     // devices.
  48     long? channel;
  49
  50     // The LS2CAP PSM number, used when the profile is to be exported to remote
  51     // deviecs.
  52     long? psm;
  53
  54     // Specifies whether pairing (and encryption) is required to be able to
  55     // connect.
  56     boolean? requireAuthentication;
  57
  58     // Specifies whether user authorization is required to be able to connect.
  59     boolean? requireAuthorization;
  60
  61     // Specifies whether this profile will be automatically connected if any
  62     // other profile of device also exporting this profile connects to the host.
  63     boolean? autoConnect;
  64
  65     // Specifies the implemented version of the profile.
  66     long? version;
  67
  68     // Specifies the profile-specific bit field of features the implementation
  69     // supports.
  70     long? features;
  71   };
  72
  73   dictionary ServiceRecord {
  74     // The name of the service.
  75     DOMString name;
  76
  77     // The UUID of the service.
  78     DOMString? uuid;
  79   };
  80
  81   dictionary Socket {
  82     // The remote Bluetooth device associated with this socket.
  83     Device device;
  84
  85     // The remote Bluetooth profile associated with this socket.
  86     Profile profile;
  87
  88     // An identifier for this socket that should be used with the
  89     // read/write/disconnect methods.
  90     long id;
  91   };
  92
  93   dictionary OutOfBandPairingData {
  94     // Simple Pairing Hash C.
  95     // Always 16 octets long.
  96     ArrayBuffer hash;
  97
  98     // Simple Pairing Randomizer R.
  99     // Always 16 octets long.
 100     ArrayBuffer randomizer;
 101   };
 102
 103   callback AdapterStateCallback = void(AdapterState result);
 104   callback AddressCallback = void (DOMString result);
 105   callback BooleanCallback = void (boolean result);
 106   callback DataCallback = void (optional ArrayBuffer result);
 107   callback DeviceCallback = void (Device device);
 108   callback DevicesCallback = void (Device[] result);
 109   callback NameCallback = void (DOMString result);
 110   callback OutOfBandPairingDataCallback = void (OutOfBandPairingData data);
 111   callback ProfilesCallback = void(Profile[] result);
 112   callback ResultCallback = void ();
 113   callback ServicesCallback = void(ServiceRecord[] result);
 114   callback SizeCallback = void (long result);
 115   callback SocketCallback = void (Socket result);
 116
 117   // Options for the getDevices function. If |profile| is not provided, all
 118   // devices known to the system are returned.
 119   dictionary GetDevicesOptions {
 120     // Only devices providing |profile| will be returned.
 121     Profile? profile;
 122
 123     // Called for each matching device.  Note that a service discovery request
 124     // must be made to each non-matching device before it can be definitively
 125     // excluded.  This can take some time.
 126     DeviceCallback deviceCallback;
 127   };
 128
 129   // Options for the getProfiles function.
 130   dictionary GetProfilesOptions {
 131     // The remote Bluetooth device to retrieve the exported profiles list from.
 132     Device device;
 133   };
 134
 135   // Options for the getServices function.
 136   dictionary GetServicesOptions {
 137     // The address of the device to inquire about. |deviceAddress| should be
 138     // in the format 'XX:XX:XX:XX:XX:XX'.
 139     DOMString deviceAddress;
 140   };
 141
 142   // Options for the connect function.
 143   dictionary ConnectOptions {
 144     // The connection is made to |device|.
 145     Device device;
 146
 147     // The connection is made to |profile|.
 148     Profile profile;
 149   };
 150
 151   // Options for the disconnect function.
 152   dictionary DisconnectOptions {
 153     // The socket to disconnect.
 154     Socket socket;
 155   };
 156
 157   // Options for the read function.
 158   dictionary ReadOptions {
 159     // The socket to read from.
 160     Socket socket;
 161   };
 162
 163   // Options for the write function.
 164   dictionary WriteOptions {
 165     // The socket to write to.
 166     Socket socket;
 167
 168     // The data to write.
 169     ArrayBuffer data;
 170   };
 171
 172   // Options for the setOutOfBandPairingData function.
 173   dictionary SetOutOfBandPairingDataOptions {
 174     // The address of the remote device that the data should be associated
 175     // with. |deviceAddress| should be in the format 'XX:XX:XX:XX:XX:XX'.
 176     DOMString address;
 177
 178     // The Out Of Band Pairing Data. If this is omitted, the data for the
 179     // device is cleared instead.
 180     OutOfBandPairingData? data;
 181   };
 182
 183   // Options for the startDiscovery function.
 184   dictionary StartDiscoveryOptions {
 185     // Called for each device that is discovered.
 186     DeviceCallback deviceCallback;
 187   };
 188
 189   // These functions all report failures via chrome.runtime.lastError.
 190   interface Functions {
 191     // Registers the JavaScript application as an implementation for the given
 192     // Profile; if a channel or PSM is specified, the profile will be exported
 193     // in the host's SDP and GATT tables and advertised to other devices.
 194     static void addProfile(Profile profile, ResultCallback callback);
 195
 196     // Unregisters the JavaScript application as an implementation for the given
 197     // Profile; only the uuid field of the Profile object is used.
 198     static void removeProfile(Profile profile, ResultCallback callback);
 199
 200     // Get information about the Bluetooth adapter.
 201     // |callback| : Called with an AdapterState object describing the adapter
 202     //              state.
 203     static void getAdapterState(AdapterStateCallback callback);
 204
 205     // Get a bluetooth devices known to the system.  Known devices are either
 206     // currently paired, or have been paired in the past.
 207     // |options|  : Controls which devices are returned and provides
 208     //              |deviceCallback|, which is called for each matching device.
 209     // |callback| : Called when the search is completed.
 210     //              |options.deviceCallback| will not be called after
 211     //              |callback| has been called.
 212     static void getDevices(GetDevicesOptions options,
 213                            ResultCallback callback);
 214
 215     // Returns the set of exported profiles for the device specified in options.
 216     // This function will not initiate a connection to the remote device.
 217     static void getProfiles(GetProfilesOptions options,
 218                             ProfilesCallback callback);
 219
 220     // Get a list of services provided by a device.
 221     static void getServices(GetServicesOptions options,
 222                             ServicesCallback callback);
 223
 224     // Connect to a service on a device.
 225     // |options|  : The options for the connection.
 226     // |callback| : Called to indicate success or failure.
 227     static void connect(ConnectOptions options,
 228                         ResultCallback callback);
 229
 230     // Close a Bluetooth connection.
 231     // |options|  : The options for this function.
 232     // |callback| : Called to indicate success or failure.
 233     static void disconnect(DisconnectOptions options,
 234                            optional ResultCallback callback);
 235
 236     // Read data from a Bluetooth connection. The |callback| will be called
 237     // with the current data in the buffer even if it is empty. This function
 238     // should be polled to read incoming data.
 239     // |options|  : The options for this function.
 240     // |callback| : Called with the data read from the socket buffer.
 241     static void read(ReadOptions options,
 242                      DataCallback callback);
 243
 244     // Write data to a Bluetooth connection.
 245     // |options|  : The options for this function.
 246     // |callback| : Called with the number of bytes written.
 247     static void write(WriteOptions options,
 248                       optional SizeCallback callback);
 249
 250     // Get the local Out of Band Pairing data.
 251     // |callback| : Called with the data.
 252     static void getLocalOutOfBandPairingData(
 253         OutOfBandPairingDataCallback callback);
 254
 255     // Set the Out of Band Pairing data for a remote device.
 256     // Any previous Out Of Band Pairing Data for this device is overwritten.
 257     // |options|  : The options for this function.
 258     // |callback| : Called to indicate success or failure.
 259     static void setOutOfBandPairingData(SetOutOfBandPairingDataOptions options,
 260                                         optional ResultCallback callback);
 261
 262     // Start discovery. Discovered devices will be returned via the
 263     // |onDeviceDiscovered| callback.  Discovery will fail to start if it is
 264     // already in progress.  Discovery can be resource intensive: stopDiscovery
 265     // should be called as soon as possible.
 266     // |options|  : The options for this function.
 267     // |callback| : Called to indicate success or failure.
 268     static void startDiscovery(
 269         StartDiscoveryOptions options,
 270         optional ResultCallback callback);
 271
 272     // Stop discovery.
 273     // |callback| : Called to indicate success or failure.
 274     static void stopDiscovery(
 275         optional ResultCallback callback);
 276   };
 277
 278   interface Events {
 279     // Fired when the state of the Bluetooth adapter changes.
 280     // |state| : The new state of the adapter.
 281     static void onAdapterStateChanged(AdapterState state);
 282
 283     // Fired when a connection has been made for a registered profile.
 284     // |socket| : The socket for the connection.
 285     static void onConnection(Socket socket);
 286   };
 287 };