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 17 matching lines @@
     boolean? connected;
 
     // UUIDs of protocols, profiles and services advertised by the device.
     // For classic Bluetooth devices, this list is obtained from EIR data and
     // SDP tables. For Low Energy devices, this list is obtained from AD and
     // GATT primary services. For dual mode devices this may be obtained from
     // both.
     DOMString[]? uuids;
   };
 
+  // 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

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

[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 {
     // Simple Pairing Hash C.
     // Always 16 octets long.
     ArrayBuffer hash;
 
     // Simple Pairing Randomizer R.
     // Always 16 octets long.
     ArrayBuffer randomizer;
@@ skipping 15 matching lines @@
   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>.

[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 {
-    // 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);
 
     // Get information about a Bluetooth device known to the system.
     // |deviceAddress| : Address of device to get.
     // |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);
+    // 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

[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.
     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);
   };
 };