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..b42fce4a6ee865e24072fc621fd1bb87555995e6 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 adapter.
   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 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 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
+    // 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 {
@@ -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 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.
@@ -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 <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.
@@ -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);
   };
 };