chrome/common/extensions/api/bluetooth.idl - platform/external/chromium_org - Git at Google

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

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

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

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

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

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

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