diff options
Diffstat (limited to 'netwerk/base/nsIServerSocket.idl')
| -rw-r--r-- | netwerk/base/nsIServerSocket.idl | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/netwerk/base/nsIServerSocket.idl b/netwerk/base/nsIServerSocket.idl new file mode 100644 index 0000000000..61e38602ff --- /dev/null +++ b/netwerk/base/nsIServerSocket.idl @@ -0,0 +1,262 @@ +/* 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); + + /** + * 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); +}; |