src/chrome/common/extensions/api/sockets_tcp.idl

   1 // Copyright 2013 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. Note that the socket
   8 // ids created from this namespace are not compatible with ids created in other
   9 // namespaces.
  10 namespace sockets.tcp {
  11   // The socket properties specified in the <code>create</code> or
  12   // <code>update</code> function. Each property is optional. If a property
  13   // value is not specified, a default value is used when calling
  14   // <code>create</code>, or the existing value if preserved when calling
  15   // <code>update</code>.
  16   dictionary SocketProperties {
  17     // Flag indicating if the socket is left open when the event page of
  18     // the application is unloaded (see
  19     // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
  20     // Lifecycle</a>). The default value is "false." When the application is
  21     // loaded, any sockets previously opened with persistent=true can be fetched
  22     // with <code>getSockets</code>.
  23     boolean? persistent;
  24
  25     // An application-defined string associated with the socket.
  26     DOMString? name;
  27
  28     // The size of the buffer used to receive data. The default value is 4096.
  29     long? bufferSize;
  30   };
  31
  32   // Result of <code>create</code> call.
  33   dictionary CreateInfo {
  34     // The ID of the newly created socket.
  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   // Result of the <code>getInfo</code> method.
  84   dictionary SocketInfo {
  85     // The socket identifier.
  86     long socketId;
  87
  88     // Flag indicating whether the socket is left open when the application is
  89     // suspended (see <code>SocketProperties.persistent</code>).
  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 (see <code>setPaused</code>).
 101     boolean paused;
 102
 103     // Flag indicating whether the socket is connected to a remote peer.
 104     boolean connected;
 105
 106     // If the underlying socket is connected, contains its local IPv4/6 address.
 107     DOMString? localAddress;
 108
 109     // If the underlying socket is connected, contains its local port.
 110     long? localPort;
 111
 112     // If the underlying socket is connected, contains the peer/ IPv4/6 address.
 113     DOMString? peerAddress;
 114
 115     // If the underlying socket is connected, contains the peer port.
 116     long? peerPort;
 117   };
 118
 119   // Callback from the <code>getInfo</code> method.
 120   // |socketInfo| : Object containing the socket information.
 121   callback GetInfoCallback = void (SocketInfo socketInfo);
 122
 123   // Callback from the <code>getSockets</code> method.
 124   // |socketInfos| : Array of object containing socket information.
 125   callback GetSocketsCallback = void (SocketInfo[] socketInfos);
 126
 127   // Data from an <code>onReceive</code> event.
 128   dictionary ReceiveInfo {
 129     // The socket identifier.
 130     long socketId;
 131
 132     // The data received, with a maxium size of <code>bufferSize</code>.
 133     ArrayBuffer data;
 134   };
 135
 136   // Data from an <code>onReceiveError</code> event.
 137   dictionary ReceiveErrorInfo {
 138     // The socket identifier.
 139     long socketId;
 140
 141      // The result code returned from the underlying network call.
 142     long resultCode;
 143   };
 144
 145   interface Functions {
 146     // Creates a TCP socket.
 147     // |properties| : The socket properties (optional).
 148     // |callback| : Called when the socket has been created.
 149     static void create(optional SocketProperties properties,
 150                        CreateCallback callback);
 151
 152     // Updates the socket properties.
 153     // |socketId| : The socket identifier.
 154     // |properties| : The properties to update.
 155     // |callback| : Called when the properties are updated.
 156     static void update(long socketId,
 157                        SocketProperties properties,
 158                        UpdateCallback callback);
 159
 160     // Enables or disables the application from receiving messages from its
 161     // peer. The default value is "false". Pausing a socket is typically used
 162     // by an application to throttle data sent by its peer. When a socket is
 163     // paused, no <code>onReceive<code> event is raised. When a socket is
 164     // connected and un-paused, <code>onReceive<code> events are raised again
 165     // when messages are received.
 166     static void setPaused(long socketId,
 167                           boolean paused,
 168                           SetPausedCallback callback);
 169
 170     // Enables or disables the keep-alive functionality for a TCP connection.
 171     // |socketId| : The socket identifier.
 172     // |enable| : If true, enable keep-alive functionality.
 173     // |delay| : Set the delay seconds between the last data packet received
 174     // and the first keepalive probe. Default is 0.
 175     // |callback| : Called when the setKeepAlive attempt is complete.
 176     static void setKeepAlive(long socketId,
 177                              boolean enable,
 178                              optional long delay,
 179                              SetKeepAliveCallback callback);
 180
 181     // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 182     // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 183     // |socketId| : The socket identifier.
 184     // |noDelay| : If true, disables Nagle's algorithm.
 185     // |callback| : Called when the setNoDelay attempt is complete.
 186     static void setNoDelay(long socketId,
 187                            boolean noDelay,
 188                            SetNoDelayCallback callback);
 189
 190     // Connects the socket to a remote machine. When the <code>connect</code>
 191     // operation completes successfully, <code>onReceive</code> events are
 192     // raised when data is received from the peer. If a network error occurs
 193     // while the runtime is receiving packets, a <code>onReceiveError</code>
 194     // event is raised, at which point no more <code>onReceive</code> event will
 195     // be raised for this socket until the <code>resume</code> method is called.
 196     // |socketId| : The socket identifier.
 197     // |peerAddress| : The address of the remote machine. DNS name, IPv4 and
 198     //  IPv6 formats are supported.
 199     // |peerPort| : The port of the remote machine.
 200     // |callback| : Called when the connect attempt is complete.
 201     static void connect(long socketId,
 202                         DOMString peerAddress,
 203                         long peerPort,
 204                         ConnectCallback callback);
 205
 206     // Disconnects the socket.
 207     // |socketId| : The socket identifier.
 208     // |callback| : Called when the disconnect attempt is complete.
 209     static void disconnect(long socketId,
 210                            optional DisconnectCallback callback);
 211
 212     // Sends data on the given TCP socket.
 213     // |socketId| : The socket identifier.
 214     // |data| : The data to send.
 215     // |callback| : Called when the <code>send</code> operation completes.
 216     static void send(long socketId,
 217                      ArrayBuffer data,
 218                      SendCallback callback);
 219
 220     // Closes the socket and releases the address/port the socket is bound to.
 221     // Each socket created should be closed after use. The socket id is no
 222     // no longer valid as soon at the function is called. However, the socket is
 223     // guaranteed to be closed only when the callback is invoked.
 224     // |socketId| : The socket identifier.
 225     // |callback| : Called when the <code>close</code> operation completes.
 226     static void close(long socketId,
 227                       optional CloseCallback callback);
 228
 229     // Retrieves the state of the given socket.
 230     // |socketId| : The socket identifier.
 231     // |callback| : Called when the socket state is available.
 232     static void getInfo(long socketId,
 233                         GetInfoCallback callback);
 234
 235     // Retrieves the list of currently opened sockets owned by the application.
 236     // |callback| : Called when the list of sockets is available.
 237     static void getSockets(GetSocketsCallback callback);
 238   };
 239
 240   interface Events {
 241     // Event raised when data has been received for a given socket.
 242     // |info| : The event data.
 243     static void onReceive(ReceiveInfo info);
 244
 245     // Event raised when a network error occured while the runtime was waiting
 246     // for data on the socket address and port. Once this event is raised, the
 247     // socket is set to <code>paused</code> and no more <code>onReceive</code>
 248     // events are raised for this socket.
 249     // |info| : The event data.
 250     static void onReceiveError(ReceiveErrorInfo info);
 251   };
 252 };