netwerk/base/nsIServerSocket.idl

   1 /* vim:set ts=4 sw=4 et cindent: */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIFile;
   9 interface nsIServerSocketListener;
  10 interface nsISocketTransport;
  11
  12 native PRNetAddr(union PRNetAddr);
  13 [ptr] native PRNetAddrPtr(union PRNetAddr);
  14
  15 typedef unsigned long nsServerSocketFlag;
  16
  17 /**
  18  * nsIServerSocket
  19  *
  20  * An interface to a server socket that can accept incoming connections.
  21  */
  22 [scriptable, builtinclass, uuid(7a9c39cb-a13f-4eef-9bdf-a74301628742)]
  23 interface nsIServerSocket : nsISupports
  24 {
  25     /**
  26      * @name Server Socket Flags
  27      * These flags define various socket options.
  28      * @{
  29      */
  30     /// The server socket will only respond to connections on the
  31     /// local loopback interface.  Otherwise, it will accept connections
  32     /// from any interface.  To specify a particular network interface,
  33     /// use initWithAddress.
  34     const nsServerSocketFlag LoopbackOnly = 0x00000001;
  35     /// The server socket will not be closed when Gecko is set
  36     /// offline.
  37     const nsServerSocketFlag KeepWhenOffline = 0x00000002;
  38     /** @} */
  39
  40     /**
  41      * init
  42      *
  43      * This method initializes a server socket.
  44      *
  45      * @param aPort
  46      *        The port of the server socket.  Pass -1 to indicate no preference,
  47      *        and a port will be selected automatically.
  48      * @param aLoopbackOnly
  49      *        If true, the server socket will only respond to connections on the
  50      *        local loopback interface.  Otherwise, it will accept connections
  51      *        from any interface.  To specify a particular network interface,
  52      *        use initWithAddress.
  53      * @param aBackLog
  54      *        The maximum length the queue of pending connections may grow to.
  55      *        This parameter may be silently limited by the operating system.
  56      *        Pass -1 to use the default value.
  57      */
  58     void init(in long aPort,
  59               in boolean aLoopbackOnly,
  60               in long aBackLog);
  61
  62     /**
  63      * the same as init(), but initializes an IPv6 server socket
  64      */
  65     void initIPv6(in long aPort,
  66                   in boolean aLoopbackOnly,
  67                   in long aBackLog);
  68
  69     /**
  70      * Similar to init(), but initializes a server socket that supports
  71      * both IPv4 and IPv6.
  72      */
  73     void initDualStack(in long aPort,
  74                        in long aBackLog);
  75
  76     /**
  77      * initSpecialConnection
  78      *
  79      * This method initializes a server socket and offers the ability to have
  80      * that socket not get terminated if Gecko is set offline.
  81      *
  82      * @param aPort
  83      *        The port of the server socket.  Pass -1 to indicate no preference,
  84      *        and a port will be selected automatically.
  85      * @param aFlags
  86      *        Flags for the socket.
  87      * @param aBackLog
  88      *        The maximum length the queue of pending connections may grow to.
  89      *        This parameter may be silently limited by the operating system.
  90      *        Pass -1 to use the default value.
  91      */
  92     void initSpecialConnection(in long aPort,
  93                                in nsServerSocketFlag aFlags,
  94                                in long aBackLog);
  95
  96
  97     /**
  98      * initWithAddress
  99      *
 100      * This method initializes a server socket, and binds it to a particular
 101      * local address (and hence a particular local network interface).
 102      *
 103      * @param aAddr
 104      *        The address to which this server socket should be bound.
 105      * @param aBackLog
 106      *        The maximum length the queue of pending connections may grow to.
 107      *        This parameter may be silently limited by the operating system.
 108      *        Pass -1 to use the default value.
 109      */
 110     [noscript] void initWithAddress([const] in PRNetAddrPtr aAddr, in long aBackLog);
 111
 112     /**
 113      * initWithFilename
 114      *
 115      * This method initializes a Unix domain or "local" server socket. Such
 116      * a socket has a name in the filesystem, like an ordinary file. To
 117      * connect, a client supplies the socket's filename, and the usual
 118      * permission checks on socket apply.
 119      *
 120      * This makes Unix domain sockets useful for communication between the
 121      * programs being run by a specific user on a single machine: the
 122      * operating system takes care of authentication, and the user's home
 123      * directory or profile directory provide natural per-user rendezvous
 124      * points.
 125      *
 126      * Since Unix domain sockets are always local to the machine, they are
 127      * not affected by the nsIIOService's 'offline' flag.
 128      *
 129      * The system-level socket API may impose restrictions on the length of
 130      * the filename that are stricter than those of the underlying
 131      * filesystem. If the file name is too long, this returns
 132      * NS_ERROR_FILE_NAME_TOO_LONG.
 133      *
 134      * All components of the path prefix of |aPath| must name directories;
 135      * otherwise, this returns NS_ERROR_FILE_NOT_DIRECTORY.
 136      *
 137      * This call requires execute permission on all directories containing
 138      * the one in which the socket is to be created, and write and execute
 139      * permission on the directory itself. Otherwise, this returns
 140      * NS_ERROR_CONNECTION_REFUSED.
 141      *
 142      * This call creates the socket's directory entry. There must not be
 143      * any existing entry with the given name. If there is, this returns
 144      * NS_ERROR_SOCKET_ADDRESS_IN_USE.
 145      *
 146      * On systems that don't support Unix domain sockets at all, this
 147      * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
 148      *
 149      * @param aPath nsIFile
 150      *        The file name at which the socket should be created.
 151      *
 152      * @param aPermissions unsigned long
 153      *        Unix-style permission bits to be applied to the new socket.
 154      *
 155      * Note about permissions: Linux's unix(7) man page claims that some
 156      * BSD-derived systems ignore permissions on UNIX-domain sockets;
 157      * NetBSD's bind(2) man page agrees, but says it does check now (dated
 158      * 2005). POSIX has required 'connect' to fail if write permission on
 159      * the socket itself is not granted since 2003 (Issue 6). NetBSD says
 160      * that the permissions on the containing directory (execute) have
 161      * always applied, so creating sockets in appropriately protected
 162      * directories should be secure on both old and new systems.
 163      */
 164     void initWithFilename(in nsIFile aPath, in unsigned long aPermissions,
 165                           in long aBacklog);
 166
 167     /**
 168      * initWithAbstractAddress
 169      *
 170      * This mehtod is a flavor of initWithFilename method. This initializes
 171      * a UNIX domain socket that uses abstract socket address.
 172      * This socket type is only supported on Linux and Android.
 173      *
 174      * On systems that don't support this type's UNIX domain sockets at all,
 175      * this returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
 176      *
 177      * @param aName
 178      *        The abstract socket address which the socket should be created.
 179      * @param aBacklog
 180      *        The maximum length the queue of pending connections may grow to.
 181      */
 182     void initWithAbstractAddress(in AUTF8String aName,
 183                                  in long aBacklog);
 184
 185     /**
 186      * close
 187      *
 188      * This method closes a server socket.  This does not affect already
 189      * connected client sockets (i.e., the nsISocketTransport instances
 190      * created from this server socket).  This will cause the onStopListening
 191      * event to asynchronously fire with a status of NS_BINDING_ABORTED.
 192      */
 193     void close();
 194
 195     /**
 196      * asyncListen
 197      *
 198      * This method puts the server socket in the listening state.  It will
 199      * asynchronously listen for and accept client connections.  The listener
 200      * will be notified once for each client connection that is accepted.  The
 201      * listener's onSocketAccepted method will be called on the same thread
 202      * that called asyncListen (the calling thread must have a nsIEventTarget).
 203      *
 204      * The listener will be passed a reference to an already connected socket
 205      * transport (nsISocketTransport).  See below for more details.
 206      *
 207      * @param aListener
 208      *        The listener to be notified when client connections are accepted.
 209      */
 210     void asyncListen(in nsIServerSocketListener aListener);
 211
 212     /**
 213      * Returns the port of this server socket.
 214      */
 215     readonly attribute long port;
 216
 217     /**
 218      * Returns the address to which this server socket is bound.  Since a
 219      * server socket may be bound to multiple network devices, this address
 220      * may not necessarily be specific to a single network device.  In the
 221      * case of an IP socket, the IP address field would be zerod out to
 222      * indicate a server socket bound to all network devices.  Therefore,
 223      * this method cannot be used to determine the IP address of the local
 224      * system.  See nsIDNSService::myHostName if this is what you need.
 225      */
 226     [noscript] PRNetAddr getAddress();
 227 };
 228
 229 /**
 230  * nsIServerSocketListener
 231  *
 232  * This interface is notified whenever a server socket accepts a new connection.
 233  * The transport is in the connected state, and read/write streams can be opened
 234  * using the normal nsITransport API.  The address of the client can be found by
 235  * calling the nsISocketTransport::GetAddress method or by inspecting
 236  * nsISocketTransport::GetHost, which returns a string representation of the
 237  * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
 238  */
 239 [scriptable, uuid(836d98ec-fee2-4bde-b609-abd5e966eabd)]
 240 interface nsIServerSocketListener : nsISupports
 241 {
 242     /**
 243      * onSocketAccepted
 244      *
 245      * This method is called when a client connection is accepted.
 246      *
 247      * @param aServ
 248      *        The server socket.
 249      * @param aTransport
 250      *        The connected socket transport.
 251      */
 252     void onSocketAccepted(in nsIServerSocket aServ,
 253                           in nsISocketTransport aTransport);
 254
 255     /**
 256      * onStopListening
 257      *
 258      * This method is called when the listening socket stops for some reason.
 259      * The server socket is effectively dead after this notification.
 260      *
 261      * @param aServ
 262      *        The server socket.
 263      * @param aStatus
 264      *        The reason why the server socket stopped listening.  If the
 265      *        server socket was manually closed, then this value will be
 266      *        NS_BINDING_ABORTED.
 267      */
 268     void onStopListening(in nsIServerSocket aServ, in nsresult aStatus);
 269 };