/* 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); /** * the same as init(), but initializes an IPv6 server socket */ void initIPv6(in long aPort, in boolean aLoopbackOnly, in long aBackLog); /** * Similar to init(), but initializes a server socket that supports * both IPv4 and IPv6. */ void initDualStack(in long aPort, 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); };