diff options
Diffstat (limited to 'netwerk/base/nsIProtocolProxyService.idl')
| -rw-r--r-- | netwerk/base/nsIProtocolProxyService.idl | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/netwerk/base/nsIProtocolProxyService.idl b/netwerk/base/nsIProtocolProxyService.idl new file mode 100644 index 0000000000..8463f7acd0 --- /dev/null +++ b/netwerk/base/nsIProtocolProxyService.idl @@ -0,0 +1,330 @@ +/* -*- 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; + +[scriptable, uuid(77984234-aad5-47fc-a412-03398c2134a5)] +interface nsIProxyConfigChangedCallback : nsISupports +{ + /** + * Called when one of the following conditions are changed. + * 1. System proxy settings changed. + * 2. A proxy filter is registered or unregistered. + * 3. Proxy related prefs changed. + */ + void onProxyConfigChanged(); +}; + +/** + * 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); + + /** + * This method is used to register a nsIProxyConfigChangedCallback. + * + * @param aCallback + * The aCallback instance to be registered. + */ + void addProxyConfigCallback(in nsIProxyConfigChangedCallback aCallback); + + /** + * This method is used to unregister a nsIProxyConfigChangedCallback. + * + * @param aCallback + * The aCallback instance to be unregistered. + */ + void removeProxyConfigCallback(in nsIProxyConfigChangedCallback aCallback); + + + /** + * This method is used internal only. Called when proxy config is changed. + */ + void notifyProxyConfigChangedInternal(); + + /** + * 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; +}; |