Cast: Stop logging kVideoFrameSentToEncoder and rename a couple events.

[chromium-blink-merge.git] / 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;
  };

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

  // Information about a Bluetooth profile.
  dictionary Profile {
    // Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
    DOMString uuid;

    // Human-readable name of the Profile, e.g. "Health Device"
    DOMString? name;

    // The RFCOMM channel id, used when the profile is to be exported to remote
    // devices.
    long? channel;

    // The LS2CAP PSM number, used when the profile is to be exported to remote
    // devices.
    long? psm;

    // Specifies whether pairing (and encryption) is required to be able to
    // connect.
    boolean? requireAuthentication;

    // Specifies whether user authorization is required to be able to connect.
    boolean? requireAuthorization;

    // Specifies whether this profile will be automatically connected if any
    // other profile of device also exporting this profile connects to the host.
    boolean? autoConnect;

    // Specifies the implemented version of the profile.
    long? version;

    // Specifies the profile-specific bit field of features the implementation
    // supports.
    long? features;
  };

  // The socket properties specified in the $ref:update function. Each property
  // is optional. If a property value is not specified, the existing value if
  // preserved when calling $ref:update.
  dictionary SocketProperties {
    // Flag indicating whether the socket is left open when the event page of
    // the application is unloaded (see <a
    // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
    // Lifecycle</a>). The default value is <code>false.</code> When the
    // application is loaded, any sockets previously opened with persistent=true
    // can be fetched with $ref:getSockets.
    boolean? persistent;

    // An application-defined string associated with the socket.
    DOMString? name;

    // The size of the buffer used to receive data. The default value is 4096.
    long? bufferSize;
  };

  dictionary Socket {
    // The socket identifier.
    long id;

    // The remote Bluetooth device associated with this socket.
    Device device;

    // The remote Bluetooth uuid associated with this socket.
    DOMString uuid;

    // Flag indicating whether the socket is left open when the application is
    // suspended (see <code>SocketProperties.persistent</code>).
    boolean persistent;

    // Application-defined string associated with the socket.
    DOMString? name;

    // The size of the buffer used to receive data. If no buffer size has been
    // specified explictly, the field is not provided.
    long? bufferSize;

    // Flag indicating whether a connected socket blocks its peer from sending
    // more data (see <code>setPaused</code>).
    boolean paused;
  };

  dictionary OutOfBandPairingData {
    // Simple Pairing Hash C.
    // Always 16 octets long.
    ArrayBuffer hash;

    // Simple Pairing Randomizer R.
    // Always 16 octets long.
    ArrayBuffer randomizer;
  };

  callback AdapterStateCallback = void(AdapterState result);
  callback AddressCallback = void(DOMString result);
  callback BooleanCallback = void(boolean result);
  callback DataCallback = void(optional ArrayBuffer result);
  callback DeviceCallback = void(Device result);
  callback DevicesCallback = void(Device[] result);
  callback NameCallback = void(DOMString result);
  callback OutOfBandPairingDataCallback = void(OutOfBandPairingData data);
  callback ResultCallback = void();
  callback SizeCallback = void(long result);
  callback SocketCallback = void(Socket result);

  // Options for the connect function.
  dictionary ConnectOptions {
    // The connection is made to |device|.
    Device device;

    // The connection is made to |profile|.
    Profile profile;
  };

  // Options for the disconnect function.
  dictionary DisconnectOptions {
    // The socket identifier.
    long socketId;
  };

  // Options for the setOutOfBandPairingData function.
  dictionary SetOutOfBandPairingDataOptions {
    // The address of the remote device that the data should be associated
    // with. |deviceAddress| should be in the format 'XX:XX:XX:XX:XX:XX'.
    DOMString address;

    // The Out Of Band Pairing Data. If this is omitted, the data for the
    // device is cleared instead.
    OutOfBandPairingData? data;
  };

  // Callback from the <code>getSocket</code> method.
  // |socket| : Object containing the socket information.
  callback GetSocketCallback = void (Socket socket);

  // Callback from the <code>getSockets</code> method.
  // |sockets| : Array of object containing socket information.
  callback GetSocketsCallback = void (Socket[] sockets);

  // Data from an <code>onReceive</code> event.
  dictionary ReceiveInfo {
    // The socket identifier.
    long socketId;

    // The data received, with a maximum size of <code>bufferSize</code>.
    ArrayBuffer data;
  };

  enum ReceiveError {
    // The connection was disconnected.
    disconnected,

    // A system error occurred and the connection may be unrecoverable.
    system_error
  };

  // Data from an <code>onReceiveError</code> event.
  dictionary ReceiveErrorInfo {
    // The socket identifier.
    long socketId;

     // The error message.
    DOMString errorMessage;

    // An error code indicating what went wrong.
    ReceiveError error;
  };

  // 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 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(DevicesCallback 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, DeviceCallback callback);

    // Registers the JavaScript application as an implementation for the given
    // Profile; if a channel or PSM is specified, the profile will be exported
    // in the host's SDP and GATT tables and advertised to other devices.
    static void addProfile(Profile profile, ResultCallback callback);

    // Unregisters the JavaScript application as an implementation for the given
    // Profile; only the uuid field of the Profile object is used.
    static void removeProfile(Profile profile, ResultCallback callback);

    // Connect to a service on a device.
    // |options|  : The options for the connection.
    // |callback| : Called to indicate success or failure.
    static void connect(ConnectOptions options,
                        ResultCallback callback);

    // Closes a Bluetooth connection.
    // |options|  : The options for this function.
    // |callback| : Called to indicate success or failure.
    static void disconnect(DisconnectOptions options,
                           optional ResultCallback callback);

    // Sends data to a Bluetooth connection.
    // |socketId| : The socket identifier.
    // |data| : The data to send.
    // |callback| : Called with the number of bytes sent.
    static void send(long socketId,
                     ArrayBuffer data,
                     optional SizeCallback callback);

    // Updates the socket properties.
    // |socketId| : The socket identifier.
    // |properties| : The properties to update.
    // |callback| : Called when the properties are updated.
    static void updateSocket(long socketId,
                             SocketProperties properties,
                             optional ResultCallback callback);

    // Enables or disables the application from receiving messages from its
    // peer. The default value is <code>false</code>. Pausing a socket is
    // typically used by an application to throttle data sent by its peer. When
    // a socket is paused, no $ref:onReceive event is raised. When a socket is
    // connected and un-paused, $ref:onReceive events are raised again when
    // messages are received.
    static void setSocketPaused(long socketId,
                                boolean paused,
                                optional ResultCallback callback);

    // Retrieves the state of the given socket.
    // |socketId| : The socket identifier.
    // |callback| : Called when the socket state is available.
    static void getSocket(long socketId,
                          GetSocketCallback callback);

    // Retrieves the list of currently opened sockets owned by the application.
    // |callback| : Called when the list of sockets is available.
    static void getSockets(GetSocketsCallback callback);

    // Get the local Out of Band Pairing data.
    // |callback| : Called with the data.
    static void getLocalOutOfBandPairingData(
        OutOfBandPairingDataCallback callback);

    // Set the Out of Band Pairing data for a remote device.
    // Any previous Out Of Band Pairing Data for this device is overwritten.
    // |options|  : The options for this function.
    // |callback| : Called to indicate success or failure.
    static void setOutOfBandPairingData(SetOutOfBandPairingDataOptions options,
                                        optional ResultCallback 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 ResultCallback callback);

    // Stop discovery.
    // |callback| : Called to indicate success or failure.
    static void stopDiscovery(
        optional ResultCallback 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);

    // Fired when a connection has been made for a registered profile.
    // |socket| : The socket for the connection.
    static void onConnection(Socket socket);

    // Event raised when data has been received for a given socket.
    // |info| : The event data.
    static void onReceive(ReceiveInfo info);

    // Event raised when a network error occured while the runtime was waiting
    // for data on the socket. Once this event is raised, the socket is set to
    // <code>paused</code> and no more <code>onReceive</code> events are raised
    // for this socket.
    // |info| : The event data.
    static void onReceiveError(ReceiveErrorInfo info);
  };
};