netwerk/base/nsIProtocolProxyFilter.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   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 nsIChannel;
  10 interface nsIProtocolProxyService;
  11 interface nsIProxyInfo;
  12 interface nsIURI;
  13
  14 /**
  15  * Recipient of the result of implementers of nsIProtocolProxy(Channel)Filter
  16  * allowing the proxyinfo be provided asynchronously.
  17  */
  18 [scriptable, uuid(009E6C3F-FB64-40C5-8093-F1495C64773E)]
  19 interface nsIProxyProtocolFilterResult : nsISupports
  20 {
  21   /**
  22    * It's mandatory to call this method exactly once when the applyFilter()
  23    * implementation doesn't throw and to not call it when applyFilter() does
  24    * throw.
  25    *
  26    * It's mandatory to call this method on the same thread as the call to
  27    * applyFilter() has been made on.
  28    *
  29    * Following the above conditions, can be called either from within
  30    * applyFilter() or asynchronouly any time later.
  31    */
  32   void onProxyFilterResult(in nsIProxyInfo aProxy);
  33 };
  34
  35 /**
  36  * This interface is used to apply filters to the proxies selected for a given
  37  * URI.  Use nsIProtocolProxyService::registerFilter to hook up instances of
  38  * this interface. See also nsIProtocolProxyChannelFilter.
  39  */
  40 [scriptable, uuid(f424abd3-32b4-456c-9f45-b7e3376cb0d1)]
  41 interface nsIProtocolProxyFilter : nsISupports
  42 {
  43   /**
  44    * This method is called to apply proxy filter rules for the given URI
  45    * and proxy object (or list of proxy objects).
  46    *
  47    * @param aURI
  48    *        The URI for which these proxy settings apply.
  49    * @param aProxy
  50    *        The proxy (or list of proxies) that would be used by default for
  51    *        the given URI.  This may be null.
  52    *
  53    * @param aCallback
  54    *        An object that the implementer is obligated to call on with
  55    *        the result (from within applyFilter() or asynchronously) when
  56    *        applyFilter didn't throw.  The argument passed to onProxyFilterResult
  57    *        is the proxy (or list of proxies) that should be used in place of
  58    *        aProxy.  This can be just be aProxy if the filter chooses not to
  59    *        modify the proxy.  It can also be null to indicate that a direct
  60    *        connection should be used.  Use nsIProtocolProxyService.newProxyInfo
  61    *        to construct nsIProxyInfo objects.
  62    */
  63   void applyFilter(in nsIURI aURI, in nsIProxyInfo aProxy,
  64                    in nsIProxyProtocolFilterResult aCallback);
  65 };
  66
  67 /**
  68  * This interface is used to apply filters to the proxies selected for a given
  69  * channel.  Use nsIProtocolProxyService::registerChannelFilter to hook up instances of
  70  * this interface. See also nsIProtocolProxyFilter.
  71  */
  72 [scriptable, uuid(245b0880-82c5-4e6e-be6d-bc586aa55a90)]
  73 interface nsIProtocolProxyChannelFilter : nsISupports
  74 {
  75   /**
  76    * This method is called to apply proxy filter rules for the given channel
  77    * and proxy object (or list of proxy objects).
  78    *
  79    * @param aChannel
  80    *        The channel for which these proxy settings apply.
  81    * @param aProxy
  82    *        The proxy (or list of proxies) that would be used by default for
  83    *        the given channel. This may be null.
  84    *
  85    * @param aCallback
  86    *        An object that the implementer is obligated to call on with
  87    *        the result (from within applyFilter() or asynchronously) when
  88    *        applyFilter didn't throw.  The argument passed to onProxyFilterResult
  89    *        is the proxy (or list of proxies) that should be used in place of
  90    *        aProxy.  This can be just be aProxy if the filter chooses not to
  91    *        modify the proxy.  It can also be null to indicate that a direct
  92    *        connection should be used.  Use nsIProtocolProxyService.newProxyInfo
  93    *        to construct nsIProxyInfo objects.
  94    */
  95   void applyFilter(in nsIChannel aChannel, in nsIProxyInfo aProxy,
  96                    in nsIProxyProtocolFilterResult aCallback);
  97 };