netwerk/base/nsINetworkPredictor.idl

   1 /* vim: set ts=2 sts=2 et sw=2: */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIURI;
   9 interface nsINetworkPredictorVerifier;
  10
  11 webidl Document;
  12
  13 typedef unsigned long PredictorPredictReason;
  14 typedef unsigned long PredictorLearnReason;
  15
  16 %{C++
  17 namespace mozilla {
  18
  19 class OriginAttributes;
  20
  21 }
  22 %}
  23
  24 [ref] native OriginAttributes(const mozilla::OriginAttributes);
  25
  26 /**
  27  * nsINetworkPredictor - learn about pages users visit, and allow us to take
  28  *                       predictive actions upon future visits.
  29  *                       NOTE: nsINetworkPredictor should only
  30  *                       be used on the main thread.
  31  */
  32 [scriptable, builtinclass, uuid(acc88e7c-3f39-42c7-ac31-6377c2c3d73e)]
  33 interface nsINetworkPredictor : nsISupports
  34 {
  35   /**
  36    * Prediction reasons
  37    *
  38    * PREDICT_LINK - we are being asked to take predictive action because
  39    * the user is hovering over a link.
  40    *
  41    * PREDICT_LOAD - we are being asked to take predictive action because
  42    * the user has initiated a pageload.
  43    *
  44    * PREDICT_STARTUP - we are being asked to take predictive action
  45    * because the browser is starting up.
  46    */
  47   const PredictorPredictReason PREDICT_LINK = 0;
  48   const PredictorPredictReason PREDICT_LOAD = 1;
  49   const PredictorPredictReason PREDICT_STARTUP = 2;
  50
  51   /**
  52    * Start taking predictive actions
  53    *
  54    * Calling this will cause the predictor to (possibly) start
  55    * taking actions such as DNS prefetch and/or TCP preconnect based on
  56    * (1) the host name that we are given, and (2) the reason we are being
  57    * asked to take actions.
  58    *
  59    * @param targetURI - The URI we are being asked to take actions based on.
  60    * @param sourceURI - The URI that is currently loaded. This is so we can
  61    *   avoid doing predictive actions for link hover on an HTTPS page (for
  62    *   example).
  63    * @param reason - The reason we are being asked to take actions. Can be
  64    *   any of the PREDICT_* values above.
  65    *   In the case of PREDICT_LINK, targetURI should be the URI of the link
  66    *   that is being hovered over, and sourceURI should be the URI of the page
  67    *   on which the link appears.
  68    *   In the case of PREDICT_LOAD, targetURI should be the URI of the page that
  69    *   is being loaded and sourceURI should be null.
  70    *   In the case of PREDICT_STARTUP, both targetURI and sourceURI should be
  71    *   null.
  72    * @param originAttributes - The originAttributes of the page load we are
  73    *   predicting about.
  74    * @param verifier - An nsINetworkPredictorVerifier used in testing to ensure
  75    *   we're predicting the way we expect to. Not necessary (or desired) for
  76    *   normal operation.
  77    */
  78   [implicit_jscontext]
  79   void predict(in nsIURI targetURI,
  80                in nsIURI sourceURI,
  81                in PredictorPredictReason reason,
  82                in jsval originAttributes,
  83                in nsINetworkPredictorVerifier verifier);
  84
  85   [notxpcom]
  86   nsresult predictNative(in nsIURI targetURI,
  87                          in nsIURI sourceURI,
  88                          in PredictorPredictReason reason,
  89                          in OriginAttributes originAttributes,
  90                          in nsINetworkPredictorVerifier verifier);
  91
  92
  93   /*
  94    * Reasons we are learning something
  95    *
  96    * LEARN_LOAD_TOPLEVEL - we are learning about the toplevel resource of a
  97    *                       pageload (NOTE: this should ONLY be used by tests)
  98    *
  99    * LEARN_LOAD_SUBRESOURCE - we are learning a subresource from a pageload
 100    *
 101    * LEARN_LOAD_REDIRECT - we are learning about the re-direct of a URI
 102    *
 103    * LEARN_STARTUP - we are learning about a page loaded during startup
 104    */
 105   const PredictorLearnReason LEARN_LOAD_TOPLEVEL = 0;
 106   const PredictorLearnReason LEARN_LOAD_SUBRESOURCE = 1;
 107   const PredictorLearnReason LEARN_LOAD_REDIRECT = 2;
 108   const PredictorLearnReason LEARN_STARTUP = 3;
 109
 110   /**
 111    * Add to our compendium of knowledge
 112    *
 113    * This adds to our prediction database to make things (hopefully)
 114    * smarter next time we predict something.
 115    *
 116    * @param targetURI - The URI that was loaded that we are keeping track of.
 117    * @param sourceURI - The URI that caused targetURI to be loaded (for page
 118    *   loads). This means the DOCUMENT URI.
 119    * @param reason - The reason we are learning this bit of knowledge.
 120    *   Reason can be any of the LEARN_* values.
 121    *   In the case of LEARN_LOAD_SUBRESOURCE, targetURI should be the URI of a
 122    *   subresource of a page, and sourceURI should be the top-level URI.
 123    *   In the case of LEARN_LOAD_REDIRECT, targetURI is the NEW URI of a
 124    *   top-level resource that was redirected to, and sourceURI is the
 125    *   ORIGINAL URI of said top-level resource.
 126    *   In the case of LEARN_STARTUP, targetURI should be the URI of a page
 127    *   that was loaded immediately after browser startup, and sourceURI should
 128    *   be null.
 129    * @param originAttributes - The originAttributes for the page load that we
 130    *   are learning about.
 131    */
 132   [implicit_jscontext]
 133   void learn(in nsIURI targetURI,
 134              in nsIURI sourceURI,
 135              in PredictorLearnReason reason,
 136              in jsval originAttributes);
 137
 138   [notxpcom]
 139   nsresult learnNative(in nsIURI targetURI,
 140                        in nsIURI sourceURI,
 141                        in PredictorLearnReason reason,
 142                        in OriginAttributes originAttributes);
 143
 144   /**
 145    * Clear out all our learned knowledge
 146    *
 147    * This removes everything from our database so that any predictions begun
 148    * after this completes will start from a blank slate.
 149    */
 150   void reset();
 151 };
 152
 153 %{C++
 154 // Wrapper functions to make use of the predictor easier and less invasive
 155 class nsIChannel;
 156
 157 class nsILoadContext;
 158 class nsILoadGroup;
 159 class nsINetworkPredictorVerifier;
 160
 161 namespace mozilla {
 162
 163 class OriginAttributes;
 164
 165 namespace net {
 166
 167 nsresult PredictorPredict(nsIURI *targetURI,
 168                           nsIURI *sourceURI,
 169                           PredictorPredictReason reason,
 170                           const OriginAttributes& originAttributes,
 171                           nsINetworkPredictorVerifier *verifier);
 172
 173 nsresult PredictorLearn(nsIURI *targetURI,
 174                         nsIURI *sourceURI,
 175                         PredictorLearnReason reason,
 176                         const OriginAttributes& originAttributes);
 177
 178 nsresult PredictorLearn(nsIURI *targetURI,
 179                         nsIURI *sourceURI,
 180                         PredictorLearnReason reason,
 181                         nsILoadGroup *loadGroup);
 182
 183 nsresult PredictorLearn(nsIURI *targetURI,
 184                         nsIURI *sourceURI,
 185                         PredictorLearnReason reason,
 186                         dom::Document *document);
 187
 188 nsresult PredictorLearnRedirect(nsIURI *targetURI,
 189                                 nsIChannel *channel,
 190                                 const OriginAttributes& originAttributes);
 191
 192 } // mozilla::net
 193 } // mozilla
 194 %}