extensions/common/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   // Allocation authorities for Vendor IDs.
   9   enum VendorIdSource {bluetooth, usb};
  10
  11   // Common device types recognized by Chrome.
  12   enum DeviceType {computer, phone, modem, audio, carAudio, video, peripheral,
  13                    joystick, gamepad, keyboard, mouse, tablet,
  14                    keyboardMouseCombo};
  15
  16   // Information about the state of the Bluetooth adapter.
  17   dictionary AdapterState {
  18     // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
  19     DOMString address;
  20
  21     // The human-readable name of the adapter.
  22     DOMString name;
  23
  24     // Indicates whether or not the adapter has power.
  25     boolean powered;
  26
  27     // Indicates whether or not the adapter is available (i.e. enabled).
  28     boolean available;
  29
  30     // Indicates whether or not the adapter is currently discovering.
  31     boolean discovering;
  32   };
  33
  34   // Callback from the <code>getAdapterState</code> method.
  35   // |adapterInfo| : Object containing the adapter information.
  36   callback AdapterStateCallback = void(AdapterState adapterInfo);
  37
  38   // Information about the state of a known Bluetooth device.
  39   dictionary Device {
  40     // The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
  41     DOMString address;
  42
  43     // The human-readable name of the device.
  44     DOMString? name;
  45
  46     // The class of the device, a bit-field defined by
  47     // http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
  48     long? deviceClass;
  49
  50     // The Device ID record of the device, where available.
  51     VendorIdSource? vendorIdSource;
  52     long? vendorId;
  53     long? productId;
  54     long? deviceId;
  55
  56     // The type of the device, if recognized by Chrome. This is obtained from
  57     // the |deviceClass| field and only represents a small fraction of the
  58     // possible device types. When in doubt you should use the |deviceClass|
  59     // field directly.
  60     DeviceType? type;
  61
  62     // Indicates whether or not the device is paired with the system.
  63     boolean? paired;
  64
  65     // Indicates whether the device is currently connected to the system.
  66     boolean? connected;
  67
  68     // Indicates the RSSI ("received signal strength indication") of the
  69     // connection to the device, measured in dBm, to a resolution of 1dBm.
  70     // If the device is currently connected, then measures the RSSI of the
  71     // connection signal. Otherwise, measures the RSSI of the last inquiry sent
  72     // to the device, where available. Absent if unavailable.
  73     [nodoc] long? rssi;
  74
  75     // Indicates the host's current transmit power ("Tx power") for the
  76     // connection to the device, measured in dBm, to a resolution of 1dBm.
  77     // This value is only available if the device is currently connected.
  78     [nodoc] long? currentHostTransmitPower;
  79
  80     // Indicates the host's maximum transmit power ("Tx power") for the
  81     // connection to the device, measured in dBm, to a resolution of 1dBm.
  82     // This value is only available if the device is currently connected.
  83     [nodoc] long? maximumHostTransmitPower;
  84
  85     // UUIDs of protocols, profiles and services advertised by the device.
  86     // For classic Bluetooth devices, this list is obtained from EIR data and
  87     // SDP tables. For Low Energy devices, this list is obtained from AD and
  88     // GATT primary services. For dual mode devices this may be obtained from
  89     // both.
  90     DOMString[]? uuids;
  91   };
  92
  93   // Callback from the <code>getDevice</code> method.
  94   // |deviceInfo| : Object containing the device information.
  95   callback GetDeviceCallback = void(Device deviceInfo);
  96
  97   // Callback from the <code>getDevices</code> method.
  98   // |deviceInfos| : Array of object containing device information.
  99   callback GetDevicesCallback = void(Device[] deviceInfos);
 100
 101   // Callback from the <code>startDiscovery</code> method.
 102   callback StartDiscoveryCallback = void();
 103
 104   // Callback from the <code>stopDiscovery</code> method.
 105   callback StopDiscoveryCallback = void();
 106
 107   // These functions all report failures via chrome.runtime.lastError.
 108   interface Functions {
 109     // Get information about the Bluetooth adapter.
 110     // |callback| : Called with an AdapterState object describing the adapter
 111     //              state.
 112     static void getAdapterState(AdapterStateCallback callback);
 113
 114     // Get information about a Bluetooth device known to the system.
 115     // |deviceAddress| : Address of device to get.
 116     // |callback| : Called with the Device object describing the device.
 117     static void getDevice(DOMString deviceAddress, GetDeviceCallback callback);
 118
 119     // Get a list of Bluetooth devices known to the system, including paired
 120     // and recently discovered devices.
 121     // |callback| : Called when the search is completed.
 122     static void getDevices(GetDevicesCallback callback);
 123
 124     // Start discovery. Newly discovered devices will be returned via the
 125     // onDeviceAdded event. Previously discovered devices already known to
 126     // the adapter must be obtained using getDevices and will only be updated
 127     // using the |onDeviceChanged| event if information about them changes.
 128     //
 129     // Discovery will fail to start if this application has already called
 130     // startDiscovery.  Discovery can be resource intensive: stopDiscovery
 131     // should be called as soon as possible.
 132     // |callback| : Called to indicate success or failure.
 133     static void startDiscovery(optional StartDiscoveryCallback callback);
 134
 135     // Stop discovery.
 136     // |callback| : Called to indicate success or failure.
 137     static void stopDiscovery(optional StopDiscoveryCallback callback);
 138   };
 139
 140   interface Events {
 141     // Fired when the state of the Bluetooth adapter changes.
 142     // |state| : The new state of the adapter.
 143     static void onAdapterStateChanged(AdapterState state);
 144
 145     // Fired when information about a new Bluetooth device is available.
 146     static void onDeviceAdded(Device device);
 147
 148     // Fired when information about a known Bluetooth device has changed.
 149     static void onDeviceChanged(Device device);
 150
 151     // Fired when a Bluetooth device that was previously discovered has been
 152     // out of range for long enough to be considered unavailable again, and
 153     // when a paired device is removed.
 154     static void onDeviceRemoved(Device device);
 155   };
 156 };