michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIFile;
michael@0: interface nsISocketTransport;
michael@0: interface nsIProxyInfo;
michael@0: interface nsIRunnable;
michael@0: 
michael@0: %{C++
michael@0: class nsASocketHandler;
michael@0: struct PRFileDesc;
michael@0: %}
michael@0: 
michael@0: [ptr] native PRFileDescPtr(PRFileDesc);
michael@0: [ptr] native nsASocketHandlerPtr(nsASocketHandler);
michael@0: 
michael@0: [scriptable, uuid(ad56b25f-e6bb-4db3-9f7b-5b7db33fd2b1)]
michael@0: interface nsISocketTransportService : nsISupports 
michael@0: {
michael@0:     /**
michael@0:      * Creates a transport for a specified host and port.
michael@0:      *
michael@0:      * @param aSocketTypes
michael@0:      *        array of socket type strings.  null if using default socket type.
michael@0:      * @param aTypeCount
michael@0:      *        specifies length of aSocketTypes.
michael@0:      * @param aHost
michael@0:      *        specifies the target hostname or IP address literal of the peer
michael@0:      *        for this socket.
michael@0:      * @param aPort
michael@0:      *        specifies the target port of the peer for this socket.
michael@0:      * @param aProxyInfo
michael@0:      *        specifies the transport-layer proxy type to use.  null if no
michael@0:      *        proxy.  used for communicating information about proxies like
michael@0:      *        SOCKS (which are transparent to upper protocols).
michael@0:      *
michael@0:      * @see nsIProxiedProtocolHandler
michael@0:      * @see nsIProtocolProxyService::GetProxyInfo
michael@0:      *
michael@0:      * NOTE: this function can be called from any thread
michael@0:      */
michael@0:     nsISocketTransport createTransport([array, size_is(aTypeCount)]
michael@0:                                        in string aSocketTypes,
michael@0:                                        in unsigned long aTypeCount,
michael@0:                                        in AUTF8String aHost,
michael@0:                                        in long aPort,
michael@0:                                        in nsIProxyInfo aProxyInfo);
michael@0: 
michael@0:     /**
michael@0:      * Create a transport built on a Unix domain socket, connecting to the
michael@0:      * given filename.
michael@0:      *
michael@0:      * Since Unix domain sockets are always local to the machine, they are
michael@0:      * not affected by the nsIIOService's 'offline' flag.
michael@0:      *
michael@0:      * On systems that don't support Unix domain sockets at all, this
michael@0:      * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
michael@0:      *
michael@0:      * The system-level socket API may impose restrictions on the length of
michael@0:      * the filename that are stricter than those of the underlying
michael@0:      * filesystem. If the file name is too long, this returns
michael@0:      * NS_ERROR_FILE_NAME_TOO_LONG.
michael@0:      *
michael@0:      * The |aPath| parameter must specify an existing directory entry.
michael@0:      * Otherwise, this returns NS_ERROR_FILE_NOT_FOUND.
michael@0:      *
michael@0:      * The program must have search permission on all components of the
michael@0:      * path prefix of |aPath|, and read and write permission on |aPath|
michael@0:      * itself. Without such permission, this returns
michael@0:      * NS_ERROR_CONNECTION_REFUSED.
michael@0:      *
michael@0:      * The |aPath| parameter must refer to a unix-domain socket. Otherwise,
michael@0:      * this returns NS_ERROR_CONNECTION_REFUSED. (POSIX specifies
michael@0:      * ECONNREFUSED when "the target address was not listening for
michael@0:      * connections", and this is what Linux returns.)
michael@0:      *
michael@0:      * @param aPath
michael@0:      *        The file name of the Unix domain socket to which we should
michael@0:      *        connect.
michael@0:      */
michael@0:     nsISocketTransport createUnixDomainTransport(in nsIFile aPath);
michael@0: 
michael@0:     /**
michael@0:      * Adds a new socket to the list of controlled sockets.
michael@0:      *
michael@0:      * This will fail with the error code NS_ERROR_NOT_AVAILABLE if the maximum
michael@0:      * number of sockets is already reached.
michael@0:      * In this case, the notifyWhenCanAttachSocket method should be used.
michael@0:      *
michael@0:      * @param aFd
michael@0:      *        Open file descriptor of the socket to control.
michael@0:      * @param aHandler
michael@0:      *        Socket handler that will receive notifications when the socket is
michael@0:      *        ready or detached.
michael@0:      *
michael@0:      * NOTE: this function may only be called from an event dispatch on the
michael@0:      *       socket thread.
michael@0:      */
michael@0:     [noscript] void attachSocket(in PRFileDescPtr aFd,
michael@0:                                  in nsASocketHandlerPtr aHandler);
michael@0: 
michael@0:     /**
michael@0:      * if the number of sockets reaches the limit, then consumers can be
michael@0:      * notified when the number of sockets becomes less than the limit.  the
michael@0:      * notification is asynchronous, delivered via the given nsIRunnable
michael@0:      * instance on the socket transport thread.
michael@0:      *
michael@0:      * @param aEvent
michael@0:      *        Event that will receive the notification when a new socket can
michael@0:      *        be attached
michael@0:      *
michael@0:      * NOTE: this function may only be called from an event dispatch on the
michael@0:      *       socket thread.
michael@0:      */
michael@0:     [noscript] void notifyWhenCanAttachSocket(in nsIRunnable aEvent);
michael@0: };