Adding upstream version 86.0.1.upstream/86.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 296 insertions, 0 deletions

diff --git a/netwerk/base/nsIProtocolProxyService.idl b/netwerk/base/nsIProtocolProxyService.idl
new file mode 100644
index 0000000000..c07592d38a
--- /dev/null
+++ b/netwerk/base/nsIProtocolProxyService.idl
@@ -0,0 +1,296 @@
+/* -*- 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;
+};