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 25128564b1ebcd81962e5f9a1365e42365a3836a..0249623d9edca702e21cb87cad1e2219faab3454 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;
@@ -60,6 +62,7 @@ namespace bluetooth {
     boolean? connected;
   };
 
+  // Information about a Bluetooth profile.
   dictionary Profile {
     // Unique profile identifier, e.g. 00001401-0000-1000-8000-00805F9B23FB
     DOMString uuid;
@@ -72,7 +75,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
@@ -94,24 +97,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;
+    // 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 {
@@ -127,15 +155,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 {
@@ -143,13 +167,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|.
@@ -161,23 +178,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.
@@ -191,17 +193,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.
@@ -212,40 +242,67 @@ 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);

[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);
-
-    // 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
+    // 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.
@@ -296,5 +353,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);
   };
 };