netwerk/base/nsISocketTransportService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   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 nsIDNSRecord;
   9 interface nsIFile;
  10 interface nsISocketTransport;
  11 interface nsIProxyInfo;
  12 interface nsIRunnable;
  13
  14 %{C++
  15 class nsASocketHandler;
  16 struct PRFileDesc;
  17 %}
  18
  19 [ptr] native PRFileDescPtr(PRFileDesc);
  20 [ptr] native nsASocketHandlerPtr(nsASocketHandler);
  21
  22 [scriptable, function, uuid(338947df-2f3b-4d24-9ce4-ecf161c1b7df)]
  23 interface nsISTSShutdownObserver : nsISupports {
  24
  25    /**
  26     * Observe will be called when the SocketTransportService is shutting down,
  27     * before threads are stopped.
  28     */
  29     void observe();
  30 };
  31
  32 [builtinclass, scriptable, uuid(ad56b25f-e6bb-4db3-9f7b-5b7db33fd2b1)]
  33 interface nsISocketTransportService : nsISupports
  34 {
  35     /**
  36      * Creates a transport for a specified host and port.
  37      *
  38      * @param aSocketTypes
  39      *        array of socket type strings.  Empty array if using default
  40      *        socket type.
  41      * @param aHost
  42      *        specifies the target hostname or IP address literal of the peer
  43      *        for this socket.
  44      * @param aPort
  45      *        specifies the target port of the peer for this socket.
  46      * @param aProxyInfo
  47      *        specifies the transport-layer proxy type to use.  null if no
  48      *        proxy.  used for communicating information about proxies like
  49      *        SOCKS (which are transparent to upper protocols).
  50      * @param aDnsRecord
  51      *        the dns record to be used for the connection
  52      *
  53      * @see nsIProxiedProtocolHandler
  54      * @see nsIProtocolProxyService::GetProxyInfo
  55      *
  56      * NOTE: this function can be called from any thread
  57      */
  58     nsISocketTransport createTransport(in Array<ACString> aSocketTypes,
  59                                        in AUTF8String aHost,
  60                                        in long aPort,
  61                                        in nsIProxyInfo aProxyInfo,
  62                                        in nsIDNSRecord dnsRecord);
  63
  64     /**
  65      * Create a transport built on a Unix domain socket, connecting to the
  66      * given filename.
  67      *
  68      * Since Unix domain sockets are always local to the machine, they are
  69      * not affected by the nsIIOService's 'offline' flag.
  70      *
  71      * On systems that don't support Unix domain sockets at all, this
  72      * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
  73      *
  74      * The system-level socket API may impose restrictions on the length of
  75      * the filename that are stricter than those of the underlying
  76      * filesystem. If the file name is too long, this returns
  77      * NS_ERROR_FILE_NAME_TOO_LONG.
  78      *
  79      * The |aPath| parameter must specify an existing directory entry.
  80      * Otherwise, this returns NS_ERROR_FILE_NOT_FOUND.
  81      *
  82      * The program must have search permission on all components of the
  83      * path prefix of |aPath|, and read and write permission on |aPath|
  84      * itself. Without such permission, this returns
  85      * NS_ERROR_CONNECTION_REFUSED.
  86      *
  87      * The |aPath| parameter must refer to a unix-domain socket. Otherwise,
  88      * this returns NS_ERROR_CONNECTION_REFUSED. (POSIX specifies
  89      * ECONNREFUSED when "the target address was not listening for
  90      * connections", and this is what Linux returns.)
  91      *
  92      * @param aPath
  93      *        The file name of the Unix domain socket to which we should
  94      *        connect.
  95      */
  96     nsISocketTransport createUnixDomainTransport(in nsIFile aPath);
  97
  98     /**
  99      * Create a transport built on a Unix domain socket that uses abstract
 100      * address name.
 101      *
 102      * If abstract socket address isn't supported on System, this returns
 103      * NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
 104      *
 105      * @param aName
 106      *        The name of abstract socket adress of the Unix domain socket to
 107      *        which we should connect.
 108      */
 109     nsISocketTransport
 110     createUnixDomainAbstractAddressTransport(in ACString aName);
 111
 112     /**
 113      * Adds a new socket to the list of controlled sockets.
 114      *
 115      * This will fail with the error code NS_ERROR_NOT_AVAILABLE if the maximum
 116      * number of sockets is already reached.
 117      * In this case, the notifyWhenCanAttachSocket method should be used.
 118      *
 119      * @param aFd
 120      *        Open file descriptor of the socket to control.
 121      * @param aHandler
 122      *        Socket handler that will receive notifications when the socket is
 123      *        ready or detached.
 124      *
 125      * NOTE: this function may only be called from an event dispatch on the
 126      *       socket thread.
 127      */
 128     [noscript] void attachSocket(in PRFileDescPtr aFd,
 129                                  in nsASocketHandlerPtr aHandler);
 130
 131     /**
 132      * if the number of sockets reaches the limit, then consumers can be
 133      * notified when the number of sockets becomes less than the limit.  the
 134      * notification is asynchronous, delivered via the given nsIRunnable
 135      * instance on the socket transport thread.
 136      *
 137      * @param aEvent
 138      *        Event that will receive the notification when a new socket can
 139      *        be attached
 140      *
 141      * NOTE: this function may only be called from an event dispatch on the
 142      *       socket thread.
 143      */
 144     [noscript] void notifyWhenCanAttachSocket(in nsIRunnable aEvent);
 145
 146     [noscript] void addShutdownObserver(in nsISTSShutdownObserver aObserver);
 147     [noscript] void removeShutdownObserver(in nsISTSShutdownObserver aObserver);
 148 };
 149
 150 [builtinclass, scriptable, uuid(c5204623-5b58-4a16-8b2e-67c34dd02e3f)]
 151 interface nsIRoutedSocketTransportService : nsISocketTransportService
 152 {
 153     // use this instead of createTransport when you have a transport
 154     // that distinguishes between origin and route (aka connection)
 155     nsISocketTransport createRoutedTransport(in Array<ACString> aSocketTypes,
 156                                              in AUTF8String aHost, // origin
 157                                              in long aPort, // origin
 158                                              in AUTF8String aHostRoute,
 159                                              in long aPortRoute,
 160                                              in nsIProxyInfo aProxyInfo,
 161                                              in nsIDNSRecord aDnsRecord);
 162 };