Introduce chrome.bluetoothSocket API.

chrome/common/extensions/api/bluetooth_socket.idl

+// Copyright (c) 2014 The Chromium Authors. All rights reserved.

[rpaquay, 2014/04/22 15:47:55]

nit: Copyright 2014

[keybuk, 2014/04/24 11:46:45]

Done.

+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.bluetoothSocket</code> API to send and receive data
+// to Bluetooth devices using RFCOMM and L2CAP connections.
+namespace bluetoothSocket {

[not at google - send to devlin, 2014/04/22 17:27:05]

is there an API proposal that encompasses this API?

[keybuk, 2014/04/24 11:46:45]

I wrote this to outline the changes:
https://docs.google.com/a/google.com/document/d/1NkO5_s_loaAv4sExBtZ1XE3z54ek...

For the most part it's just moving things from chrome.bluetooth to
chrome.bluetoothSocket and making them even more consistent with
chrome.sockets.*

+  // The socket properties specified in the $ref:create or $ref:update
+  // function. Each property is optional. If a property value is not specified,
+  // a default value is used when calling $ref:create, or the existing value is
+  // 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 size of the buffer used to receive data. The default value is 4096.
+    long? bufferSize;
+  };
+
+  // Result of <code>create</code> call.
+  dictionary CreateInfo {
+    // The ID of the newly created socket. Note that socket IDs created
+    // from this API are not compatible with socket IDs created from other APIs,
+    // such as the <code>$(ref:sockets.tcp)</code> API.
+    long socketId;
+  };
+
+  // Callback from the <code>create</code> method.
+  // |createInfo| : The result of the socket creation.
+  callback CreateCallback = void (CreateInfo createInfo);
+
+  // Callback from the <code>update</code> method.
+  callback UpdateCallback = void ();
+
+  // Callback from the <code>setPaused</code> method.
+  callback SetPausedCallback = void ();
+
+  // Callback from the <code>listenUsingRfcomm</code>,
+  // <code>listenUsingInsecureRfcomm</code> and
+  // <code>listenUsingL2cap</code> methods.
+  // |result| : The result code returned from the underlying network call.
+  // A negative value indicates an error.
+  callback ListenCallback = void (long result);
+
+  // Callback from the <code>connect</code> method.
+  // |result| : The result code returned from the underlying network call.
+  // A negative value indicates an error.
+  callback ConnectCallback = void (long result);
+
+  // Callback from the <code>disconnect</code> method.
+  callback DisconnectCallback = void ();
+
+  // Callback from the <code>close</code> method.
+  callback CloseCallback = void ();
+
+  // Result of the <code>send</code> method.
+  dictionary SendInfo {
+    // The result code returned from the underlying network call.
+    // A negative value indicates an error.
+    long resultCode;

[rpaquay, 2014/04/22 15:47:55]

Maybe we should use a custom enum for the bluetooth API, with a few entries only
(Ok, Disconnected, SystemError) as we did with chrome.serial.

We decided to use return code for TCP sockets, because they come from the net::
namespace, which normalizes them across platforms (all of them use some form of
posix-like "socket" api under the hood).

For Bluetooth, the OSX implementation is very different (it uses IOBluetoothXxx
functions) than Windows/ChromeOS, so I think it will be a challenge to normalize
error codes.

[keybuk, 2014/04/24 11:46:45]

Oops, yes!

I was copying from both the existing idl and the sockets ones to make sure I got
consistency - looks like I copied the wrong thing here - I hadn't intended to
change that!

+
+    // The number of bytes sent (if result == 0)
+    long? bytesSent;
+  };
+
+  // Callback from the <code>send</code> method.
+  // |sendInfo| : Result of the <code>send</code> method.
+  callback SendCallback = void (SendInfo sendInfo);
+
+  // Result of the <code>getInfo</code> method.
+  dictionary SocketInfo {
+    // The socket identifier.
+    long socketId;
+
+    // Flag indicating if the socket remains open when the event page of the
+    // application is unloaded (see <code>SocketProperties.persistent</code>).
+    // The default value is "false".
+    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
+    // mode data, or whether connection requests on a listening socket are

[armansito, 2014/04/22 20:13:04]

nit: s/mode/more ?

[keybuk, 2014/04/24 11:46:45]

Done.

+    // dispatched through the <code>onAccept</code> event or queued up in the
+    // listen queue backlog.
+    // See <code>setPaused</code>. The default value is "false".
+    boolean paused;
+
+    // Flag indicating whether the socket is connected to a remote peer.
+    boolean connected;
+
+    // If the underlying socket is connected, contains information about the
+    // device it is connected to.
+    bluetooth.Device? device;
+
+    // If the underlying socket is connected, contains information about the
+    // service UUID it is connected to, otherwise if the underlying socket is
+    // listening, contains information about the service UUID it is listening
+    // on.
+    DOMString? uuid;
+  };
+
+  // Callback from the <code>getInfo</code> method.
+  // |socketInfo| : Object containing the socket information.
+  callback GetInfoCallback = void (SocketInfo socketInfo);
+
+  // Callback from the <code>getSockets</code> method.
+  // |socketInfos| : Array of object containing socket information.
+  callback GetSocketsCallback = void (SocketInfo[] sockets);
+
+  // Data from an <code>onAccept</code> event.
+  dictionary AcceptInfo {
+    // The server socket identifier.
+    long socketId;
+
+    // The client socket identifier, i.e. the socket identifier of the newly
+    // established connection. This socket identifier should be used only with
+    // functions from the <code>chrome.sockets.tcp</code> namespace. Note the

[rpaquay, 2014/04/22 15:47:55]

chrome.bluetoothSocket

[keybuk, 2014/04/24 11:46:45]

Done.

+    // client socket is initially paused and must be explictly un-paused by the
+    // application to start receiving data.
+    long clientSocketId;
+  };
+
+  // Data from an <code>onAcceptError</code> event.
+  dictionary AcceptErrorInfo {
+    // The server socket identifier.
+    long socketId;
+
+    // The result code returned from the underlying network call.
+    long resultCode;
+  };
+
+  // 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;
+  };
+
+  // Data from an <code>onReceiveError</code> event.
+  dictionary ReceiveErrorInfo {
+    // The socket identifier.
+    long socketId;
+
+     // The result code returned from the underlying network call.
+    long resultCode;
+  };
+
+  // These functions all report failures via chrome.runtime.lastError.
+  interface Functions {
+    // Creates a Bluetooth socket.
+    // |properties| : The socket properties (optional).
+    // |callback| : Called when the socket has been created.
+    static void create(optional SocketProperties properties,
+                       CreateCallback callback);
+
+    // Updates the socket properties.
+    // |socketId| : The socket identifier.
+    // |properties| : The properties to update.
+    // |callback| : Called when the properties are updated.
+    static void update(long socketId,
+                       SocketProperties properties,
+                       optional UpdateCallback callback);
+
+    // Enables or disables a connected socket from receiving messages from its
+    // peer, or a listening socket from accepting new connections. The default
+    // value is "false". Pausing a connected socket is typically used by an
+    // application to throttle data sent by its peer. When a connected socket
+    // is paused, no <code>onReceive</code>event is raised. When a socket is
+    // connected and un-paused, <code>onReceive</code> events are raised again
+    // when messages are received. When a listening socket is paused, new
+    // connections are accepted until its backlog is full then additional
+    // connection requests are refused. <code>onAccept</code> events are raised
+    // only when the socket is un-paused.
+    static void setPaused(long socketId,
+                          boolean paused,
+                          optional SetPausedCallback callback);
+
+    // Listen for connections using the RFCOMM protocol.
+    // |socketId| : The socket identifier.
+    // |uuid| : Service UUID to listen on.
+    // |channel| : RFCOMM channel id to listen on. Zero may be specified to
+    // allocate an unused channel.
+    // |backlog| : Length of the socket's listen queue. The default value
+    // depends on the Operating System Host Subsystem.
+    // |callback| : Called when listen operation completes.
+    static void listenUsingRfcomm(long socketId,
+                                  DOMString uuid,
+                                  long channel,
+                                  optional long backlog,
+                                  ListenCallback callback);
+
+    // Listens for connections from Bluetooth 1.0 and 2.0 devices using the
+    // RFCOMM protocol without requiring encryption or authentication on the
+    // socket.
+    // |socketId| : The socket identifier.
+    // |uuid| : Service UUID to listen on.
+    // |channel| : RFCOMM channel id to listen on. Zero may be specified to
+    // allocate an unused channel.
+    // |backlog| : Length of the socket's listen queue. The default value
+    // depends on the Operating System Host Subsystem.
+    // |callback| : Called when listen operation completes.
+    static void listenUsingInsecureRfcomm(long socketId,
+                                          DOMString uuid,
+                                          long channel,
+                                          optional long backlog,
+                                          ListenCallback callback);
+
+    // Listen for connections using the L2CAP protocol.
+    // |socketId| : The socket identifier.
+    // |uuid| : Service UUID to listen on.
+    // |psm| : L2CAP PSM to listen on. Zero may be specified to allocate an
+    // unused PSM.
+    // |backlog| : Length of the socket's listen queue. The default value
+    // depends on the Operating System Host Subsystem.

[miket_OOO, 2014/04/22 20:18:17]

Unless "Operating System Host Subsystem" is a term of art, it shouldn't be
capitalized. Otherwise it's confusing because people will look for a definition,
and won't find it. (this one and other occurrences in this file).

[keybuk, 2014/04/24 11:46:45]

Done.

+    // |callback| : Called when listen operation completes.
+    static void listenUsingL2cap(long socketId,
+                                 DOMString uuid,
+                                 long psm,
+                                 optional long backlog,
+                                 ListenCallback callback);
+
+    // Connects the socket to a remote Bluetooth device. When the
+    // <code>connect</code> operation completes successfully,
+    // <code>onReceive</code> events are raised when data is received from the
+    // peer. If a network error occur while the runtime is receiving packets,
+    // a <code>onReceiveError</code> event is raised, at which point no more
+    // <code>onReceive</code> event will be raised for this socket until the
+    // <code>resume</code> method is called.

[rpaquay, 2014/04/22 15:47:55]

<code>setPaused(false)</code>

[keybuk, 2014/04/24 11:46:45]

Done.

+    // |socketId| : The socket identifier.
+    // |address| : The address of the Bluetooth device.
+    // |uuid| : The UUID of the service to connect to.
+    // |callback| : Called when the connect attempt is complete.
+    static void connect(long socketId,
+                        DOMString address,
+                        DOMString uuid,
+                        ConnectCallback callback);
+
+    // Disconnects the socket. The socket identifier remains valid.
+    // |socketId| : The socket identifier.
+    // |callback| : Called when the disconnect attempt is complete.
+    static void disconnect(long socketId,
+                           optional DisconnectCallback callback);
+
+    // Disconnects and destroys the socket. Each socket created should be
+    // closed after use. The socket id is no longer valid as soon at the
+    // function is called. However, the socket is guaranteed to be closed only
+    // when the callback is invoked.
+    // |socketId| : The socket identifier.
+    // |callback| : Called when the <code>close</code> operation completes.
+    static void close(long socketId,
+                      optional CloseCallback callback);
+
+    // Sends data on the given Bluetooth socket.
+    // |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 SendCallback callback);
+
+    // Retrieves the state of the given socket.
+    // |socketId| : The socket identifier.
+    // |callback| : Called when the socket state is available.
+    static void getInfo(long socketId,
+                        GetInfoCallback 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);
+  };
+
+  interface Events {
+    // Event raised when a connection has been established for a given socket.
+    // |info| : The event data.
+    static void onAccept(AcceptInfo info);
+
+    // Event raised when a network error occurred while the runtime was waiting
+    // for new connections on the given socket. Once this event is raised, the
+    // socket is set to <code>paused</code> and no more <code>onAccept</code>
+    // events are raised for this socket.
+    // |info| : The event data.
+    static void onAcceptError(AcceptErrorInfo info);
+
+    // 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);
+  };
+};