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 {
+  // 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;
 
     // 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;
 
     // Indicates whether or not the device is paired with the system.
     boolean? paired;
 
     // Indicates whether the device is currently connected to the system.
     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;
 
     // 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
+    // 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;
 
-    // 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 {
     // Simple Pairing Hash C.
     // Always 16 octets long.
     ArrayBuffer hash;
 
     // Simple Pairing Randomizer R.
     // Always 16 octets long.
     ArrayBuffer randomizer;
   };
 
   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 {
     // The remote Bluetooth device to retrieve the exported profiles list from.
     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|.
     Device device;
 
     // The connection is made to |profile|.
     Profile profile;
   };
 
   // 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;
   };
 
   // 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>.
+    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);
 
+    // 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.
+    // Sends data to a Bluetooth connection.
     // |options|  : The options for this function.
-    // |callback| : Called with the data read from the socket buffer.
-    static void read(ReadOptions options,
-                     DataCallback 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

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