netwerk/base/public/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 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is mozilla.org code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1998
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Darin Fisher <darin@meer.net>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 interface nsICancelable;
  43 interface nsIProtocolProxyCallback;
  44 interface nsIProtocolProxyFilter;
  45 interface nsIProxyInfo;
  46 interface nsIChannel;
  47 interface nsIURI;
  48
  49 /**
  50  * nsIProtocolProxyService provides methods to access information about
  51  * various network proxies.
  52  *
  53  * @status UNDER_REVIEW
  54  */
  55 [scriptable, uuid(e38ab577-786e-4a7f-936b-7ae4c7d877b2)]
  56 interface nsIProtocolProxyService : nsISupports
  57 {
  58     /**
  59      * This flag may be passed to the resolve method to request that it fail
  60      * instead of block the calling thread.  Proxy Auto Config (PAC) may
  61      * perform a synchronous DNS query, which may not return immediately.  So,
  62      * calling resolve without this flag may result in locking up the calling
  63      * thread for a lengthy period of time.
  64      *
  65      * By passing this flag to resolve, one can failover to asyncResolve to
  66      * avoid locking up the calling thread if a PAC query is required.
  67      *
  68      * When this flag is passed to resolve, resolve may throw the exception
  69      * NS_BASE_STREAM_WOULD_BLOCK to indicate that it failed due to this flag
  70      * being present.
  71      */
  72     const unsigned long RESOLVE_NON_BLOCKING = 1 << 0;
  73
  74     /**
  75      * This method returns a nsIProxyInfo instance that identifies a proxy to
  76      * be used for loading the given URI.  Otherwise, this method returns null
  77      * indicating that a direct connection should be used.
  78      *
  79      * @param aURI
  80      *        The URI to test.
  81      * @param aFlags
  82      *        A bit-wise combination of the RESOLVE_ flags defined above.  Pass
  83      *        0 to specify the default behavior.  Any additional bits that do
  84      *        not correspond to a RESOLVE_ flag are reserved for future use.
  85      *
  86      * NOTE: If this proxy is unavailable, getFailoverForProxy may be called
  87      * to determine the correct secondary proxy to be used.
  88      *
  89      * NOTE: If the protocol handler for the given URI supports
  90      * nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from
  91      * resolve may be passed to the newProxiedChannel method to create a
  92      * nsIChannel to the given URI that uses the specified proxy.
  93      *
  94      * NOTE: However, if the nsIProxyInfo type is "http", then it means that
  95      * the given URI should be loaded using the HTTP protocol handler, which
  96      * also supports nsIProxiedProtocolHandler.
  97      *
  98      * NOTE: If PAC is configured, and the PAC file has not yet been loaded,
  99      * then this method will return a nsIProxyInfo instance with a type of
 100      * "unknown" to indicate to the consumer that asyncResolve should be used
 101      * to wait for the PAC file to finish loading.  Otherwise, the consumer
 102      * may choose to treat the result as type "direct" if desired.
 103      *
 104      * @see nsIProxiedProtocolHandler::newProxiedChannel
 105      */
 106     nsIProxyInfo resolve(in nsIURI aURI, in unsigned long aFlags);
 107
 108     /**
 109      * This method is an asychronous version of the resolve method.  Unlike
 110      * resolve, this method is guaranteed not to block the calling thread
 111      * waiting for DNS queries to complete.  This method is intended as a
 112      * substitute for resolve when the result is not needed immediately.
 113      *
 114      * @param aURI
 115      *        The URI to test.
 116      * @param aFlags
 117      *        A bit-wise combination of the RESOLVE_ flags defined above.  Pass
 118      *        0 to specify the default behavior.  Any additional bits that do
 119      *        not correspond to a RESOLVE_ flag are reserved for future use.
 120      * @param aCallback
 121      *        The object to be notified when the result is available.
 122      *
 123      * @return An object that can be used to cancel the asychronous operation.
 124      *         If canceled, the cancelation status (aReason) will be forwarded
 125      *         to the callback's onProxyAvailable method via the aStatus param.
 126      */
 127     nsICancelable asyncResolve(in nsIURI aURI, in unsigned long aFlags,
 128                                in nsIProtocolProxyCallback aCallback);
 129
 130     /**
 131      * This method may be called to construct a nsIProxyInfo instance from
 132      * the given parameters.  This method may be useful in conjunction with
 133      * nsISocketTransportService::createTransport for creating, for example,
 134      * a SOCKS connection.
 135      *
 136      * @param aType
 137      *        The proxy type.  This is a string value that identifies the proxy
 138      *        type.  Standard values include:
 139      *          "http"    - specifies a HTTP proxy
 140      *          "socks"   - specifies a SOCKS version 5 proxy
 141      *          "socks4"  - specifies a SOCKS version 4 proxy
 142      *          "direct"  - specifies a direct connection (useful for failover)
 143      *        The type name is case-insensitive.  Other string values may be
 144      *        possible, and new types may be defined by a future version of
 145      *        this interface.
 146      * @param aHost
 147      *        The proxy hostname or IP address.
 148      * @param aPort
 149      *        The proxy port.
 150      * @param aFlags
 151      *        Flags associated with this connection.  See nsIProxyInfo.idl
 152      *        for currently defined flags.
 153      * @param aFailoverTimeout
 154      *        Specifies the length of time (in seconds) to ignore this proxy if
 155      *        this proxy fails.  Pass PR_UINT32_MAX to specify the default
 156      *        timeout value, causing nsIProxyInfo::failoverTimeout to be
 157      *        assigned the default value.
 158      * @param aFailoverProxy
 159      *        Specifies the next proxy to try if this proxy fails.  This
 160      *        parameter may be null.
 161      */
 162     nsIProxyInfo newProxyInfo(in ACString aType, in AUTF8String aHost,
 163                               in long aPort, in unsigned long aFlags,
 164                               in unsigned long aFailoverTimeout,
 165                               in nsIProxyInfo aFailoverProxy);
 166
 167     /**
 168      * If the proxy identified by aProxyInfo is unavailable for some reason,
 169      * this method may be called to access an alternate proxy that may be used
 170      * instead.  As a side-effect, this method may affect future result values
 171      * from resolve/asyncResolve as well as from getFailoverForProxy.
 172      *
 173      * @param aProxyInfo
 174      *        The proxy that was unavailable.
 175      * @param aURI
 176      *        The URI that was originally passed to resolve/asyncResolve.
 177      * @param aReason
 178      *        The error code corresponding to the proxy failure.  This value
 179      *        may be used to tune the delay before this proxy is used again.
 180      *
 181      * @throw NS_ERROR_NOT_AVAILABLE if there is no alternate proxy available.
 182      */
 183     nsIProxyInfo getFailoverForProxy(in nsIProxyInfo aProxyInfo,
 184                                      in nsIURI       aURI,
 185                                      in nsresult     aReason);
 186
 187     /**
 188      * This method may be used to register a proxy filter instance.  Each proxy
 189      * filter is registered with an associated position that determines the
 190      * order in which the filters are applied (starting from position 0).  When
 191      * resolve/asyncResolve is called, it generates a list of proxies for the
 192      * given URI, and then it applies the proxy filters.  The filters have the
 193      * opportunity to modify the list of proxies.
 194      *
 195      * If two filters register for the same position, then the filters will be
 196      * visited in the order in which they were registered.
 197      *
 198      * If the filter is already registered, then its position will be updated.
 199      *
 200      * After filters have been run, any disabled or disallowed proxies will be
 201      * removed from the list.  A proxy is disabled if it had previously failed-
 202      * over to another proxy (see getFailoverForProxy).  A proxy is disallowed,
 203      * for example, if it is a HTTP proxy and the nsIProtocolHandler for the
 204      * queried URI does not permit proxying via HTTP.
 205      *
 206      * If a nsIProtocolHandler disallows all proxying, then filters will never
 207      * have a chance to intercept proxy requests for such URLs.
 208      *
 209      * @param aFilter
 210      *        The nsIProtocolProxyFilter instance to be registered.
 211      * @param aPosition
 212      *        The position of the filter.
 213      *
 214      * NOTE: It is possible to construct filters that compete with one another
 215      * in undesirable ways.  This API does not attempt to protect against such
 216      * problems.  It is recommended that any extensions that choose to call
 217      * this method make their position value configurable at runtime (perhaps
 218      * via the preferences service).
 219      */
 220     void registerFilter(in nsIProtocolProxyFilter aFilter,
 221                         in unsigned long aPosition);
 222
 223     /**
 224      * This method may be used to unregister a proxy filter instance.  All
 225      * filters will be automatically unregistered at XPCOM shutdown.
 226      *
 227      * @param aFilter
 228      *        The nsIProtocolProxyFilter instance to be unregistered.
 229      */
 230     void unregisterFilter(in nsIProtocolProxyFilter aFilter);
 231 };