chrome.bluetooth API improvements.

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 adapater.
   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;
@@ skipping 10 matching lines @@
     // 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;
   };
 
+  // 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
-    // deviecs.
+    // 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;
   };
 
-  dictionary ServiceRecord {
-    // The name of the service.
-    DOMString name;
+  // 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 if 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 "false." When the application is
+    // loaded, any sockets previously opened with persistent=true can be fetched
+    // with $ref:getSockets.
+    boolean? persistent;
 
-    // The UUID of the service.
-    DOMString? uuid;
+    // 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 profile associated with this socket.
-    Profile profile;
+    // The remote Bluetooth uuid associated with this socket.
+    DOMString uuid;
 
-    // An identifier for this socket that should be used with the
-    // read/write/disconnect methods.
-    long id;
+    // 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 value 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 DevicesCallback = void (Device[] result);
-  callback NameCallback = void (DOMString result);
   callback OutOfBandPairingDataCallback = void (OutOfBandPairingData data);
   callback ProfilesCallback = void(Profile[] result);
   callback ResultCallback = void ();
-  callback ServicesCallback = void(ServiceRecord[] result);
   callback SizeCallback = void (long result);
-  callback SocketCallback = void (Socket result);
 
   // Options for the getProfiles function.
   dictionary GetProfilesOptions {
     // The remote Bluetooth device to retrieve the exported profiles list from.
     Device device;
   };
 
-  // Options for the getServices function.
-  dictionary GetServicesOptions {
-    // The address of the device to inquire about. |deviceAddress| should be
-    // in the format 'XX:XX:XX:XX:XX:XX'.
-    DOMString deviceAddress;
-  };
-
   // 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 to disconnect.
-    Socket socket;
-  };
-
-  // Options for the read function.
-  dictionary ReadOptions {
-    // The socket to read from.
-    Socket socket;
-  };
-
-  // Options for the write function.
-  dictionary WriteOptions {
-    // The socket to write to.
-    Socket socket;
-
-    // The data to write.
-    ArrayBuffer data;
+    // 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 maxium 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 {
-    // 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);
-
     // 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);
 
+    // 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);
+
     // Returns the set of exported profiles for the device specified in options.
     // This function will not initiate a connection to the remote device.
     static void getProfiles(GetProfilesOptions options,
                             ProfilesCallback callback);
 
-    // Get a list of services provided by a device.
-    static void getServices(GetServicesOptions options,
-                            ServicesCallback callback);
-
-    // Connect to a service on a device.
+    // Connects to a profile on a device.
     // |options|  : The options for the connection.
     // |callback| : Called to indicate success or failure.
     static void connect(ConnectOptions options,
                         ResultCallback callback);
 
-    // Close a Bluetooth connection.
+    // 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);

[keybuk, 2014/03/27 20:20:07]

TODO or Bug for changing disconnect to: 

chrome.bluetooth.disconnect(integer socketId, function callback)

To match sockets -- since this CL has been in progress for long enough, I won't
make you do that here ;-)

[rpaquay, 2014/03/27 22:00:01]

Done: crbug/357328

 
-    // Read data from a Bluetooth connection. The |callback| will be called
-    // with the current data in the buffer even if it is empty. This function
-    // should be polled to read incoming data.
-    // |options|  : The options for this function.
-    // |callback| : Called with the data read from the socket buffer.
-    static void read(ReadOptions options,
-                     DataCallback 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);
 
-    // Write data to a Bluetooth connection.
-    // |options|  : The options for this function.
-    // |callback| : Called with the number of bytes written.
-    static void write(WriteOptions options,
-                      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 "false". 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.
@@ skipping 30 matching lines @@
     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);
   };
 };