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

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

netwerk/base/public/nsIProtocolProxyService.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

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

The Tor Browser / annotate

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

netwerk/base/public/nsIProtocolProxyService.idl