The Tor Browser: netwerk/base/public/nsIServerSocket.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIServerSocket.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIServerSocket.idl

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* 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);
     /**
      * 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);
 };

The Tor Browser / annotate

netwerk/base/public/nsIServerSocket.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIServerSocket.idl