extensions/common/api/sockets_tcp.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.sockets.tcp</code> API to send and receive data over the
   6 // network using TCP connections. This API supersedes the TCP functionality
   7 // previously found in the <code>chrome.socket</code> API.
   8 namespace sockets.tcp {
   9   // The socket properties specified in the <code>create</code> or
  10   // <code>update</code> function. Each property is optional. If a property
  11   // value is not specified, a default value is used when calling
  12   // <code>create</code>, or the existing value if preserved when calling
  13   // <code>update</code>.
  14   dictionary SocketProperties {
  15     // Flag indicating if the socket is left open when the event page of
  16     // the application is unloaded (see
  17     // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
  18     // Lifecycle</a>). The default value is "false." When the application is
  19     // loaded, any sockets previously opened with persistent=true can be fetched
  20     // with <code>getSockets</code>.
  21     boolean? persistent;
  22
  23     // An application-defined string associated with the socket.
  24     DOMString? name;
  25
  26     // The size of the buffer used to receive data. The default value is 4096.
  27     long? bufferSize;
  28   };
  29
  30   // Result of <code>create</code> call.
  31   dictionary CreateInfo {
  32     // The ID of the newly created socket. Note that socket IDs created from
  33     // this API are not compatible with socket IDs created from other APIs, such
  34     // as the deprecated <code>$(ref:socket)</code> API.
  35     long socketId;
  36   };
  37
  38   // Callback from the <code>create</code> method.
  39   // |createInfo| : The result of the socket creation.
  40   callback CreateCallback = void (CreateInfo createInfo);
  41
  42   // Callback from the <code>connect</code> method.
  43   // |result| : The result code returned from the underlying network call.
  44   // A negative value indicates an error.
  45   callback ConnectCallback = void (long result);
  46
  47   // Callback from the <code>disconnect</code> method.
  48   callback DisconnectCallback = void ();
  49
  50   // Result of the <code>send</code> method.
  51   dictionary SendInfo {
  52     // The result code returned from the underlying network call.
  53     // A negative value indicates an error.
  54     long resultCode;
  55
  56     // The number of bytes sent (if result == 0)
  57     long? bytesSent;
  58   };
  59
  60   // Callback from the <code>send</code> method.
  61   // |sendInfo| : Result of the <code>send</code> method.
  62   callback SendCallback = void (SendInfo sendInfo);
  63
  64   // Callback from the <code>close</code> method.
  65   callback CloseCallback = void ();
  66
  67   // Callback from the <code>update</code> method.
  68   callback UpdateCallback = void ();
  69
  70   // Callback from the <code>setPaused</code> method.
  71   callback SetPausedCallback = void ();
  72
  73   // Callback from the <code>setKeepAliveCallback</code> method.
  74   // |result| : The result code returned from the underlying network call.
  75   // A negative value indicates an error.
  76   callback SetKeepAliveCallback = void (long result);
  77
  78   // Callback from the <code>setNodeDelay</code> method.
  79   // |result| : The result code returned from the underlying network call.
  80   // A negative value indicates an error.
  81   callback SetNoDelayCallback = void (long result);
  82
  83   dictionary TLSVersionConstraints {
  84     // The minimum and maximum acceptable versions of TLS. These will
  85     // be <code>ssl3</code>, <code>tls1</code>, <code>tls1.1</code>,
  86     // or <code>tls1.2</code>.
  87     DOMString? min;
  88     DOMString? max;
  89   };
  90
  91   dictionary SecureOptions {
  92     TLSVersionConstraints? tlsVersion;
  93   };
  94
  95   callback SecureCallback = void (long result);
  96
  97   // Result of the <code>getInfo</code> method.
  98   dictionary SocketInfo {
  99     // The socket identifier.
 100     long socketId;
 101
 102     // Flag indicating whether the socket is left open when the application is
 103     // suspended (see <code>SocketProperties.persistent</code>).
 104     boolean persistent;
 105
 106     // Application-defined string associated with the socket.
 107     DOMString? name;
 108
 109     // The size of the buffer used to receive data. If no buffer size has been
 110     // specified explictly, the value is not provided.
 111     long? bufferSize;
 112
 113     // Flag indicating whether a connected socket blocks its peer from sending
 114     // more data (see <code>setPaused</code>).
 115     boolean paused;
 116
 117     // Flag indicating whether the socket is connected to a remote peer.
 118     boolean connected;
 119
 120     // If the underlying socket is connected, contains its local IPv4/6 address.
 121     DOMString? localAddress;
 122
 123     // If the underlying socket is connected, contains its local port.
 124     long? localPort;
 125
 126     // If the underlying socket is connected, contains the peer/ IPv4/6 address.
 127     DOMString? peerAddress;
 128
 129     // If the underlying socket is connected, contains the peer port.
 130     long? peerPort;
 131   };
 132
 133   // Callback from the <code>getInfo</code> method.
 134   // |socketInfo| : Object containing the socket information.
 135   callback GetInfoCallback = void (SocketInfo socketInfo);
 136
 137   // Callback from the <code>getSockets</code> method.
 138   // |socketInfos| : Array of object containing socket information.
 139   callback GetSocketsCallback = void (SocketInfo[] socketInfos);
 140
 141   // Data from an <code>onReceive</code> event.
 142   dictionary ReceiveInfo {
 143     // The socket identifier.
 144     long socketId;
 145
 146     // The data received, with a maxium size of <code>bufferSize</code>.
 147     ArrayBuffer data;
 148   };
 149
 150   // Data from an <code>onReceiveError</code> event.
 151   dictionary ReceiveErrorInfo {
 152     // The socket identifier.
 153     long socketId;
 154
 155      // The result code returned from the underlying network call.
 156     long resultCode;
 157   };
 158
 159   interface Functions {
 160     // Creates a TCP socket.
 161     // |properties| : The socket properties (optional).
 162     // |callback| : Called when the socket has been created.
 163     static void create(optional SocketProperties properties,
 164                        CreateCallback callback);
 165
 166     // Updates the socket properties.
 167     // |socketId| : The socket identifier.
 168     // |properties| : The properties to update.
 169     // |callback| : Called when the properties are updated.
 170     static void update(long socketId,
 171                        SocketProperties properties,
 172                        optional UpdateCallback callback);
 173
 174     // Enables or disables the application from receiving messages from its
 175     // peer. The default value is "false". Pausing a socket is typically used
 176     // by an application to throttle data sent by its peer. When a socket is
 177     // paused, no <code>onReceive</code> event is raised. When a socket is
 178     // connected and un-paused, <code>onReceive</code> events are raised again
 179     // when messages are received.
 180     static void setPaused(long socketId,
 181                           boolean paused,
 182                           optional SetPausedCallback callback);
 183
 184     // Enables or disables the keep-alive functionality for a TCP connection.
 185     // |socketId| : The socket identifier.
 186     // |enable| : If true, enable keep-alive functionality.
 187     // |delay| : Set the delay seconds between the last data packet received
 188     // and the first keepalive probe. Default is 0.
 189     // |callback| : Called when the setKeepAlive attempt is complete.
 190     static void setKeepAlive(long socketId,
 191                              boolean enable,
 192                              optional long delay,
 193                              SetKeepAliveCallback callback);
 194
 195     // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 196     // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 197     // |socketId| : The socket identifier.
 198     // |noDelay| : If true, disables Nagle's algorithm.
 199     // |callback| : Called when the setNoDelay attempt is complete.
 200     static void setNoDelay(long socketId,
 201                            boolean noDelay,
 202                            SetNoDelayCallback callback);
 203
 204     // Connects the socket to a remote machine. When the <code>connect</code>
 205     // operation completes successfully, <code>onReceive</code> events are
 206     // raised when data is received from the peer. If a network error occurs
 207     // while the runtime is receiving packets, a <code>onReceiveError</code>
 208     // event is raised, at which point no more <code>onReceive</code> event will
 209     // be raised for this socket until the <code>resume</code> method is called.
 210     // |socketId| : The socket identifier.
 211     // |peerAddress| : The address of the remote machine. DNS name, IPv4 and
 212     //  IPv6 formats are supported.
 213     // |peerPort| : The port of the remote machine.
 214     // |callback| : Called when the connect attempt is complete.
 215     static void connect(long socketId,
 216                         DOMString peerAddress,
 217                         long peerPort,
 218                         ConnectCallback callback);
 219
 220     // Disconnects the socket.
 221     // |socketId| : The socket identifier.
 222     // |callback| : Called when the disconnect attempt is complete.
 223     static void disconnect(long socketId,
 224                            optional DisconnectCallback callback);
 225
 226     // Start a TLS client connection over the connected TCP client socket.
 227     // |socketId| : The existing, connected socket to use.
 228     // |options| : Constraints and parameters for the TLS connection.
 229     // |callback| : Called when the connection attempt is complete.
 230     static void secure(long socketId,
 231                        optional SecureOptions options,
 232                        SecureCallback callback);
 233
 234     // Sends data on the given TCP socket.
 235     // |socketId| : The socket identifier.
 236     // |data| : The data to send.
 237     // |callback| : Called when the <code>send</code> operation completes.
 238     static void send(long socketId,
 239                      ArrayBuffer data,
 240                      SendCallback callback);
 241
 242     // Closes the socket and releases the address/port the socket is bound to.
 243     // Each socket created should be closed after use. The socket id is no
 244     // no longer valid as soon at the function is called. However, the socket is
 245     // guaranteed to be closed only when the callback is invoked.
 246     // |socketId| : The socket identifier.
 247     // |callback| : Called when the <code>close</code> operation completes.
 248     static void close(long socketId,
 249                       optional CloseCallback callback);
 250
 251     // Retrieves the state of the given socket.
 252     // |socketId| : The socket identifier.
 253     // |callback| : Called when the socket state is available.
 254     static void getInfo(long socketId,
 255                         GetInfoCallback callback);
 256
 257     // Retrieves the list of currently opened sockets owned by the application.
 258     // |callback| : Called when the list of sockets is available.
 259     static void getSockets(GetSocketsCallback callback);
 260   };
 261
 262   interface Events {
 263     // Event raised when data has been received for a given socket.
 264     // |info| : The event data.
 265     static void onReceive(ReceiveInfo info);
 266
 267     // Event raised when a network error occured while the runtime was waiting
 268     // for data on the socket address and port. Once this event is raised, the
 269     // socket is set to <code>paused</code> and no more <code>onReceive</code>
 270     // events are raised for this socket.
 271     // |info| : The event data.
 272     static void onReceiveError(ReceiveErrorInfo info);
 273   };
 274 };