netwerk/base/src/nsPACMan.h

   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 /* ***** 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 Google Inc.
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *  Darin Fisher <darin@meer.net>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef nsPACMan_h__
  40 #define nsPACMan_h__
  41
  42 #include "nsIStreamLoader.h"
  43 #include "nsIInterfaceRequestor.h"
  44 #include "nsIChannelEventSink.h"
  45 #include "nsIProxyAutoConfig.h"
  46 #include "nsIURI.h"
  47 #include "nsCOMPtr.h"
  48 #include "nsString.h"
  49 #include "prclist.h"
  50
  51 /**
  52  * This class defines a callback interface used by AsyncGetProxyForURI.
  53  */
  54 class NS_NO_VTABLE nsPACManCallback : public nsISupports
  55 {
  56 public:
  57   /**
  58    * This method is invoked on the same thread that called AsyncGetProxyForURI.
  59    *
  60    * @param status
  61    *        This parameter indicates whether or not the PAC query succeeded.
  62    * @param pacString
  63    *        This parameter holds the value of the PAC string.  It is empty when
  64    *        status is a failure code.
  65    */
  66   virtual void OnQueryComplete(nsresult status, const nsCString &pacString) = 0;
  67 };
  68
  69 /**
  70  * This class provides an abstraction layer above the PAC thread.  The methods
  71  * defined on this class are intended to be called on the main thread only.
  72  */
  73 class nsPACMan : public nsIStreamLoaderObserver
  74                , public nsIInterfaceRequestor
  75                , public nsIChannelEventSink
  76 {
  77 public:
  78   NS_DECL_ISUPPORTS
  79
  80   nsPACMan();
  81
  82   /**
  83    * This method may be called to shutdown the PAC manager.  Any async queries
  84    * that have not yet completed will either finish normally or be canceled by
  85    * the time this method returns.
  86    */
  87   void Shutdown();
  88
  89   /**
  90    * This method queries a PAC result synchronously.
  91    *
  92    * @param uri
  93    *        The URI to query.
  94    * @param result
  95    *        Holds the PAC result string upon return.
  96    *
  97    * @return NS_ERROR_IN_PROGRESS if the PAC file is not yet loaded.
  98    * @return NS_ERROR_NOT_AVAILABLE if the PAC file could not be loaded.
  99    */
 100   nsresult GetProxyForURI(nsIURI *uri, nsACString &result);
 101
 102   /**
 103    * This method queries a PAC result asynchronously.  The callback runs on the
 104    * calling thread.  If the PAC file has not yet been loaded, then this method
 105    * will queue up the request, and complete it once the PAC file has been
 106    * loaded.
 107    *
 108    * @param uri
 109    *        The URI to query.
 110    * @param callback
 111    *        The callback to run once the PAC result is available.
 112    */
 113   nsresult AsyncGetProxyForURI(nsIURI *uri, nsPACManCallback *callback);
 114
 115   /**
 116    * This method may be called to reload the PAC file.  While we are loading
 117    * the PAC file, any asynchronous PAC queries will be queued up to be
 118    * processed once the PAC file finishes loading.
 119    *
 120    * @param pacURI
 121    *        The nsIURI of the PAC file to load.  If this parameter is null,
 122    *        then the previous PAC URI is simply reloaded.
 123    */
 124   nsresult LoadPACFromURI(nsIURI *pacURI);
 125
 126   /**
 127    * Returns true if we are currently loading the PAC file.
 128    */
 129   PRBool IsLoading() { return mLoader != nsnull; }
 130
 131   /**
 132    * Returns true if the given URI matches the URI of our PAC file.
 133    */
 134   PRBool IsPACURI(nsIURI *uri) {
 135     PRBool result;
 136     return mPACURI && NS_SUCCEEDED(mPACURI->Equals(uri, &result)) && result;
 137   }
 138
 139 private:
 140   NS_DECL_NSISTREAMLOADEROBSERVER
 141   NS_DECL_NSIINTERFACEREQUESTOR
 142   NS_DECL_NSICHANNELEVENTSINK
 143
 144   ~nsPACMan();
 145
 146   /**
 147    * Cancel any existing load if any.
 148    */
 149   void CancelExistingLoad();
 150
 151   /**
 152    * Process mPendingQ.  If status is a failure code, then the pending queue
 153    * will be emptied.  If status is a success code, then the pending requests
 154    * will be processed (i.e., their Start method will be called).
 155    */
 156   void ProcessPendingQ(nsresult status);
 157
 158   /**
 159    * Start loading the PAC file.
 160    */
 161   void StartLoading();
 162
 163   /**
 164    * Reload the PAC file if there is reason to.
 165    */
 166   void MaybeReloadPAC();
 167
 168   /**
 169    * Called when we fail to load the PAC file.
 170    */
 171   void OnLoadFailure();
 172
 173 private:
 174   nsCOMPtr<nsIProxyAutoConfig> mPAC;
 175   nsCOMPtr<nsIURI>             mPACURI;
 176   PRCList                      mPendingQ;
 177   nsCOMPtr<nsIStreamLoader>    mLoader;
 178   PRPackedBool                 mLoadPending;
 179   PRPackedBool                 mShutdown;
 180   PRTime                       mScheduledReload;
 181   PRUint32                     mLoadFailureCount;
 182 };
 183
 184 #endif  // nsPACMan_h__