gecko-dev/netwerk/base/nsIProtocolProxyService.idl

/* -*- 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;
interface nsISerialEventTarget;

/**
 * nsIProtocolProxyService provides methods to access information about
 * various network proxies.
 */
[scriptable, builtinclass, uuid(ef57c8b6-e09d-4cd4-9222-2a5d2402e15d)]
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 aChannelOrURI
     *        The channel for which a proxy is to be found, or, if no channel is
     *        available, a URI indicating the same. This method will return
     *        NS_ERROR_NOINTERFACE if this argument isn't either an nsIURI or an
     *        nsIChannel.
     * @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.
     * @param aMainThreadTarget
     *        A labelled event target for dispatching runnables to main thread.
     *
     * @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 nsISupports aChannelOrURI, in unsigned long aFlags,
        in nsIProtocolProxyCallback aCallback,
        [optional] in nsISerialEventTarget aMainThreadTarget);

    /**
     * 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
     *          "https"   - specifies HTTP proxying over TLS connection to 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 ACString aProxyAuthorizationHeader,
                              in ACString aConnectionIsolationKey,
                              in unsigned long aFlags,
                              in unsigned long aFailoverTimeout,
                              in nsIProxyInfo aFailoverProxy);

    /**
     * This method may be called to construct a nsIProxyInfo instance for
     * with the specified username and password.
     * Currently implemented for SOCKS proxies only.
     * @param aType
     *        The proxy type.  This is a string value that identifies the proxy
     *        type.  Standard values include:
     *          "socks"   - specifies a SOCKS version 5 proxy
     *          "socks4"  - specifies a SOCKS version 4 proxy
     *        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 aUsername
     *        The proxy username
     * @param aPassword
     *        The proxy 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 newProxyInfoWithAuth(in ACString aType, in AUTF8String aHost,
                                      in long aPort,
                                      in ACString aUsername, in ACString aPassword,
                                      in ACString aProxyAuthorizationHeader,
                                      in ACString aConnectionIsolationKey,
                                      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;

     /**
      * True if there is a PAC download in progress.
      */
    [notxpcom, nostdcall] readonly attribute boolean isPACLoading;
};