1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIServerSocket.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,237 @@
1.4 +/* vim:set ts=4 sw=4 et cindent: */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIFile;
1.12 +interface nsIServerSocketListener;
1.13 +interface nsISocketTransport;
1.14 +
1.15 +native PRNetAddr(union PRNetAddr);
1.16 +[ptr] native PRNetAddrPtr(union PRNetAddr);
1.17 +
1.18 +typedef unsigned long nsServerSocketFlag;
1.19 +
1.20 +/**
1.21 + * nsIServerSocket
1.22 + *
1.23 + * An interface to a server socket that can accept incoming connections.
1.24 + */
1.25 +[scriptable, uuid(7a9c39cb-a13f-4eef-9bdf-a74301628742)]
1.26 +interface nsIServerSocket : nsISupports
1.27 +{
1.28 + /**
1.29 + * @name Server Socket Flags
1.30 + * These flags define various socket options.
1.31 + * @{
1.32 + */
1.33 + /// The server socket will only respond to connections on the
1.34 + /// local loopback interface. Otherwise, it will accept connections
1.35 + /// from any interface. To specify a particular network interface,
1.36 + /// use initWithAddress.
1.37 + const nsServerSocketFlag LoopbackOnly = 0x00000001;
1.38 + /// The server socket will not be closed when Gecko is set
1.39 + /// offline.
1.40 + const nsServerSocketFlag KeepWhenOffline = 0x00000002;
1.41 + /** @} */
1.42 +
1.43 + /**
1.44 + * init
1.45 + *
1.46 + * This method initializes a server socket.
1.47 + *
1.48 + * @param aPort
1.49 + * The port of the server socket. Pass -1 to indicate no preference,
1.50 + * and a port will be selected automatically.
1.51 + * @param aLoopbackOnly
1.52 + * If true, the server socket will only respond to connections on the
1.53 + * local loopback interface. Otherwise, it will accept connections
1.54 + * from any interface. To specify a particular network interface,
1.55 + * use initWithAddress.
1.56 + * @param aBackLog
1.57 + * The maximum length the queue of pending connections may grow to.
1.58 + * This parameter may be silently limited by the operating system.
1.59 + * Pass -1 to use the default value.
1.60 + */
1.61 + void init(in long aPort,
1.62 + in boolean aLoopbackOnly,
1.63 + in long aBackLog);
1.64 +
1.65 + /**
1.66 + * initSpecialConnection
1.67 + *
1.68 + * This method initializes a server socket and offers the ability to have
1.69 + * that socket not get terminated if Gecko is set offline.
1.70 + *
1.71 + * @param aPort
1.72 + * The port of the server socket. Pass -1 to indicate no preference,
1.73 + * and a port will be selected automatically.
1.74 + * @param aFlags
1.75 + * Flags for the socket.
1.76 + * @param aBackLog
1.77 + * The maximum length the queue of pending connections may grow to.
1.78 + * This parameter may be silently limited by the operating system.
1.79 + * Pass -1 to use the default value.
1.80 + */
1.81 + void initSpecialConnection(in long aPort,
1.82 + in nsServerSocketFlag aFlags,
1.83 + in long aBackLog);
1.84 +
1.85 +
1.86 + /**
1.87 + * initWithAddress
1.88 + *
1.89 + * This method initializes a server socket, and binds it to a particular
1.90 + * local address (and hence a particular local network interface).
1.91 + *
1.92 + * @param aAddr
1.93 + * The address to which this server socket should be bound.
1.94 + * @param aBackLog
1.95 + * The maximum length the queue of pending connections may grow to.
1.96 + * This parameter may be silently limited by the operating system.
1.97 + * Pass -1 to use the default value.
1.98 + */
1.99 + [noscript] void initWithAddress([const] in PRNetAddrPtr aAddr, in long aBackLog);
1.100 +
1.101 + /**
1.102 + * initWithFilename
1.103 + *
1.104 + * This method initializes a Unix domain or "local" server socket. Such
1.105 + * a socket has a name in the filesystem, like an ordinary file. To
1.106 + * connect, a client supplies the socket's filename, and the usual
1.107 + * permission checks on socket apply.
1.108 + *
1.109 + * This makes Unix domain sockets useful for communication between the
1.110 + * programs being run by a specific user on a single machine: the
1.111 + * operating system takes care of authentication, and the user's home
1.112 + * directory or profile directory provide natural per-user rendezvous
1.113 + * points.
1.114 + *
1.115 + * Since Unix domain sockets are always local to the machine, they are
1.116 + * not affected by the nsIIOService's 'offline' flag.
1.117 + *
1.118 + * The system-level socket API may impose restrictions on the length of
1.119 + * the filename that are stricter than those of the underlying
1.120 + * filesystem. If the file name is too long, this returns
1.121 + * NS_ERROR_FILE_NAME_TOO_LONG.
1.122 + *
1.123 + * All components of the path prefix of |aPath| must name directories;
1.124 + * otherwise, this returns NS_ERROR_FILE_NOT_DIRECTORY.
1.125 + *
1.126 + * This call requires execute permission on all directories containing
1.127 + * the one in which the socket is to be created, and write and execute
1.128 + * permission on the directory itself. Otherwise, this returns
1.129 + * NS_ERROR_CONNECTION_REFUSED.
1.130 + *
1.131 + * This call creates the socket's directory entry. There must not be
1.132 + * any existing entry with the given name. If there is, this returns
1.133 + * NS_ERROR_SOCKET_ADDRESS_IN_USE.
1.134 + *
1.135 + * On systems that don't support Unix domain sockets at all, this
1.136 + * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
1.137 + *
1.138 + * @param aPath nsIFile
1.139 + * The file name at which the socket should be created.
1.140 + *
1.141 + * @param aPermissions unsigned long
1.142 + * Unix-style permission bits to be applied to the new socket.
1.143 + *
1.144 + * Note about permissions: Linux's unix(7) man page claims that some
1.145 + * BSD-derived systems ignore permissions on UNIX-domain sockets;
1.146 + * NetBSD's bind(2) man page agrees, but says it does check now (dated
1.147 + * 2005). POSIX has required 'connect' to fail if write permission on
1.148 + * the socket itself is not granted since 2003 (Issue 6). NetBSD says
1.149 + * that the permissions on the containing directory (execute) have
1.150 + * always applied, so creating sockets in appropriately protected
1.151 + * directories should be secure on both old and new systems.
1.152 + */
1.153 + void initWithFilename(in nsIFile aPath, in unsigned long aPermissions,
1.154 + in long aBacklog);
1.155 +
1.156 + /**
1.157 + * close
1.158 + *
1.159 + * This method closes a server socket. This does not affect already
1.160 + * connected client sockets (i.e., the nsISocketTransport instances
1.161 + * created from this server socket). This will cause the onStopListening
1.162 + * event to asynchronously fire with a status of NS_BINDING_ABORTED.
1.163 + */
1.164 + void close();
1.165 +
1.166 + /**
1.167 + * asyncListen
1.168 + *
1.169 + * This method puts the server socket in the listening state. It will
1.170 + * asynchronously listen for and accept client connections. The listener
1.171 + * will be notified once for each client connection that is accepted. The
1.172 + * listener's onSocketAccepted method will be called on the same thread
1.173 + * that called asyncListen (the calling thread must have a nsIEventTarget).
1.174 + *
1.175 + * The listener will be passed a reference to an already connected socket
1.176 + * transport (nsISocketTransport). See below for more details.
1.177 + *
1.178 + * @param aListener
1.179 + * The listener to be notified when client connections are accepted.
1.180 + */
1.181 + void asyncListen(in nsIServerSocketListener aListener);
1.182 +
1.183 + /**
1.184 + * Returns the port of this server socket.
1.185 + */
1.186 + readonly attribute long port;
1.187 +
1.188 + /**
1.189 + * Returns the address to which this server socket is bound. Since a
1.190 + * server socket may be bound to multiple network devices, this address
1.191 + * may not necessarily be specific to a single network device. In the
1.192 + * case of an IP socket, the IP address field would be zerod out to
1.193 + * indicate a server socket bound to all network devices. Therefore,
1.194 + * this method cannot be used to determine the IP address of the local
1.195 + * system. See nsIDNSService::myHostName if this is what you need.
1.196 + */
1.197 + [noscript] PRNetAddr getAddress();
1.198 +};
1.199 +
1.200 +/**
1.201 + * nsIServerSocketListener
1.202 + *
1.203 + * This interface is notified whenever a server socket accepts a new connection.
1.204 + * The transport is in the connected state, and read/write streams can be opened
1.205 + * using the normal nsITransport API. The address of the client can be found by
1.206 + * calling the nsISocketTransport::GetAddress method or by inspecting
1.207 + * nsISocketTransport::GetHost, which returns a string representation of the
1.208 + * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
1.209 + */
1.210 +[scriptable, uuid(836d98ec-fee2-4bde-b609-abd5e966eabd)]
1.211 +interface nsIServerSocketListener : nsISupports
1.212 +{
1.213 + /**
1.214 + * onSocketAccepted
1.215 + *
1.216 + * This method is called when a client connection is accepted.
1.217 + *
1.218 + * @param aServ
1.219 + * The server socket.
1.220 + * @param aTransport
1.221 + * The connected socket transport.
1.222 + */
1.223 + void onSocketAccepted(in nsIServerSocket aServ,
1.224 + in nsISocketTransport aTransport);
1.225 +
1.226 + /**
1.227 + * onStopListening
1.228 + *
1.229 + * This method is called when the listening socket stops for some reason.
1.230 + * The server socket is effectively dead after this notification.
1.231 + *
1.232 + * @param aServ
1.233 + * The server socket.
1.234 + * @param aStatus
1.235 + * The reason why the server socket stopped listening. If the
1.236 + * server socket was manually closed, then this value will be
1.237 + * NS_BINDING_ABORTED.
1.238 + */
1.239 + void onStopListening(in nsIServerSocket aServ, in nsresult aStatus);
1.240 +};
