The Tor Browser / file revision

 /* vim: set ts=2 sts=2 et sw=2: */

 /* This Source Code Form is subject to the terms of the Mozilla Public

  * License, v. 2.0. If a copy of the MPL was not distributed with this

  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

 #include "nsISupports.idl"

 interface nsIURI;

 interface nsILoadContext;

 interface nsINetworkSeerVerifier;

 typedef unsigned long SeerPredictReason;

 typedef unsigned long SeerLearnReason;

 /**

  * nsINetworkSeer - learn about pages users visit, and allow us to take

  *                  predictive actions upon future visits.

  *                  NOTE: nsINetworkSeer should only be used on the main thread

  */

 [scriptable, uuid(25e323b6-99e0-4274-b5b3-1a9eb56e28ac)]

 interface nsINetworkSeer : nsISupports

 {

   /**

    * Prediction reasons

    *

    * PREDICT_LINK - we are being asked to take predictive action because

    * the user is hovering over a link.

    *

    * PREDICT_LOAD - we are being asked to take predictive action because

    * the user has initiated a pageload.

    *

    * PREDICT_STARTUP - we are being asked to take predictive action

    * because the browser is starting up.

    */

   const SeerPredictReason PREDICT_LINK = 0;

   const SeerPredictReason PREDICT_LOAD = 1;

   const SeerPredictReason PREDICT_STARTUP = 2;

   /**

    * Start taking predictive actions

    *

    * Calling this will cause the seer to (possibly) start

    * taking actions such as DNS prefetch and/or TCP preconnect based on

    * (1) the host name that we are given, and (2) the reason we are being

    * asked to take actions.

    *

    * @param targetURI - The URI we are being asked to take actions based on.

    * @param sourceURI - The URI that is currently loaded. This is so we can

    *   avoid doing predictive actions for link hover on an HTTPS page (for

    *   example).

    * @param reason - The reason we are being asked to take actions. Can be

    *   any of the PREDICT_* values above.

    *   In the case of PREDICT_LINK, targetURI should be the URI of the link

    *   that is being hovered over, and sourceURI should be the URI of the page

    *   on which the link appears.

    *   In the case of PREDICT_LOAD, targetURI should be the URI of the page that

    *   is being loaded and sourceURI should be null.

    *   In the case of PREDICT_STARTUP, both targetURI and sourceURI should be

    *   null.

    * @param loadContext - The nsILoadContext of the page load we are predicting

    *   about.

    * @param verifier - An nsINetworkSeerVerifier used in testing to ensure we're

    *   predicting the way we expect to. Not necessary (or desired) for normal

    *   operation.

    */

   void predict(in nsIURI targetURI,

                in nsIURI sourceURI,

                in SeerPredictReason reason,

                in nsILoadContext loadContext,

                in nsINetworkSeerVerifier verifier);

   /*

    * Reasons we are learning something

    *

    * LEARN_LOAD_TOPLEVEL - we are learning about the toplevel resource of a

    *                       pageload (NOTE: this should ONLY be used by tests)

    *

    * LEARN_LOAD_SUBRESOURCE - we are learning a subresource from a pageload

    *

    * LEARN_LOAD_REDIRECT - we are learning about the re-direct of a URI

    *

    * LEARN_STARTUP - we are learning about a page loaded during startup

    */

   const SeerLearnReason LEARN_LOAD_TOPLEVEL = 0;

   const SeerLearnReason LEARN_LOAD_SUBRESOURCE = 1;

   const SeerLearnReason LEARN_LOAD_REDIRECT = 2;

   const SeerLearnReason LEARN_STARTUP = 3;

   /**

    * Add to our compendium of knowledge

    *

    * This adds to our prediction database to make things (hopefully)

    * smarter next time we predict something.

    *

    * @param targetURI - The URI that was loaded that we are keeping track of.

    * @param sourceURI - The URI that caused targetURI to be loaded (for page

    *   loads). This means the DOCUMENT URI.

    * @param reason - The reason we are learning this bit of knowledge.

    *   Reason can be any of the LEARN_* values.

    *   In the case of LEARN_LOAD_SUBRESOURCE, targetURI should be the URI of a

    *   subresource of a page, and sourceURI should be the top-level URI.

    *   In the case of LEARN_LOAD_REDIRECT, targetURI is the NEW URI of a

    *   top-level resource that was redirected to, and sourceURI is the

    *   ORIGINAL URI of said top-level resource.

    *   In the case of LEARN_STARTUP, targetURI should be the URI of a page

    *   that was loaded immediately after browser startup, and sourceURI should

    *   be null.

    * @param loadContext - The nsILoadContext for the page load that we are

    *   learning about.

    */

   void learn(in nsIURI targetURI,

              in nsIURI sourceURI,

              in SeerLearnReason reason,

              in nsILoadContext loadContext);

   /**

    * Clear out all our learned knowledge

    *

    * This removes everything from our database so that any predictions begun

    * after this completes will start from a blank slate.

    */

   void reset();

   /**

    * @deprecated THIS API IS FOR TESTING ONLY. IF YOU DON'T KNOW WHAT IT DOES,

    * DON'T USE IT

    */

   void prepareForDnsTest(in long long timestamp, in string uri);

 };

 %{C++

 // Wrapper functions to make use of the seer easier and less invasive

 class nsIChannel;

 class nsIDocument;

 class nsILoadContext;

 class nsILoadGroup;

 class nsINetworkSeerVerifier;

 namespace mozilla {

 namespace net {

 nsresult SeerPredict(nsIURI *targetURI,

                      nsIURI *sourceURI,

                      SeerPredictReason reason,

                      nsILoadContext *loadContext,

                      nsINetworkSeerVerifier *verifier);

 nsresult SeerLearn(nsIURI *targetURI,

                    nsIURI *sourceURI,

                    SeerLearnReason reason,

                    nsILoadContext *loadContext);

 nsresult SeerLearn(nsIURI *targetURI,

                    nsIURI *sourceURI,

                    SeerLearnReason reason,

                    nsILoadGroup *loadGroup);

 nsresult SeerLearn(nsIURI *targetURI,

                    nsIURI *sourceURI,

                    SeerLearnReason reason,

                    nsIDocument *document);

 nsresult SeerLearnRedirect(nsIURI *targetURI,

                            nsIChannel *channel,

                            nsILoadContext *loadContext);

 } // mozilla::net

 } // mozilla

 %}