chrome.bluetooth API improvements.

chrome/common/extensions/api/bluetooth.idl

Index: chrome/common/extensions/api/bluetooth.idl
diff --git a/chrome/common/extensions/api/bluetooth.idl b/chrome/common/extensions/api/bluetooth.idl
index 0e7c2c0fc5acf54df9b5e78040cc5959501b92d3..066bc88daeb49d174624ec85928fd71a0b68d4e1 100644
--- a/chrome/common/extensions/api/bluetooth.idl
+++ b/chrome/common/extensions/api/bluetooth.idl
@@ -5,6 +5,7 @@
 // Use the <code>chrome.bluetooth</code> API to connect to a Bluetooth
 // device. All functions report failures via chrome.runtime.lastError.
 namespace bluetooth {
+  // Information about the state of the bluetooth adapater.

[miket_OOO, 2014/03/28 20:48:43]

adapter

[rpaquay, 2014/03/31 15:39:19]

Done.

   dictionary AdapterState {
     // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
     DOMString address;
@@ -22,6 +23,7 @@ namespace bluetooth {
     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;
@@ -36,6 +38,7 @@ namespace bluetooth {
     boolean? connected;
   };
 
+  // Information about a bluetooth profile -- or service.

[keybuk, 2014/03/14 17:58:07]

Bluetooth profile/service terminology isn't quite like other systems, we should
avoid using "service" like this to avoid confusion for people who know Bluetooth
well and are intending to implement a Chrome client.

[rpaquay, 2014/03/14 18:27:50]

Ok, so stick with "profile" term only?

[keybuk, 2014/03/14 19:47:06]

Yeah, and hope to get rid of that term as well

[rpaquay, 2014/03/14 20:30:56]

OK, I'll change this comment and remove "service".

[rpaquay, 2014/03/20 00:48:18]

Done.

   dictionary Profile {
     // Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
     DOMString uuid;
@@ -48,7 +51,7 @@ namespace bluetooth {
     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
@@ -70,24 +73,49 @@ namespace bluetooth {
     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;
+
+    // An application-defined string associated with the socket.
+    DOMString? name;
 
-    // The UUID of the service.
-    DOMString? uuid;
+    // 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;
 
-    // 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 {
@@ -103,15 +131,11 @@ namespace bluetooth {
   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 {
@@ -119,13 +143,6 @@ namespace bluetooth {
     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|.
@@ -137,22 +154,16 @@ namespace bluetooth {
 
   // Options for the disconnect function.
   dictionary DisconnectOptions {
-    // The socket to disconnect.
-    Socket socket;
+    // The socket identifier.
+    long socketId;
   };
 
-  // Options for the read function.
-  dictionary ReadOptions {
-    // The socket to read from.
-    Socket socket;
-  };
+  // Options for the $ref:send function.
+  dictionary SendOptions {
+    // The socket identifier.
+    long socketId;
 
-  // Options for the write function.
-  dictionary WriteOptions {
-    // The socket to write to.
-    Socket socket;
-
-    // The data to write.
+    // The data to send.
     ArrayBuffer data;
   };
 
@@ -167,17 +178,45 @@ namespace bluetooth {
     OutOfBandPairingData? data;
   };
 
-  // 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);
+  // Callback from the <code>getSocket</code> method.
+  // |socket| : Object containing the socket information.
+  callback GetSocketCallback = void (Socket socket);
 
-    // 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);
+  // 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 {
     // Get information about the Bluetooth adapter.
     // |callback| : Called with an AdapterState object describing the adapter
     //              state.
@@ -188,40 +227,65 @@ namespace bluetooth {
     // |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);
 
-    // 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);
-
-    // Write data to a Bluetooth connection.
+    // Sends 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);
+    // |callback| : Called with the number of bytes sent.
+    static void send(SendOptions options,
+                     optional SizeCallback callback);

[keybuk, 2014/03/14 17:58:07]

The chrome.sockets.tcp.send() method takes the socketId and arrayBuffer as
separate arguments, not grouped into the options object -- this should match
that other API

[rpaquay, 2014/03/14 18:27:50]

I had a chat with Kalman@ about that. We are between a rock and a hard place:
the bluetooth api uses options everywhere, so we should be consistent with that,
but other api (tcp, etc.) don't, so we should be consistent with that. At the
time, we agreed that consistency within this idl file was (slightly) higher
order than consistency with other idl files.

That said, given the work has grown since then, maybe we should consider getting
rid of all "options" classes and use simple parameters everywhere? (I would do
that in a later CL, though).

[keybuk, 2014/03/14 19:47:06]

I would prefer the Bluetooth API moved towards getting rid of the options
classes, except where they co-incide with the others - since we're already
reworking this API anyway

No need to do that in this CL, we can do it in subsequent CLs

[rpaquay, 2014/03/14 20:30:56]

Agreed: crbug/352775

+
+    // 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.
@@ -272,5 +336,16 @@ namespace bluetooth {
     // 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);
   };
 };