// 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);
  };
};