extensions/common/api/bluetooth_socket.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.bluetoothSocket</code> API to send and receive data
   6 // to Bluetooth devices using RFCOMM and L2CAP connections.
   7 namespace bluetoothSocket {
   8   // The socket properties specified in the $ref:create or $ref:update
   9   // function. Each property is optional. If a property value is not specified,
  10   // a default value is used when calling $ref:create, or the existing value is
  11   // preserved when calling $ref:update.
  12   dictionary SocketProperties {
  13     // Flag indicating whether the socket is left open when the event page of
  14     // the application is unloaded (see <a
  15     // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
  16     // Lifecycle</a>). The default value is <code>false.</code> When the
  17     // application is loaded, any sockets previously opened with persistent=true
  18     // can be fetched with $ref:getSockets.
  19     boolean? persistent;
  20
  21     // An application-defined string associated with the socket.
  22     DOMString? name;
  23
  24     // The size of the buffer used to receive data. The default value is 4096.
  25     long? bufferSize;
  26   };
  27
  28   // Result of <code>create</code> call.
  29   dictionary CreateInfo {
  30     // The ID of the newly created socket. Note that socket IDs created
  31     // from this API are not compatible with socket IDs created from other APIs,
  32     // such as the <code>$(ref:sockets.tcp)</code> API.
  33     long socketId;
  34   };
  35
  36   // Callback from the <code>create</code> method.
  37   // |createInfo| : The result of the socket creation.
  38   callback CreateCallback = void (CreateInfo createInfo);
  39
  40   // Callback from the <code>update</code> method.
  41   callback UpdateCallback = void ();
  42
  43   // Callback from the <code>setPaused</code> method.
  44   callback SetPausedCallback = void ();
  45
  46   // Options that may be passed to the <code>listenUsingRfcomm</code> and
  47   // <code>listenUsingL2cap</code> methods. Each property is optional with a
  48   // default being used if not specified.
  49   dictionary ListenOptions {
  50     // The RFCOMM Channel used by <code>listenUsingRfcomm</code>. If specified,
  51     // this channel must not be previously in use or the method call will fail.
  52     // When not specified, an unused channel will be automatically allocated.
  53     long? channel;
  54
  55     // The L2CAP PSM used by <code>listenUsingL2cap</code>. If specified, this
  56     // PSM must not be previously in use or the method call with fail. When
  57     // not specified, an unused PSM will be automatically allocated.
  58     long? psm;
  59
  60     // Length of the socket's listen queue. The default value depends on the
  61     // operating system's host subsystem.
  62     long? backlog;
  63   };
  64
  65   // Callback from the <code>listenUsingRfcomm</code> and
  66   // <code>listenUsingL2cap</code> methods.
  67   callback ListenCallback = void ();
  68
  69   // Callback from the <code>connect</code> method.
  70   callback ConnectCallback = void ();
  71
  72   // Callback from the <code>disconnect</code> method.
  73   callback DisconnectCallback = void ();
  74
  75   // Callback from the <code>close</code> method.
  76   callback CloseCallback = void ();
  77
  78   // Callback from the <code>send</code> method.
  79   // |bytesSent| : The number of bytes sent.
  80   callback SendCallback = void (long bytesSent);
  81
  82   // Result of the <code>getInfo</code> method.
  83   dictionary SocketInfo {
  84     // The socket identifier.
  85     long socketId;
  86
  87     // Flag indicating if the socket remains open when the event page of the
  88     // application is unloaded (see <code>SocketProperties.persistent</code>).
  89     // The default value is "false".
  90     boolean persistent;
  91
  92     // Application-defined string associated with the socket.
  93     DOMString? name;
  94
  95     // The size of the buffer used to receive data. If no buffer size has been
  96     // specified explictly, the value is not provided.
  97     long? bufferSize;
  98
  99     // Flag indicating whether a connected socket blocks its peer from sending
 100     // more data, or whether connection requests on a listening socket are
 101     // dispatched through the <code>onAccept</code> event or queued up in the
 102     // listen queue backlog.
 103     // See <code>setPaused</code>. The default value is "false".
 104     boolean paused;
 105
 106     // Flag indicating whether the socket is connected to a remote peer.
 107     boolean connected;
 108
 109     // If the underlying socket is connected, contains the Bluetooth address of
 110     // the device it is connected to.
 111     DOMString? address;
 112
 113     // If the underlying socket is connected, contains information about the
 114     // service UUID it is connected to, otherwise if the underlying socket is
 115     // listening, contains information about the service UUID it is listening
 116     // on.
 117     DOMString? uuid;
 118   };
 119
 120   // Callback from the <code>getInfo</code> method.
 121   // |socketInfo| : Object containing the socket information.
 122   callback GetInfoCallback = void (SocketInfo socketInfo);
 123
 124   // Callback from the <code>getSockets</code> method.
 125   // |socketInfos| : Array of object containing socket information.
 126   callback GetSocketsCallback = void (SocketInfo[] sockets);
 127
 128   // Data from an <code>onAccept</code> event.
 129   dictionary AcceptInfo {
 130     // The server socket identifier.
 131     long socketId;
 132
 133     // The client socket identifier, i.e. the socket identifier of the newly
 134     // established connection. This socket identifier should be used only with
 135     // functions from the <code>chrome.bluetoothSocket</code> namespace. Note
 136     // the client socket is initially paused and must be explictly un-paused by
 137     // the application to start receiving data.
 138     long clientSocketId;
 139   };
 140
 141   enum AcceptError {
 142     // A system error occurred and the connection may be unrecoverable.
 143     system_error,
 144
 145     // The socket is not listening.
 146     not_listening
 147   };
 148
 149   // Data from an <code>onAcceptError</code> event.
 150   dictionary AcceptErrorInfo {
 151     // The server socket identifier.
 152     long socketId;
 153
 154     // The error message.
 155     DOMString errorMessage;
 156
 157     // An error code indicating what went wrong.
 158     AcceptError error;
 159   };
 160
 161   // Data from an <code>onReceive</code> event.
 162   dictionary ReceiveInfo {
 163     // The socket identifier.
 164     long socketId;
 165
 166     // The data received, with a maxium size of <code>bufferSize</code>.
 167     ArrayBuffer data;
 168   };
 169
 170   enum ReceiveError {
 171     // The connection was disconnected.
 172     disconnected,
 173
 174     // A system error occurred and the connection may be unrecoverable.
 175     system_error,
 176
 177     // The socket has not been connected.
 178     not_connected
 179   };
 180
 181   // Data from an <code>onReceiveError</code> event.
 182   dictionary ReceiveErrorInfo {
 183     // The socket identifier.
 184     long socketId;
 185
 186     // The error message.
 187     DOMString errorMessage;
 188
 189     // An error code indicating what went wrong.
 190     ReceiveError error;
 191   };
 192
 193   // These functions all report failures via chrome.runtime.lastError.
 194   interface Functions {
 195     // Creates a Bluetooth socket.
 196     // |properties| : The socket properties (optional).
 197     // |callback| : Called when the socket has been created.
 198     static void create(optional SocketProperties properties,
 199                        CreateCallback callback);
 200
 201     // Updates the socket properties.
 202     // |socketId| : The socket identifier.
 203     // |properties| : The properties to update.
 204     // |callback| : Called when the properties are updated.
 205     static void update(long socketId,
 206                        SocketProperties properties,
 207                        optional UpdateCallback callback);
 208
 209     // Enables or disables a connected socket from receiving messages from its
 210     // peer, or a listening socket from accepting new connections. The default
 211     // value is "false". Pausing a connected socket is typically used by an
 212     // application to throttle data sent by its peer. When a connected socket
 213     // is paused, no <code>onReceive</code>event is raised. When a socket is
 214     // connected and un-paused, <code>onReceive</code> events are raised again
 215     // when messages are received. When a listening socket is paused, new
 216     // connections are accepted until its backlog is full then additional
 217     // connection requests are refused. <code>onAccept</code> events are raised
 218     // only when the socket is un-paused.
 219     static void setPaused(long socketId,
 220                           boolean paused,
 221                           optional SetPausedCallback callback);
 222
 223     // Listen for connections using the RFCOMM protocol.
 224     // |socketId| : The socket identifier.
 225     // |uuid| : Service UUID to listen on.
 226     // |options| : Optional additional options for the service.
 227     // |callback| : Called when listen operation completes.
 228     static void listenUsingRfcomm(long socketId,
 229                                   DOMString uuid,
 230                                   optional ListenOptions options,
 231                                   ListenCallback callback);
 232
 233     // Listen for connections using the L2CAP protocol.
 234     // |socketId| : The socket identifier.
 235     // |uuid| : Service UUID to listen on.
 236     // |options| : Optional additional options for the service.
 237     // |callback| : Called when listen operation completes.
 238     static void listenUsingL2cap(long socketId,
 239                                  DOMString uuid,
 240                                  optional ListenOptions options,
 241                                  ListenCallback callback);
 242
 243     // Connects the socket to a remote Bluetooth device. When the
 244     // <code>connect</code> operation completes successfully,
 245     // <code>onReceive</code> events are raised when data is received from the
 246     // peer. If a network error occur while the runtime is receiving packets,
 247     // a <code>onReceiveError</code> event is raised, at which point no more
 248     // <code>onReceive</code> event will be raised for this socket until the
 249     // <code>setPaused(false)</code> method is called.
 250     // |socketId| : The socket identifier.
 251     // |address| : The address of the Bluetooth device.
 252     // |uuid| : The UUID of the service to connect to.
 253     // |callback| : Called when the connect attempt is complete.
 254     static void connect(long socketId,
 255                         DOMString address,
 256                         DOMString uuid,
 257                         ConnectCallback callback);
 258
 259     // Disconnects the socket. The socket identifier remains valid.
 260     // |socketId| : The socket identifier.
 261     // |callback| : Called when the disconnect attempt is complete.
 262     static void disconnect(long socketId,
 263                            optional DisconnectCallback callback);
 264
 265     // Disconnects and destroys the socket. Each socket created should be
 266     // closed after use. The socket id is no longer valid as soon at the
 267     // function is called. However, the socket is guaranteed to be closed only
 268     // when the callback is invoked.
 269     // |socketId| : The socket identifier.
 270     // |callback| : Called when the <code>close</code> operation completes.
 271     static void close(long socketId,
 272                       optional CloseCallback callback);
 273
 274     // Sends data on the given Bluetooth socket.
 275     // |socketId| : The socket identifier.
 276     // |data| : The data to send.
 277     // |callback| : Called with the number of bytes sent.
 278     static void send(long socketId,
 279                      ArrayBuffer data,
 280                      optional SendCallback callback);
 281
 282     // Retrieves the state of the given socket.
 283     // |socketId| : The socket identifier.
 284     // |callback| : Called when the socket state is available.
 285     static void getInfo(long socketId,
 286                         GetInfoCallback callback);
 287
 288     // Retrieves the list of currently opened sockets owned by the application.
 289     // |callback| : Called when the list of sockets is available.
 290     static void getSockets(GetSocketsCallback callback);
 291   };
 292
 293   interface Events {
 294     // Event raised when a connection has been established for a given socket.
 295     // |info| : The event data.
 296     static void onAccept(AcceptInfo info);
 297
 298     // Event raised when a network error occurred while the runtime was waiting
 299     // for new connections on the given socket. Once this event is raised, the
 300     // socket is set to <code>paused</code> and no more <code>onAccept</code>
 301     // events are raised for this socket.
 302     // |info| : The event data.
 303     static void onAcceptError(AcceptErrorInfo info);
 304
 305     // Event raised when data has been received for a given socket.
 306     // |info| : The event data.
 307     static void onReceive(ReceiveInfo info);
 308
 309     // Event raised when a network error occured while the runtime was waiting
 310     // for data on the socket. Once this event is raised, the socket is set to
 311     // <code>paused</code> and no more <code>onReceive</code> events are raised
 312     // for this socket.
 313     // |info| : The event data.
 314     static void onReceiveError(ReceiveErrorInfo info);
 315   };
 316 };