chrome/common/extensions/api/bluetooth.idl

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.bluetooth</code> API to connect to a Bluetooth
// device. All functions report failures via chrome.runtime.lastError.
namespace bluetooth {
  // Allocation authorities for Vendor IDs.
  enum VendorIdSource {bluetooth, usb};

  // Common device types recognized by Chrome.
  enum DeviceType {computer, phone, modem, audio, carAudio, video, peripheral,
                   joystick, gamepad, keyboard, mouse, tablet,
                   keyboardMouseCombo};

  // Information about the state of the Bluetooth adapter.
  dictionary AdapterState {
    // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
    DOMString address;

    // The human-readable name of the adapter.
    DOMString name;

    // Indicates whether or not the adapter has power.
    boolean powered;

    // Indicates whether or not the adapter is available (i.e. enabled).
    boolean available;

    // Indicates whether or not the adapter is currently discovering.
    boolean discovering;
  };

  // Callback from the <code>getAdapterState</code> method.
  // |adapterInfo| : Object containing the adapter information.
  callback AdapterStateCallback = void(AdapterState adapterInfo);

  // Information about the state of a known Bluetooth device.
  dictionary Device {
    // The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
    DOMString address;

    // The human-readable name of the device.
    DOMString? name;

    // The class of the device, a bit-field defined by
    // http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
    long? deviceClass;

    // The Device ID record of the device, where available.
    VendorIdSource? vendorIdSource;
    long? vendorId;
    long? productId;
    long? deviceId;

    // The type of the device, if recognized by Chrome. This is obtained from
    // the |deviceClass| field and only represents a small fraction of the
    // possible device types. When in doubt you should use the |deviceClass|
    // field directly.
    DeviceType? type;

    // Indicates whether or not the device is paired with the system.
    boolean? paired;

    // Indicates whether the device is currently connected to the system.
    boolean? connected;

    // Indicates the RSSI ("received signal strength indication") of the
    // connection to the device, measured in dBm, to a resolution of 1dBm.
    // If the device is currently connected, then measures the RSSI of the
    // connection signal. Otherwise, measures the RSSI of the last inquiry sent
    // to the device, where available. Absent if unavailable.
    [nodoc] long? rssi;

    // Indicates the host's current transmit power ("Tx power") for the
    // connection to the device, measured in dBm, to a resolution of 1dBm.
    // This value is only available if the device is currently connected.
    [nodoc] long? currentHostTransmitPower;

    // Indicates the host's maximum transmit power ("Tx power") for the
    // connection to the device, measured in dBm, to a resolution of 1dBm.
    // This value is only available if the device is currently connected.
    [nodoc] long? maximumHostTransmitPower;

    // UUIDs of protocols, profiles and services advertised by the device.
    // For classic Bluetooth devices, this list is obtained from EIR data and
    // SDP tables. For Low Energy devices, this list is obtained from AD and
    // GATT primary services. For dual mode devices this may be obtained from
    // both.
    DOMString[]? uuids;
  };

  // Callback from the <code>getDevice</code> method.
  // |deviceInfo| : Object containing the device information.
  callback GetDeviceCallback = void(Device deviceInfo);

  // Callback from the <code>getDevices</code> method.
  // |deviceInfos| : Array of object containing device information.
  callback GetDevicesCallback = void(Device[] deviceInfos);

  // Callback from the <code>startDiscovery</code> method.
  callback StartDiscoveryCallback = void();

  // Callback from the <code>stopDiscovery</code> method.
  callback StopDiscoveryCallback = void();

  // These functions all report failures via chrome.runtime.lastError.
  interface Functions {
    // Get information about the Bluetooth adapter.
    // |callback| : Called with an AdapterState object describing the adapter
    //              state.
    static void getAdapterState(AdapterStateCallback callback);

    // Get information about a Bluetooth device known to the system.
    // |deviceAddress| : Address of device to get.
    // |callback| : Called with the Device object describing the device.
    static void getDevice(DOMString deviceAddress, GetDeviceCallback callback);

    // Get a list of Bluetooth devices known to the system, including paired
    // and recently discovered devices.
    // |callback| : Called when the search is completed.
    static void getDevices(GetDevicesCallback callback);

    // Start discovery. Newly discovered devices will be returned via the
    // onDeviceAdded event. Previously discovered devices already known to
    // the adapter must be obtained using getDevices and will only be updated
    // using the |onDeviceChanged| event if information about them changes.
    //
    // Discovery will fail to start if this application has already called
    // startDiscovery.  Discovery can be resource intensive: stopDiscovery
    // should be called as soon as possible.
    // |callback| : Called to indicate success or failure.
    static void startDiscovery(optional StartDiscoveryCallback callback);

    // Stop discovery.
    // |callback| : Called to indicate success or failure.
    static void stopDiscovery(optional StopDiscoveryCallback callback);
  };

  interface Events {
    // Fired when the state of the Bluetooth adapter changes.
    // |state| : The new state of the adapter.
    static void onAdapterStateChanged(AdapterState state);

    // Fired when information about a new Bluetooth device is available.
    static void onDeviceAdded(Device device);

    // Fired when information about a known Bluetooth device has changed.
    static void onDeviceChanged(Device device);

    // Fired when a Bluetooth device that was previously discovered has been
    // out of range for long enough to be considered unavailable again, and
    // when a paired device is removed.
    static void onDeviceRemoved(Device device);
  };
};