The Tor Browser / file revision

 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */

 /* vim:set ts=4 sw=4 sts=4 et: */

 /* 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 nsICancelable;

 interface nsIProtocolProxyCallback;

 interface nsIProtocolProxyFilter;

 interface nsIProtocolProxyChannelFilter;

 interface nsIProxyInfo;

 interface nsIChannel;

 interface nsIURI;

 /**

  * nsIProtocolProxyService provides methods to access information about

  * various network proxies.

  */

 [scriptable, uuid(ab363090-c331-489f-aabb-7fe4481795b8)]

 interface nsIProtocolProxyService : nsISupports

 {

     /** Flag 1 << 0 is unused **/

     /**

      * When the proxy configuration is manual this flag may be passed to the

      * resolve and asyncResolve methods to request to prefer the SOCKS proxy

      * to HTTP ones.

      */

     const unsigned long RESOLVE_PREFER_SOCKS_PROXY = 1 << 1;

     /**

      * When the proxy configuration is manual this flag may be passed to the

      * resolve and asyncResolve methods to request to not analyze the uri's

      * scheme specific proxy. When this flag is set the main HTTP proxy is the

      * preferred one.

      *

      * NOTE: if RESOLVE_PREFER_SOCKS_PROXY is set then the SOCKS proxy is

      *       the preferred one.

      *

      * NOTE: if RESOLVE_PREFER_HTTPS_PROXY is set then the HTTPS proxy

      *       is the preferred one.

      */

     const unsigned long RESOLVE_IGNORE_URI_SCHEME = 1 << 2;

     /**

      * When the proxy configuration is manual this flag may be passed to the

      * resolve and asyncResolve methods to request to prefer the HTTPS proxy

      * to the others HTTP ones.

      *

      * NOTE: RESOLVE_PREFER_SOCKS_PROXY takes precedence over this flag.

      *

      * NOTE: This flag implies RESOLVE_IGNORE_URI_SCHEME.

      */

     const unsigned long RESOLVE_PREFER_HTTPS_PROXY =

         (1 << 3) | RESOLVE_IGNORE_URI_SCHEME;

     /**

      * When the proxy configuration is manual this flag may be passed to the

      * resolve and asyncResolve methods to that all methods will be tunneled via

      * CONNECT through the http proxy.

      */

     const unsigned long RESOLVE_ALWAYS_TUNNEL = (1 << 4);

     /**

      * This method returns via callback a nsIProxyInfo instance that identifies

      * a proxy to be used for the given channel.  Otherwise, this method returns

      * null indicating that a direct connection should be used.

      *

      * @param aChannel

      *        The channel for which a proxy is to be found.

      * @param aFlags

      *        A bit-wise combination of the RESOLVE_ flags defined above.  Pass

      *        0 to specify the default behavior.  Any additional bits that do

      *        not correspond to a RESOLVE_ flag are reserved for future use.

      * @param aCallback

      *        The object to be notified when the result is available.

      *

      * @return An object that can be used to cancel the asychronous operation.

      *         If canceled, the cancelation status (aReason) will be forwarded

      *         to the callback's onProxyAvailable method via the aStatus param.

      *

      * NOTE: If this proxy is unavailable, getFailoverForProxy may be called

      * to determine the correct secondary proxy to be used.

      *

      * NOTE: If the protocol handler for the given URI supports

      * nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from

      * resolve may be passed to the newProxiedChannel method to create a

      * nsIChannel to the given URI that uses the specified proxy.

      *

      * NOTE: However, if the nsIProxyInfo type is "http", then it means that

      * the given URI should be loaded using the HTTP protocol handler, which

      * also supports nsIProxiedProtocolHandler.

      *

      * @see nsIProxiedProtocolHandler::newProxiedChannel 

      */

     nsICancelable asyncResolve(in nsIChannel aChannel, in unsigned long aFlags,

                                in nsIProtocolProxyCallback aCallback);

     /**

      * This method may be called to construct a nsIProxyInfo instance from

      * the given parameters.  This method may be useful in conjunction with

      * nsISocketTransportService::createTransport for creating, for example,

      * a SOCKS connection.

      *

      * @param aType

      *        The proxy type.  This is a string value that identifies the proxy

      *        type.  Standard values include:

      *          "http"    - specifies a HTTP proxy

      *          "socks"   - specifies a SOCKS version 5 proxy

      *          "socks4"  - specifies a SOCKS version 4 proxy

      *          "direct"  - specifies a direct connection (useful for failover)

      *        The type name is case-insensitive.  Other string values may be

      *        possible, and new types may be defined by a future version of

      *        this interface.

      * @param aHost

      *        The proxy hostname or IP address.

      * @param aPort

      *        The proxy port.

      * @param aFlags

      *        Flags associated with this connection.  See nsIProxyInfo.idl

      *        for currently defined flags.

      * @param aFailoverTimeout

      *        Specifies the length of time (in seconds) to ignore this proxy if

      *        this proxy fails.  Pass UINT32_MAX to specify the default

      *        timeout value, causing nsIProxyInfo::failoverTimeout to be

      *        assigned the default value.

      * @param aFailoverProxy

      *        Specifies the next proxy to try if this proxy fails.  This

      *        parameter may be null.

      */

     nsIProxyInfo newProxyInfo(in ACString aType, in AUTF8String aHost,

                               in long aPort, in unsigned long aFlags,

                               in unsigned long aFailoverTimeout,

                               in nsIProxyInfo aFailoverProxy);

     /**

      * This method may be called to construct a nsIProxyInfo instance for

      * a SOCKS connection, with the specified username and password.

      * @param aHost

      *        The proxy hostname or IP address.

      * @param aPort

      *        The proxy port.

      * @param aUsername

      *        The SOCKS5 username

      * @param aPassword

      *        The SOCKS5 password

      * @param aFlags

      *        Flags associated with this connection.  See nsIProxyInfo.idl

      *        for currently defined flags.

      * @param aFailoverTimeout

      *        Specifies the length of time (in seconds) to ignore this proxy if

      *        this proxy fails.  Pass UINT32_MAX to specify the default

      *        timeout value, causing nsIProxyInfo::failoverTimeout to be

      *        assigned the default value.

      * @param aFailoverProxy

      *        Specifies the next proxy to try if this proxy fails.  This

      *        parameter may be null.

      */

     nsIProxyInfo newSOCKSProxyInfo(in AUTF8String aHost, in long aPort,

                                    in ACString aUsername, in ACString aPassword,

                                    in unsigned long aFlags,

                                    in unsigned long aFailoverTimeout,

                                    in nsIProxyInfo aFailoverProxy);

     /**

      * If the proxy identified by aProxyInfo is unavailable for some reason,

      * this method may be called to access an alternate proxy that may be used

      * instead.  As a side-effect, this method may affect future result values

      * from resolve/asyncResolve as well as from getFailoverForProxy.

      *

      * @param aProxyInfo

      *        The proxy that was unavailable.

      * @param aURI

      *        The URI that was originally passed to resolve/asyncResolve.

      * @param aReason

      *        The error code corresponding to the proxy failure.  This value

      *        may be used to tune the delay before this proxy is used again.

      *

      * @throw NS_ERROR_NOT_AVAILABLE if there is no alternate proxy available.

      */

     nsIProxyInfo getFailoverForProxy(in nsIProxyInfo aProxyInfo,

                                      in nsIURI       aURI,

                                      in nsresult     aReason);

     /**

      * This method may be used to register a proxy filter instance.  Each proxy

      * filter is registered with an associated position that determines the

      * order in which the filters are applied (starting from position 0).  When

      * resolve/asyncResolve is called, it generates a list of proxies for the

      * given URI, and then it applies the proxy filters.  The filters have the

      * opportunity to modify the list of proxies.

      *

      * If two filters register for the same position, then the filters will be

      * visited in the order in which they were registered.

      *

      * If the filter is already registered, then its position will be updated.

      *

      * After filters have been run, any disabled or disallowed proxies will be

      * removed from the list.  A proxy is disabled if it had previously failed-

      * over to another proxy (see getFailoverForProxy).  A proxy is disallowed,

      * for example, if it is a HTTP proxy and the nsIProtocolHandler for the

      * queried URI does not permit proxying via HTTP.

      *

      * If a nsIProtocolHandler disallows all proxying, then filters will never

      * have a chance to intercept proxy requests for such URLs.

      *

      * @param aFilter

      *        The nsIProtocolProxyFilter instance to be registered.

      * @param aPosition

      *        The position of the filter.

      *

      * NOTE: It is possible to construct filters that compete with one another

      * in undesirable ways.  This API does not attempt to protect against such

      * problems.  It is recommended that any extensions that choose to call

      * this method make their position value configurable at runtime (perhaps

      * via the preferences service).

      */

     void registerFilter(in nsIProtocolProxyFilter aFilter,

                         in unsigned long aPosition);

     /**

      * Similar to registerFilter, but accepts an nsIProtocolProxyChannelFilter,

      * which selects proxies according to channel rather than URI.

      *

      * @param aFilter

      *        The nsIProtocolProxyChannelFilter instance to be registered.

      * @param aPosition

      *        The position of the filter.

      */

     void registerChannelFilter(in nsIProtocolProxyChannelFilter aFilter,

                                in unsigned long aPosition);

     /**

      * This method may be used to unregister a proxy filter instance.  All

      * filters will be automatically unregistered at XPCOM shutdown.

      *

      * @param aFilter

      *        The nsIProtocolProxyFilter instance to be unregistered.

      */

     void unregisterFilter(in nsIProtocolProxyFilter aFilter);

     /**

      * This method may be used to unregister a proxy channel filter instance.  All

      * filters will be automatically unregistered at XPCOM shutdown.

      *

      * @param aFilter

      *        The nsIProtocolProxyChannelFilter instance to be unregistered.

      */

     void unregisterChannelFilter(in nsIProtocolProxyChannelFilter aFilter);

      /**

       * These values correspond to the possible integer values for the

       * network.proxy.type preference.

       */ 

      const unsigned long PROXYCONFIG_DIRECT   = 0;

      const unsigned long PROXYCONFIG_MANUAL   = 1;

      const unsigned long PROXYCONFIG_PAC      = 2;

      const unsigned long PROXYCONFIG_WPAD     = 4;

      const unsigned long PROXYCONFIG_SYSTEM   = 5;

      /**

       * This attribute specifies the current type of proxy configuration.

       */

      readonly attribute unsigned long proxyConfigType;

 };