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>tls1</code>, <code>tls1.1</code>, or <code>tls1.2</code>.
  86     DOMString? min;
  87     DOMString? max;
  88   };
  89
  90   dictionary SecureOptions {
  91     TLSVersionConstraints? tlsVersion;
  92   };
  93
  94   callback SecureCallback = void (long result);
  95
  96   // Result of the <code>getInfo</code> method.
  97   dictionary SocketInfo {
  98     // The socket identifier.
  99     long socketId;
 100
 101     // Flag indicating whether the socket is left open when the application is
 102     // suspended (see <code>SocketProperties.persistent</code>).
 103     boolean persistent;
 104
 105     // Application-defined string associated with the socket.
 106     DOMString? name;
 107
 108     // The size of the buffer used to receive data. If no buffer size has been
 109     // specified explictly, the value is not provided.
 110     long? bufferSize;
 111
 112     // Flag indicating whether a connected socket blocks its peer from sending
 113     // more data (see <code>setPaused</code>).
 114     boolean paused;
 115
 116     // Flag indicating whether the socket is connected to a remote peer.
 117     boolean connected;
 118
 119     // If the underlying socket is connected, contains its local IPv4/6 address.
 120     DOMString? localAddress;
 121
 122     // If the underlying socket is connected, contains its local port.
 123     long? localPort;
 124
 125     // If the underlying socket is connected, contains the peer/ IPv4/6 address.
 126     DOMString? peerAddress;
 127
 128     // If the underlying socket is connected, contains the peer port.
 129     long? peerPort;
 130   };
 131
 132   // Callback from the <code>getInfo</code> method.
 133   // |socketInfo| : Object containing the socket information.
 134   callback GetInfoCallback = void (SocketInfo socketInfo);
 135
 136   // Callback from the <code>getSockets</code> method.
 137   // |socketInfos| : Array of object containing socket information.
 138   callback GetSocketsCallback = void (SocketInfo[] socketInfos);
 139
 140   // Data from an <code>onReceive</code> event.
 141   dictionary ReceiveInfo {
 142     // The socket identifier.
 143     long socketId;
 144
 145     // The data received, with a maxium size of <code>bufferSize</code>.
 146     ArrayBuffer data;
 147   };
 148
 149   // Data from an <code>onReceiveError</code> event.
 150   dictionary ReceiveErrorInfo {
 151     // The socket identifier.
 152     long socketId;
 153
 154      // The result code returned from the underlying network call.
 155     long resultCode;
 156   };
 157
 158   interface Functions {
 159     // Creates a TCP socket.
 160     // |properties| : The socket properties (optional).
 161     // |callback| : Called when the socket has been created.
 162     static void create(optional SocketProperties properties,
 163                        CreateCallback callback);
 164
 165     // Updates the socket properties.
 166     // |socketId| : The socket identifier.
 167     // |properties| : The properties to update.
 168     // |callback| : Called when the properties are updated.
 169     static void update(long socketId,
 170                        SocketProperties properties,
 171                        optional UpdateCallback callback);
 172
 173     // Enables or disables the application from receiving messages from its
 174     // peer. The default value is "false". Pausing a socket is typically used
 175     // by an application to throttle data sent by its peer. When a socket is
 176     // paused, no <code>onReceive</code> event is raised. When a socket is
 177     // connected and un-paused, <code>onReceive</code> events are raised again
 178     // when messages are received.
 179     static void setPaused(long socketId,
 180                           boolean paused,
 181                           optional SetPausedCallback callback);
 182
 183     // Enables or disables the keep-alive functionality for a TCP connection.
 184     // |socketId| : The socket identifier.
 185     // |enable| : If true, enable keep-alive functionality.
 186     // |delay| : Set the delay seconds between the last data packet received
 187     // and the first keepalive probe. Default is 0.
 188     // |callback| : Called when the setKeepAlive attempt is complete.
 189     static void setKeepAlive(long socketId,
 190                              boolean enable,
 191                              optional long delay,
 192                              SetKeepAliveCallback callback);
 193
 194     // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 195     // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 196     // |socketId| : The socket identifier.
 197     // |noDelay| : If true, disables Nagle's algorithm.
 198     // |callback| : Called when the setNoDelay attempt is complete.
 199     static void setNoDelay(long socketId,
 200                            boolean noDelay,
 201                            SetNoDelayCallback callback);
 202
 203     // Connects the socket to a remote machine. When the <code>connect</code>
 204     // operation completes successfully, <code>onReceive</code> events are
 205     // raised when data is received from the peer. If a network error occurs
 206     // while the runtime is receiving packets, a <code>onReceiveError</code>
 207     // event is raised, at which point no more <code>onReceive</code> event will
 208     // be raised for this socket until the <code>resume</code> method is called.
 209     // |socketId| : The socket identifier.
 210     // |peerAddress| : The address of the remote machine. DNS name, IPv4 and
 211     //  IPv6 formats are supported.
 212     // |peerPort| : The port of the remote machine.
 213     // |callback| : Called when the connect attempt is complete.
 214     static void connect(long socketId,
 215                         DOMString peerAddress,
 216                         long peerPort,
 217                         ConnectCallback callback);
 218
 219     // Disconnects the socket.
 220     // |socketId| : The socket identifier.
 221     // |callback| : Called when the disconnect attempt is complete.
 222     static void disconnect(long socketId,
 223                            optional DisconnectCallback callback);
 224
 225     // Start a TLS client connection over the connected TCP client socket.
 226     // |socketId| : The existing, connected socket to use.
 227     // |options| : Constraints and parameters for the TLS connection.
 228     // |callback| : Called when the connection attempt is complete.
 229     static void secure(long socketId,
 230                        optional SecureOptions options,
 231                        SecureCallback callback);
 232
 233     // Sends data on the given TCP socket.
 234     // |socketId| : The socket identifier.
 235     // |data| : The data to send.
 236     // |callback| : Called when the <code>send</code> operation completes.
 237     static void send(long socketId,
 238                      ArrayBuffer data,
 239                      SendCallback callback);
 240
 241     // Closes the socket and releases the address/port the socket is bound to.
 242     // Each socket created should be closed after use. The socket id is no
 243     // no longer valid as soon at the function is called. However, the socket is
 244     // guaranteed to be closed only when the callback is invoked.
 245     // |socketId| : The socket identifier.
 246     // |callback| : Called when the <code>close</code> operation completes.
 247     static void close(long socketId,
 248                       optional CloseCallback callback);
 249
 250     // Retrieves the state of the given socket.
 251     // |socketId| : The socket identifier.
 252     // |callback| : Called when the socket state is available.
 253     static void getInfo(long socketId,
 254                         GetInfoCallback callback);
 255
 256     // Retrieves the list of currently opened sockets owned by the application.
 257     // |callback| : Called when the list of sockets is available.
 258     static void getSockets(GetSocketsCallback callback);
 259   };
 260
 261   interface Events {
 262     // Event raised when data has been received for a given socket.
 263     // |info| : The event data.
 264     static void onReceive(ReceiveInfo info);
 265
 266     // Event raised when a network error occured while the runtime was waiting
 267     // for data on the socket address and port. Once this event is raised, the
 268     // socket is set to <code>paused</code> and no more <code>onReceive</code>
 269     // events are raised for this socket.
 270     // |info| : The event data.
 271     static void onReceiveError(ReceiveErrorInfo info);
 272   };
 273 };