/* vim:set ts=4 sw=4 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIFile;
interface nsIServerSocketListener;
interface nsISocketTransport;

native PRNetAddr(union PRNetAddr);
[ptr] native PRNetAddrPtr(union PRNetAddr);

typedef unsigned long nsServerSocketFlag;

/**
 * nsIServerSocket
 *
 * An interface to a server socket that can accept incoming connections.
 */
[scriptable, uuid(7a9c39cb-a13f-4eef-9bdf-a74301628742)]
interface nsIServerSocket : nsISupports
{
    /**
     * @name Server Socket Flags
     * These flags define various socket options.
     * @{
     */
    /// The server socket will only respond to connections on the
    /// local loopback interface.  Otherwise, it will accept connections
    /// from any interface.  To specify a particular network interface,
    /// use initWithAddress.
    const nsServerSocketFlag LoopbackOnly = 0x00000001;
    /// The server socket will not be closed when Gecko is set
    /// offline.
    const nsServerSocketFlag KeepWhenOffline = 0x00000002;
    /** @} */

    /**
     * init
     *
     * This method initializes a server socket.
     *
     * @param aPort
     *        The port of the server socket.  Pass -1 to indicate no preference,
     *        and a port will be selected automatically.
     * @param aLoopbackOnly
     *        If true, the server socket will only respond to connections on the
     *        local loopback interface.  Otherwise, it will accept connections
     *        from any interface.  To specify a particular network interface,
     *        use initWithAddress.
     * @param aBackLog
     *        The maximum length the queue of pending connections may grow to.
     *        This parameter may be silently limited by the operating system.
     *        Pass -1 to use the default value.
     */
    void init(in long aPort,
              in boolean aLoopbackOnly,
              in long aBackLog);

    /**
     * initSpecialConnection
     *
     * This method initializes a server socket and offers the ability to have
     * that socket not get terminated if Gecko is set offline.
     *
     * @param aPort
     *        The port of the server socket.  Pass -1 to indicate no preference,
     *        and a port will be selected automatically.
     * @param aFlags
     *        Flags for the socket.
     * @param aBackLog
     *        The maximum length the queue of pending connections may grow to.
     *        This parameter may be silently limited by the operating system.
     *        Pass -1 to use the default value.
     */
    void initSpecialConnection(in long aPort,
                               in nsServerSocketFlag aFlags,
                               in long aBackLog);


    /**
     * initWithAddress
     *
     * This method initializes a server socket, and binds it to a particular
     * local address (and hence a particular local network interface).
     *
     * @param aAddr
     *        The address to which this server socket should be bound.
     * @param aBackLog
     *        The maximum length the queue of pending connections may grow to.
     *        This parameter may be silently limited by the operating system.
     *        Pass -1 to use the default value.
     */
    [noscript] void initWithAddress([const] in PRNetAddrPtr aAddr, in long aBackLog);

    /**
     * initWithFilename
     *
     * This method initializes a Unix domain or "local" server socket. Such
     * a socket has a name in the filesystem, like an ordinary file. To
     * connect, a client supplies the socket's filename, and the usual
     * permission checks on socket apply.
     *
     * This makes Unix domain sockets useful for communication between the
     * programs being run by a specific user on a single machine: the
     * operating system takes care of authentication, and the user's home
     * directory or profile directory provide natural per-user rendezvous
     * points.
     *
     * Since Unix domain sockets are always local to the machine, they are
     * not affected by the nsIIOService's 'offline' flag.
     *
     * The system-level socket API may impose restrictions on the length of
     * the filename that are stricter than those of the underlying
     * filesystem. If the file name is too long, this returns
     * NS_ERROR_FILE_NAME_TOO_LONG.
     *
     * All components of the path prefix of |aPath| must name directories;
     * otherwise, this returns NS_ERROR_FILE_NOT_DIRECTORY.
     *
     * This call requires execute permission on all directories containing
     * the one in which the socket is to be created, and write and execute
     * permission on the directory itself. Otherwise, this returns
     * NS_ERROR_CONNECTION_REFUSED.
     *
     * This call creates the socket's directory entry. There must not be
     * any existing entry with the given name. If there is, this returns
     * NS_ERROR_SOCKET_ADDRESS_IN_USE.
     *
     * On systems that don't support Unix domain sockets at all, this
     * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
     *
     * @param aPath nsIFile
     *        The file name at which the socket should be created.
     *
     * @param aPermissions unsigned long
     *        Unix-style permission bits to be applied to the new socket.
     *
     * Note about permissions: Linux's unix(7) man page claims that some
     * BSD-derived systems ignore permissions on UNIX-domain sockets;
     * NetBSD's bind(2) man page agrees, but says it does check now (dated
     * 2005). POSIX has required 'connect' to fail if write permission on
     * the socket itself is not granted since 2003 (Issue 6). NetBSD says
     * that the permissions on the containing directory (execute) have
     * always applied, so creating sockets in appropriately protected
     * directories should be secure on both old and new systems.
     */
    void initWithFilename(in nsIFile aPath, in unsigned long aPermissions,
                          in long aBacklog);

    /**
     * initWithAbstractAddress
     *
     * This mehtod is a flavor of initWithFilename method. This initializes
     * a UNIX domain socket that uses abstract socket address.
     * This socket type is only supported on Linux and Android.
     *
     * On systems that don't support this type's UNIX domain sockets at all,
     * this returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
     *
     * @param aName
     *        The abstract socket address which the socket should be created.
     * @param aBacklog
     *        The maximum length the queue of pending connections may grow to.
     */
    void initWithAbstractAddress(in AUTF8String aName,
                                 in long aBacklog);

    /**
     * close
     *
     * This method closes a server socket.  This does not affect already
     * connected client sockets (i.e., the nsISocketTransport instances
     * created from this server socket).  This will cause the onStopListening
     * event to asynchronously fire with a status of NS_BINDING_ABORTED.
     */
    void close();

    /**
     * asyncListen
     *
     * This method puts the server socket in the listening state.  It will
     * asynchronously listen for and accept client connections.  The listener
     * will be notified once for each client connection that is accepted.  The
     * listener's onSocketAccepted method will be called on the same thread
     * that called asyncListen (the calling thread must have a nsIEventTarget).
     *
     * The listener will be passed a reference to an already connected socket
     * transport (nsISocketTransport).  See below for more details.
     *
     * @param aListener
     *        The listener to be notified when client connections are accepted.
     */
    void asyncListen(in nsIServerSocketListener aListener);

    /**
     * Returns the port of this server socket.
     */
    readonly attribute long port;

    /**
     * Returns the address to which this server socket is bound.  Since a
     * server socket may be bound to multiple network devices, this address
     * may not necessarily be specific to a single network device.  In the
     * case of an IP socket, the IP address field would be zerod out to
     * indicate a server socket bound to all network devices.  Therefore,
     * this method cannot be used to determine the IP address of the local
     * system.  See nsIDNSService::myHostName if this is what you need.
     */
    [noscript] PRNetAddr getAddress();
};

/**
 * nsIServerSocketListener
 *
 * This interface is notified whenever a server socket accepts a new connection.
 * The transport is in the connected state, and read/write streams can be opened
 * using the normal nsITransport API.  The address of the client can be found by
 * calling the nsISocketTransport::GetAddress method or by inspecting
 * nsISocketTransport::GetHost, which returns a string representation of the
 * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
 */
[scriptable, uuid(836d98ec-fee2-4bde-b609-abd5e966eabd)]
interface nsIServerSocketListener : nsISupports
{
    /**
     * onSocketAccepted
     *
     * This method is called when a client connection is accepted.
     *
     * @param aServ
     *        The server socket.
     * @param aTransport
     *        The connected socket transport.
     */
    void onSocketAccepted(in nsIServerSocket aServ,
                          in nsISocketTransport aTransport);

    /**
     * onStopListening
     *
     * This method is called when the listening socket stops for some reason.
     * The server socket is effectively dead after this notification.
     *
     * @param aServ
     *        The server socket.
     * @param aStatus
     *        The reason why the server socket stopped listening.  If the
     *        server socket was manually closed, then this value will be
     *        NS_BINDING_ABORTED.
     */
    void onStopListening(in nsIServerSocket aServ, in nsresult aStatus);
};