extensions/common/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};

  // Types for filtering bluetooth devices.
  enum FilterType {all, known};

  // 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. Note: this
  // dictionary is also used in bluetooth_private.idl
  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 whether the device is currently connecting to the system.
    boolean? connecting;

    // Indicates whether the device is connectable.
    boolean? connectable;

    // 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;

    // The received signal strength, in dBm. This field is avaliable and valid
    // only during discovery. Outside of discovery it's value is not specified.
    long? inquiryRssi;

    // The transmitted power level. This field is avaliable only for LE devices
    // that include this field in AD. It is avaliable and valid only during
    // discovery.
    long? inquiryTxPower;
  };

  dictionary BluetoothFilter {
    // Type of filter to apply to the device list. Default is all.
    FilterType? filterType;

    // Maximum number of bluetoth devices to return. Default is 0 (no limit)
    // if unspecified.
    long? limit;
  };

  // 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.
    // |filter|: Some criteria to filter the list of returned bluetooth devices.
    // If the filter is not set or set to <code>{}</code>, returned device list
    // will contain all bluetooth devices. Right now this is only supported in
    // ChromeOS, for other platforms, a full list is returned.
    // |callback| : Called when the search is completed.
    static void getDevices(optional BluetoothFilter filter,
                           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);
  };
};