extensions/common/api/sockets_tcp_server.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.tcpServer</code> API to create server
   6 // applications using TCP connections. This API supersedes the TCP functionality
   7 // previously found in the <code>chrome.socket</code> API.
   8 namespace sockets.tcpServer {
   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 remains open when the event page of the
  16     // 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
  27   // Result of <code>create</code> call.
  28   dictionary CreateInfo {
  29     // The ID of the newly created server socket. Note that socket IDs created
  30     // from this API are not compatible with socket IDs created from other APIs,
  31     // such as the deprecated <code>$(ref:socket)</code> API.
  32     long socketId;
  33   };
  34
  35   // Callback from the <code>create</code> method.
  36   // |createInfo| : The result of the socket creation.
  37   callback CreateCallback = void (CreateInfo createInfo);
  38
  39   // Callback from the <code>listen</code> method.
  40   // |result| : The result code returned from the underlying network call.
  41   // A negative value indicates an error.
  42   callback ListenCallback = void (long result);
  43
  44   // Callback from the <code>disconnect</code> method.
  45   callback DisconnectCallback = void ();
  46
  47   // Callback from the <code>close</code> method.
  48   callback CloseCallback = void ();
  49
  50   // Callback from the <code>update</code> method.
  51   callback UpdateCallback = void ();
  52
  53   // Callback from the <code>setPaused</code> method.
  54   callback SetPausedCallback = void ();
  55
  56   // Result of the <code>getInfo</code> method.
  57   dictionary SocketInfo {
  58     // The socket identifier.
  59     long socketId;
  60
  61     // Flag indicating if the socket remains open when the event page of the
  62     // application is unloaded (see <code>SocketProperties.persistent</code>).
  63     // The default value is "false".
  64     boolean persistent;
  65
  66     // Application-defined string associated with the socket.
  67     DOMString? name;
  68
  69     // Flag indicating whether connection requests on a listening socket are
  70     // dispatched through the <code>onAccept</code> event or queued up in the
  71     // listen queue backlog.
  72     // See <code>setPaused</code>. The default value is "false".
  73     boolean paused;
  74
  75     // If the socket is listening, contains its local IPv4/6 address.
  76     DOMString? localAddress;
  77
  78     // If the socket is listening, contains its local port.
  79     long? localPort;
  80   };
  81
  82   // Callback from the <code>getInfo</code> method.
  83   // |socketInfo| : Object containing the socket information.
  84   callback GetInfoCallback = void (SocketInfo socketInfo);
  85
  86   // Callback from the <code>getSockets</code> method.
  87   // |socketInfos| : Array of object containing socket information.
  88   callback GetSocketsCallback = void (SocketInfo[] socketInfos);
  89
  90   // Data from an <code>onAccept</code> event.
  91   dictionary AcceptInfo {
  92     // The server socket identifier.
  93     long socketId;
  94
  95     // The client socket identifier, i.e. the socket identifier of the newly
  96     // established connection. This socket identifier should be used only with
  97     // functions from the <code>chrome.sockets.tcp</code> namespace. Note the
  98     // client socket is initially paused and must be explictly un-paused by the
  99     // application to start receiving data.
 100     long clientSocketId;
 101   };
 102
 103   // Data from an <code>onAcceptError</code> event.
 104   dictionary AcceptErrorInfo {
 105     // The server socket identifier.
 106     long socketId;
 107
 108     // The result code returned from the underlying network call.
 109     long resultCode;
 110   };
 111
 112   interface Functions {
 113     // Creates a TCP server socket.
 114     // |properties| : The socket properties (optional).
 115     // |callback| : Called when the socket has been created.
 116     static void create(optional SocketProperties properties,
 117                        CreateCallback callback);
 118
 119     // Updates the socket properties.
 120     // |socketId| : The socket identifier.
 121     // |properties| : The properties to update.
 122     // |callback| : Called when the properties are updated.
 123     static void update(long socketId,
 124                        SocketProperties properties,
 125                        optional UpdateCallback callback);
 126
 127     // Enables or disables a listening socket from accepting new connections.
 128     // When paused, a listening socket accepts new connections until its backlog
 129     // (see <code>listen</code> function) is full then refuses additional
 130     // connection requests. <code>onAccept</code> events are raised only when
 131     // the socket is un-paused.
 132     static void setPaused(long socketId,
 133                           boolean paused,
 134                           optional SetPausedCallback callback);
 135
 136     // Listens for connections on the specified port and address.
 137     // If the port/address is in use, the callback indicates a failure.
 138     // |socketId| : The socket identifier.
 139     // |address| : The address of the local machine.
 140     // |port| : The port of the local machine. When set to <code>0</code>, a
 141     // free port is chosen dynamically. The dynamically allocated port can be
 142     // found by calling <code>getInfo</code>.
 143     // |backlog| : Length of the socket's listen queue. The default value
 144     // depends on the Operating System (SOMAXCONN), which ensures a reasonable
 145     // queue length for most applications.
 146     // |callback| : Called when listen operation completes.
 147     static void listen(long socketId,
 148                        DOMString address,
 149                        long port,
 150                        optional long backlog,
 151                        ListenCallback callback);
 152
 153     // Disconnects the listening socket, i.e. stops accepting new connections
 154     // and releases the address/port the socket is bound to. The socket
 155     // identifier remains valid, e.g. it can be used with <code>listen</code> to
 156     // accept connections on a new port and address.
 157     // |socketId| : The socket identifier.
 158     // |callback| : Called when the disconnect attempt is complete.
 159     static void disconnect(long socketId,
 160                            optional DisconnectCallback callback);
 161
 162     // Disconnects and destroys the socket. Each socket created should be
 163     // closed after use. The socket id is no longer valid as soon at the
 164     // function is called. However, the socket is guaranteed to be closed only
 165     // when the callback is invoked.
 166     // |socketId| : The socket identifier.
 167     // |callback| : Called when the <code>close</code> operation completes.
 168     static void close(long socketId,
 169                       optional CloseCallback callback);
 170
 171     // Retrieves the state of the given socket.
 172     // |socketId| : The socket identifier.
 173     // |callback| : Called when the socket state is available.
 174     static void getInfo(long socketId,
 175                         GetInfoCallback callback);
 176
 177     // Retrieves the list of currently opened sockets owned by the application.
 178     // |callback| : Called when the list of sockets is available.
 179     static void getSockets(GetSocketsCallback callback);
 180   };
 181
 182   interface Events {
 183     // Event raised when a connection has been made to the server socket.
 184     // |info| : The event data.
 185     static void onAccept(AcceptInfo info);
 186
 187     // Event raised when a network error occured while the runtime was waiting
 188     // for new connections on the socket address and port. Once this event is
 189     // raised, the socket is set to <code>paused</code> and no more
 190     // <code>onAccept</code> events are raised for this socket until the socket
 191     // is resumed.
 192     // |info| : The event data.
 193     static void onAcceptError(AcceptErrorInfo info);
 194   };
 195 };