| // Copyright 2014 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| // Use the <code>chrome.sockets.tcpServer</code> API to create server |
| // applications using TCP connections. This API supersedes the TCP functionality |
| // previously found in the <code>chrome.socket</code> API. |
| namespace sockets.tcpServer { |
| // The socket properties specified in the <code>create</code> or |
| // <code>update</code> function. Each property is optional. If a property |
| // value is not specified, a default value is used when calling |
| // <code>create</code>, or the existing value if preserved when calling |
| // <code>update</code>. |
| dictionary SocketProperties { |
| // Flag indicating if the socket remains open when the event page of the |
| // application is unloaded (see |
| // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App |
| // Lifecycle</a>). The default value is "false." When the application is |
| // loaded, any sockets previously opened with persistent=true can be fetched |
| // with <code>getSockets</code>. |
| boolean? persistent; |
| |
| // An application-defined string associated with the socket. |
| DOMString? name; |
| }; |
| |
| // Result of <code>create</code> call. |
| dictionary CreateInfo { |
| // The ID of the newly created server socket. Note that socket IDs created |
| // from this API are not compatible with socket IDs created from other APIs, |
| // such as the deprecated <code>$(ref:socket)</code> API. |
| long socketId; |
| }; |
| |
| // Callback from the <code>create</code> method. |
| // |createInfo| : The result of the socket creation. |
| callback CreateCallback = void (CreateInfo createInfo); |
| |
| // Callback from the <code>listen</code> method. |
| // |result| : The result code returned from the underlying network call. |
| // A negative value indicates an error. |
| callback ListenCallback = void (long result); |
| |
| // Callback from the <code>disconnect</code> method. |
| callback DisconnectCallback = void (); |
| |
| // Callback from the <code>close</code> method. |
| callback CloseCallback = void (); |
| |
| // Callback from the <code>update</code> method. |
| callback UpdateCallback = void (); |
| |
| // Callback from the <code>setPaused</code> method. |
| callback SetPausedCallback = void (); |
| |
| // Result of the <code>getInfo</code> method. |
| dictionary SocketInfo { |
| // The socket identifier. |
| long socketId; |
| |
| // Flag indicating if the socket remains open when the event page of the |
| // application is unloaded (see <code>SocketProperties.persistent</code>). |
| // The default value is "false". |
| boolean persistent; |
| |
| // Application-defined string associated with the socket. |
| DOMString? name; |
| |
| // Flag indicating whether connection requests on a listening socket are |
| // dispatched through the <code>onAccept</code> event or queued up in the |
| // listen queue backlog. |
| // See <code>setPaused</code>. The default value is "false". |
| boolean paused; |
| |
| // If the socket is listening, contains its local IPv4/6 address. |
| DOMString? localAddress; |
| |
| // If the socket is listening, contains its local port. |
| long? localPort; |
| }; |
| |
| // Callback from the <code>getInfo</code> method. |
| // |socketInfo| : Object containing the socket information. |
| callback GetInfoCallback = void (SocketInfo socketInfo); |
| |
| // Callback from the <code>getSockets</code> method. |
| // |socketInfos| : Array of object containing socket information. |
| callback GetSocketsCallback = void (SocketInfo[] socketInfos); |
| |
| // Data from an <code>onAccept</code> event. |
| dictionary AcceptInfo { |
| // The server socket identifier. |
| long socketId; |
| |
| // The client socket identifier, i.e. the socket identifier of the newly |
| // established connection. This socket identifier should be used only with |
| // functions from the <code>chrome.sockets.tcp</code> namespace. Note the |
| // client socket is initially paused and must be explictly un-paused by the |
| // application to start receiving data. |
| long clientSocketId; |
| }; |
| |
| // Data from an <code>onAcceptError</code> event. |
| dictionary AcceptErrorInfo { |
| // The server socket identifier. |
| long socketId; |
| |
| // The result code returned from the underlying network call. |
| long resultCode; |
| }; |
| |
| interface Functions { |
| // Creates a TCP server socket. |
| // |properties| : The socket properties (optional). |
| // |callback| : Called when the socket has been created. |
| static void create(optional SocketProperties properties, |
| CreateCallback callback); |
| |
| // Updates the socket properties. |
| // |socketId| : The socket identifier. |
| // |properties| : The properties to update. |
| // |callback| : Called when the properties are updated. |
| static void update(long socketId, |
| SocketProperties properties, |
| optional UpdateCallback callback); |
| |
| // Enables or disables a listening socket from accepting new connections. |
| // When paused, a listening socket accepts new connections until its backlog |
| // (see <code>listen</code> function) is full then refuses additional |
| // connection requests. <code>onAccept</code> events are raised only when |
| // the socket is un-paused. |
| static void setPaused(long socketId, |
| boolean paused, |
| optional SetPausedCallback callback); |
| |
| // Listens for connections on the specified port and address. |
| // If the port/address is in use, the callback indicates a failure. |
| // |socketId| : The socket identifier. |
| // |address| : The address of the local machine. |
| // |port| : The port of the local machine. When set to <code>0</code>, a |
| // free port is chosen dynamically. The dynamically allocated port can be |
| // found by calling <code>getInfo</code>. |
| // |backlog| : Length of the socket's listen queue. The default value |
| // depends on the Operating System (SOMAXCONN), which ensures a reasonable |
| // queue length for most applications. |
| // |callback| : Called when listen operation completes. |
| static void listen(long socketId, |
| DOMString address, |
| long port, |
| optional long backlog, |
| ListenCallback callback); |
| |
| // Disconnects the listening socket, i.e. stops accepting new connections |
| // and releases the address/port the socket is bound to. The socket |
| // identifier remains valid, e.g. it can be used with <code>listen</code> to |
| // accept connections on a new port and address. |
| // |socketId| : The socket identifier. |
| // |callback| : Called when the disconnect attempt is complete. |
| static void disconnect(long socketId, |
| optional DisconnectCallback callback); |
| |
| // Disconnects and destroys the socket. Each socket created should be |
| // closed after use. The socket id is no longer valid as soon at the |
| // function is called. However, the socket is guaranteed to be closed only |
| // when the callback is invoked. |
| // |socketId| : The socket identifier. |
| // |callback| : Called when the <code>close</code> operation completes. |
| static void close(long socketId, |
| optional CloseCallback callback); |
| |
| // Retrieves the state of the given socket. |
| // |socketId| : The socket identifier. |
| // |callback| : Called when the socket state is available. |
| static void getInfo(long socketId, |
| GetInfoCallback callback); |
| |
| // Retrieves the list of currently opened sockets owned by the application. |
| // |callback| : Called when the list of sockets is available. |
| static void getSockets(GetSocketsCallback callback); |
| }; |
| |
| interface Events { |
| // Event raised when a connection has been made to the server socket. |
| // |info| : The event data. |
| static void onAccept(AcceptInfo info); |
| |
| // Event raised when a network error occured while the runtime was waiting |
| // for new connections on the socket address and port. Once this event is |
| // raised, the socket is set to <code>paused</code> and no more |
| // <code>onAccept</code> events are raised for this socket until the socket |
| // is resumed. |
| // |info| : The event data. |
| static void onAcceptError(AcceptErrorInfo info); |
| }; |
| }; |