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 e66cda103b89c8c0baeba404138458dc5df7b89b..8a1be515794ce279de92c7a72ce0f760bfb7182d 100644
--- a/chrome/common/extensions/api/bluetooth.idl
+++ b/chrome/common/extensions/api/bluetooth.idl
@@ -13,6 +13,7 @@ namespace bluetooth {
                    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;
@@ -30,6 +31,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;
@@ -67,6 +69,7 @@ namespace bluetooth {
     DOMString[]? uuids;
   };
 
+  // Information about a Bluetooth profile.
   dictionary Profile {
     // Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
     DOMString uuid;
@@ -79,7 +82,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
@@ -101,24 +104,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

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

Meggin will change "if" to whether, so might as well do it now.

Distinction: it's not that the flag does its indicating job only in the case
that the socket is persistent. It's that the flag reflects the persistent-or-not
state. A more acute example:

Let's decide if she goes to the park.
Let's decide whether she goes to the park.

In case one, we might or might not go through the process of deciding.
In case two, the outcome depends on our decision.

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

Done.

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

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

good!

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

Done.

+    // 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.

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

Nit: I wonder whether "field" is more accurate than "value." In a dictionary, a
value is half of a key-value pair.

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

Done.

+    long? bufferSize;
+
+    // Flag indicating whether a connected socket blocks its peer from sending
+    // more data (see <code>setPaused</code>).
+    boolean paused;
   };
 
   dictionary OutOfBandPairingData {
@@ -154,23 +182,8 @@ namespace bluetooth {
 
   // 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.
@@ -184,17 +197,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>.

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

maximum (spelling)

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

Done.

+    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.
@@ -210,31 +251,62 @@ namespace bluetooth {
     // |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);
 
-    // 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.
-    // |options|  : The options for this function.
-    // |callback| : Called with the number of bytes written.
-    static void write(WriteOptions options,
-                      optional SizeCallback 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 "false". Pausing a socket is typically used by

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

Convention seems to be to wrap in <code>

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

Done.

+    // 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.
@@ -285,5 +357,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);
   };
 };