Home | History | Annotate | Download | only in api 
      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 };
    157