netwerk/base/nsIProtocolProxyService.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* vim:set ts=4 sw=4 sts=4 et: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsICancelable;
  10 interface nsIProtocolProxyCallback;
  11 interface nsIProtocolProxyFilter;
  12 interface nsIProtocolProxyChannelFilter;
  13 interface nsIProxyInfo;
  14 interface nsIChannel;
  15 interface nsIURI;
  16 interface nsISerialEventTarget;
  17
  18 [scriptable, uuid(77984234-aad5-47fc-a412-03398c2134a5)]
  19 interface nsIProxyConfigChangedCallback : nsISupports
  20 {
  21    /**
  22      * Called when one of the following conditions are changed.
  23      * 1. System proxy settings changed.
  24      * 2. A proxy filter is registered or unregistered.
  25      * 3. Proxy related prefs changed.
  26      */
  27   void onProxyConfigChanged();
  28 };
  29
  30 /**
  31  * nsIProtocolProxyService provides methods to access information about
  32  * various network proxies.
  33  */
  34 [scriptable, builtinclass, uuid(ef57c8b6-e09d-4cd4-9222-2a5d2402e15d)]
  35 interface nsIProtocolProxyService : nsISupports
  36 {
  37     /** Flag 1 << 0 is unused **/
  38
  39     /**
  40      * When the proxy configuration is manual this flag may be passed to the
  41      * resolve and asyncResolve methods to request to prefer the SOCKS proxy
  42      * to HTTP ones.
  43      */
  44     const unsigned long RESOLVE_PREFER_SOCKS_PROXY = 1 << 1;
  45
  46     /**
  47      * When the proxy configuration is manual this flag may be passed to the
  48      * resolve and asyncResolve methods to request to not analyze the uri's
  49      * scheme specific proxy. When this flag is set the main HTTP proxy is the
  50      * preferred one.
  51      *
  52      * NOTE: if RESOLVE_PREFER_SOCKS_PROXY is set then the SOCKS proxy is
  53      *       the preferred one.
  54      *
  55      * NOTE: if RESOLVE_PREFER_HTTPS_PROXY is set then the HTTPS proxy
  56      *       is the preferred one.
  57      */
  58     const unsigned long RESOLVE_IGNORE_URI_SCHEME = 1 << 2;
  59
  60     /**
  61      * When the proxy configuration is manual this flag may be passed to the
  62      * resolve and asyncResolve methods to request to prefer the HTTPS proxy
  63      * to the others HTTP ones.
  64      *
  65      * NOTE: RESOLVE_PREFER_SOCKS_PROXY takes precedence over this flag.
  66      *
  67      * NOTE: This flag implies RESOLVE_IGNORE_URI_SCHEME.
  68      */
  69     const unsigned long RESOLVE_PREFER_HTTPS_PROXY =
  70         (1 << 3) | RESOLVE_IGNORE_URI_SCHEME;
  71
  72     /**
  73      * When the proxy configuration is manual this flag may be passed to the
  74      * resolve and asyncResolve methods to that all methods will be tunneled via
  75      * CONNECT through the http proxy.
  76      */
  77     const unsigned long RESOLVE_ALWAYS_TUNNEL = (1 << 4);
  78
  79     /**
  80      * This method returns via callback a nsIProxyInfo instance that identifies
  81      * a proxy to be used for the given channel.  Otherwise, this method returns
  82      * null indicating that a direct connection should be used.
  83      *
  84      * @param aChannelOrURI
  85      *        The channel for which a proxy is to be found, or, if no channel is
  86      *        available, a URI indicating the same. This method will return
  87      *        NS_ERROR_NOINTERFACE if this argument isn't either an nsIURI or an
  88      *        nsIChannel.
  89      * @param aFlags
  90      *        A bit-wise combination of the RESOLVE_ flags defined above.  Pass
  91      *        0 to specify the default behavior.  Any additional bits that do
  92      *        not correspond to a RESOLVE_ flag are reserved for future use.
  93      * @param aCallback
  94      *        The object to be notified when the result is available.
  95      * @param aMainThreadTarget
  96      *        A labelled event target for dispatching runnables to main thread.
  97      *
  98      * @return An object that can be used to cancel the asychronous operation.
  99      *         If canceled, the cancelation status (aReason) will be forwarded
 100      *         to the callback's onProxyAvailable method via the aStatus param.
 101      *
 102      * NOTE: If this proxy is unavailable, getFailoverForProxy may be called
 103      * to determine the correct secondary proxy to be used.
 104      *
 105      * NOTE: If the protocol handler for the given URI supports
 106      * nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from
 107      * resolve may be passed to the newProxiedChannel method to create a
 108      * nsIChannel to the given URI that uses the specified proxy.
 109      *
 110      * NOTE: However, if the nsIProxyInfo type is "http", then it means that
 111      * the given URI should be loaded using the HTTP protocol handler, which
 112      * also supports nsIProxiedProtocolHandler.
 113      *
 114      * @see nsIProxiedProtocolHandler::newProxiedChannel
 115      */
 116     nsICancelable asyncResolve(
 117         in nsISupports aChannelOrURI, in unsigned long aFlags,
 118         in nsIProtocolProxyCallback aCallback,
 119         [optional] in nsISerialEventTarget aMainThreadTarget);
 120
 121     /**
 122      * This method may be called to construct a nsIProxyInfo instance from
 123      * the given parameters.  This method may be useful in conjunction with
 124      * nsISocketTransportService::createTransport for creating, for example,
 125      * a SOCKS connection.
 126      *
 127      * @param aType
 128      *        The proxy type.  This is a string value that identifies the proxy
 129      *        type.  Standard values include:
 130      *          "http"    - specifies a HTTP proxy
 131      *          "https"   - specifies HTTP proxying over TLS connection to proxy
 132      *          "socks"   - specifies a SOCKS version 5 proxy
 133      *          "socks4"  - specifies a SOCKS version 4 proxy
 134      *          "direct"  - specifies a direct connection (useful for failover)
 135      *        The type name is case-insensitive.  Other string values may be
 136      *        possible, and new types may be defined by a future version of
 137      *        this interface.
 138      * @param aHost
 139      *        The proxy hostname or IP address.
 140      * @param aPort
 141      *        The proxy port.
 142      * @param aFlags
 143      *        Flags associated with this connection.  See nsIProxyInfo.idl
 144      *        for currently defined flags.
 145      * @param aFailoverTimeout
 146      *        Specifies the length of time (in seconds) to ignore this proxy if
 147      *        this proxy fails.  Pass UINT32_MAX to specify the default
 148      *        timeout value, causing nsIProxyInfo::failoverTimeout to be
 149      *        assigned the default value.
 150      * @param aFailoverProxy
 151      *        Specifies the next proxy to try if this proxy fails.  This
 152      *        parameter may be null.
 153      */
 154     nsIProxyInfo newProxyInfo(in ACString aType, in AUTF8String aHost,
 155                               in long aPort,
 156                               in ACString aProxyAuthorizationHeader,
 157                               in ACString aConnectionIsolationKey,
 158                               in unsigned long aFlags,
 159                               in unsigned long aFailoverTimeout,
 160                               in nsIProxyInfo aFailoverProxy);
 161
 162     /**
 163      * This method may be called to construct a nsIProxyInfo instance for
 164      * with the specified username and password.
 165      * Currently implemented for SOCKS proxies only.
 166      * @param aType
 167      *        The proxy type.  This is a string value that identifies the proxy
 168      *        type.  Standard values include:
 169      *          "socks"   - specifies a SOCKS version 5 proxy
 170      *          "socks4"  - specifies a SOCKS version 4 proxy
 171      *        The type name is case-insensitive.  Other string values may be
 172      *        possible, and new types may be defined by a future version of
 173      *        this interface.
 174      * @param aHost
 175      *        The proxy hostname or IP address.
 176      * @param aPort
 177      *        The proxy port.
 178      * @param aUsername
 179      *        The proxy username
 180      * @param aPassword
 181      *        The proxy password
 182      * @param aFlags
 183      *        Flags associated with this connection.  See nsIProxyInfo.idl
 184      *        for currently defined flags.
 185      * @param aFailoverTimeout
 186      *        Specifies the length of time (in seconds) to ignore this proxy if
 187      *        this proxy fails.  Pass UINT32_MAX to specify the default
 188      *        timeout value, causing nsIProxyInfo::failoverTimeout to be
 189      *        assigned the default value.
 190      * @param aFailoverProxy
 191      *        Specifies the next proxy to try if this proxy fails.  This
 192      *        parameter may be null.
 193      */
 194     nsIProxyInfo newProxyInfoWithAuth(in ACString aType, in AUTF8String aHost,
 195                                       in long aPort,
 196                                       in AUTF8String aUsername, in AUTF8String aPassword,
 197                                       in ACString aProxyAuthorizationHeader,
 198                                       in ACString aConnectionIsolationKey,
 199                                       in unsigned long aFlags,
 200                                       in unsigned long aFailoverTimeout,
 201                                       in nsIProxyInfo aFailoverProxy);
 202
 203     /**
 204      * If the proxy identified by aProxyInfo is unavailable for some reason,
 205      * this method may be called to access an alternate proxy that may be used
 206      * instead.  As a side-effect, this method may affect future result values
 207      * from resolve/asyncResolve as well as from getFailoverForProxy.
 208      *
 209      * @param aProxyInfo
 210      *        The proxy that was unavailable.
 211      * @param aURI
 212      *        The URI that was originally passed to resolve/asyncResolve.
 213      * @param aReason
 214      *        The error code corresponding to the proxy failure.  This value
 215      *        may be used to tune the delay before this proxy is used again.
 216      *
 217      * @throw NS_ERROR_NOT_AVAILABLE if there is no alternate proxy available.
 218      */
 219     nsIProxyInfo getFailoverForProxy(in nsIProxyInfo aProxyInfo,
 220                                      in nsIURI       aURI,
 221                                      in nsresult     aReason);
 222
 223     /**
 224      * This method may be used to register a proxy filter instance.  Each proxy
 225      * filter is registered with an associated position that determines the
 226      * order in which the filters are applied (starting from position 0).  When
 227      * resolve/asyncResolve is called, it generates a list of proxies for the
 228      * given URI, and then it applies the proxy filters.  The filters have the
 229      * opportunity to modify the list of proxies.
 230      *
 231      * If two filters register for the same position, then the filters will be
 232      * visited in the order in which they were registered.
 233      *
 234      * If the filter is already registered, then its position will be updated.
 235      *
 236      * After filters have been run, any disabled or disallowed proxies will be
 237      * removed from the list.  A proxy is disabled if it had previously failed-
 238      * over to another proxy (see getFailoverForProxy).  A proxy is disallowed,
 239      * for example, if it is a HTTP proxy and the nsIProtocolHandler for the
 240      * queried URI does not permit proxying via HTTP.
 241      *
 242      * If a nsIProtocolHandler disallows all proxying, then filters will never
 243      * have a chance to intercept proxy requests for such URLs.
 244      *
 245      * @param aFilter
 246      *        The nsIProtocolProxyFilter instance to be registered.
 247      * @param aPosition
 248      *        The position of the filter.
 249      *
 250      * NOTE: It is possible to construct filters that compete with one another
 251      * in undesirable ways.  This API does not attempt to protect against such
 252      * problems.  It is recommended that any extensions that choose to call
 253      * this method make their position value configurable at runtime (perhaps
 254      * via the preferences service).
 255      */
 256     void registerFilter(in nsIProtocolProxyFilter aFilter,
 257                         in unsigned long aPosition);
 258
 259     /**
 260      * Similar to registerFilter, but accepts an nsIProtocolProxyChannelFilter,
 261      * which selects proxies according to channel rather than URI.
 262      *
 263      * @param aFilter
 264      *        The nsIProtocolProxyChannelFilter instance to be registered.
 265      * @param aPosition
 266      *        The position of the filter.
 267      */
 268     void registerChannelFilter(in nsIProtocolProxyChannelFilter aFilter,
 269                                in unsigned long aPosition);
 270
 271     /**
 272      * This method may be used to unregister a proxy filter instance.  All
 273      * filters will be automatically unregistered at XPCOM shutdown.
 274      *
 275      * @param aFilter
 276      *        The nsIProtocolProxyFilter instance to be unregistered.
 277      */
 278     void unregisterFilter(in nsIProtocolProxyFilter aFilter);
 279
 280     /**
 281      * This method may be used to unregister a proxy channel filter instance.  All
 282      * filters will be automatically unregistered at XPCOM shutdown.
 283      *
 284      * @param aFilter
 285      *        The nsIProtocolProxyChannelFilter instance to be unregistered.
 286      */
 287     void unregisterChannelFilter(in nsIProtocolProxyChannelFilter aFilter);
 288
 289     /**
 290      * This method is used to register a nsIProxyConfigChangedCallback.
 291      *
 292      * @param aCallback
 293      *        The aCallback instance to be registered.
 294      */
 295     void addProxyConfigCallback(in nsIProxyConfigChangedCallback aCallback);
 296
 297     /**
 298      * This method is used to unregister a nsIProxyConfigChangedCallback.
 299      *
 300      * @param aCallback
 301      *        The aCallback instance to be unregistered.
 302      */
 303     void removeProxyConfigCallback(in nsIProxyConfigChangedCallback aCallback);
 304
 305
 306     /**
 307      * This method is used internal only. Called when proxy config is changed.
 308      */
 309     void notifyProxyConfigChangedInternal();
 310
 311      /**
 312       * These values correspond to the possible integer values for the
 313       * network.proxy.type preference.
 314       */
 315      const unsigned long PROXYCONFIG_DIRECT   = 0;
 316      const unsigned long PROXYCONFIG_MANUAL   = 1;
 317      const unsigned long PROXYCONFIG_PAC      = 2;
 318      const unsigned long PROXYCONFIG_WPAD     = 4;
 319      const unsigned long PROXYCONFIG_SYSTEM   = 5;
 320
 321      /**
 322       * This attribute specifies the current type of proxy configuration.
 323       */
 324      readonly attribute unsigned long proxyConfigType;
 325
 326      /**
 327       * True if there is a PAC download in progress.
 328       */
 329     [notxpcom, nostdcall] readonly attribute boolean isPACLoading;
 330 };