michael@0: /* vim: set ts=2 sts=2 et sw=2: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsILoadContext;
michael@0: interface nsINetworkSeerVerifier;
michael@0: 
michael@0: typedef unsigned long SeerPredictReason;
michael@0: typedef unsigned long SeerLearnReason;
michael@0: 
michael@0: /**
michael@0:  * nsINetworkSeer - learn about pages users visit, and allow us to take
michael@0:  *                  predictive actions upon future visits.
michael@0:  *                  NOTE: nsINetworkSeer should only be used on the main thread
michael@0:  */
michael@0: [scriptable, uuid(25e323b6-99e0-4274-b5b3-1a9eb56e28ac)]
michael@0: interface nsINetworkSeer : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Prediction reasons
michael@0:    *
michael@0:    * PREDICT_LINK - we are being asked to take predictive action because
michael@0:    * the user is hovering over a link.
michael@0:    *
michael@0:    * PREDICT_LOAD - we are being asked to take predictive action because
michael@0:    * the user has initiated a pageload.
michael@0:    *
michael@0:    * PREDICT_STARTUP - we are being asked to take predictive action
michael@0:    * because the browser is starting up.
michael@0:    */
michael@0:   const SeerPredictReason PREDICT_LINK = 0;
michael@0:   const SeerPredictReason PREDICT_LOAD = 1;
michael@0:   const SeerPredictReason PREDICT_STARTUP = 2;
michael@0: 
michael@0:   /**
michael@0:    * Start taking predictive actions
michael@0:    *
michael@0:    * Calling this will cause the seer to (possibly) start
michael@0:    * taking actions such as DNS prefetch and/or TCP preconnect based on
michael@0:    * (1) the host name that we are given, and (2) the reason we are being
michael@0:    * asked to take actions.
michael@0:    *
michael@0:    * @param targetURI - The URI we are being asked to take actions based on.
michael@0:    * @param sourceURI - The URI that is currently loaded. This is so we can
michael@0:    *   avoid doing predictive actions for link hover on an HTTPS page (for
michael@0:    *   example).
michael@0:    * @param reason - The reason we are being asked to take actions. Can be
michael@0:    *   any of the PREDICT_* values above.
michael@0:    *   In the case of PREDICT_LINK, targetURI should be the URI of the link
michael@0:    *   that is being hovered over, and sourceURI should be the URI of the page
michael@0:    *   on which the link appears.
michael@0:    *   In the case of PREDICT_LOAD, targetURI should be the URI of the page that
michael@0:    *   is being loaded and sourceURI should be null.
michael@0:    *   In the case of PREDICT_STARTUP, both targetURI and sourceURI should be
michael@0:    *   null.
michael@0:    * @param loadContext - The nsILoadContext of the page load we are predicting
michael@0:    *   about.
michael@0:    * @param verifier - An nsINetworkSeerVerifier used in testing to ensure we're
michael@0:    *   predicting the way we expect to. Not necessary (or desired) for normal
michael@0:    *   operation.
michael@0:    */
michael@0:   void predict(in nsIURI targetURI,
michael@0:                in nsIURI sourceURI,
michael@0:                in SeerPredictReason reason,
michael@0:                in nsILoadContext loadContext,
michael@0:                in nsINetworkSeerVerifier verifier);
michael@0: 
michael@0: 
michael@0:   /*
michael@0:    * Reasons we are learning something
michael@0:    *
michael@0:    * LEARN_LOAD_TOPLEVEL - we are learning about the toplevel resource of a
michael@0:    *                       pageload (NOTE: this should ONLY be used by tests)
michael@0:    *
michael@0:    * LEARN_LOAD_SUBRESOURCE - we are learning a subresource from a pageload
michael@0:    *
michael@0:    * LEARN_LOAD_REDIRECT - we are learning about the re-direct of a URI
michael@0:    *
michael@0:    * LEARN_STARTUP - we are learning about a page loaded during startup
michael@0:    */
michael@0:   const SeerLearnReason LEARN_LOAD_TOPLEVEL = 0;
michael@0:   const SeerLearnReason LEARN_LOAD_SUBRESOURCE = 1;
michael@0:   const SeerLearnReason LEARN_LOAD_REDIRECT = 2;
michael@0:   const SeerLearnReason LEARN_STARTUP = 3;
michael@0: 
michael@0:   /**
michael@0:    * Add to our compendium of knowledge
michael@0:    *
michael@0:    * This adds to our prediction database to make things (hopefully)
michael@0:    * smarter next time we predict something.
michael@0:    *
michael@0:    * @param targetURI - The URI that was loaded that we are keeping track of.
michael@0:    * @param sourceURI - The URI that caused targetURI to be loaded (for page
michael@0:    *   loads). This means the DOCUMENT URI.
michael@0:    * @param reason - The reason we are learning this bit of knowledge.
michael@0:    *   Reason can be any of the LEARN_* values.
michael@0:    *   In the case of LEARN_LOAD_SUBRESOURCE, targetURI should be the URI of a
michael@0:    *   subresource of a page, and sourceURI should be the top-level URI.
michael@0:    *   In the case of LEARN_LOAD_REDIRECT, targetURI is the NEW URI of a
michael@0:    *   top-level resource that was redirected to, and sourceURI is the
michael@0:    *   ORIGINAL URI of said top-level resource.
michael@0:    *   In the case of LEARN_STARTUP, targetURI should be the URI of a page
michael@0:    *   that was loaded immediately after browser startup, and sourceURI should
michael@0:    *   be null.
michael@0:    * @param loadContext - The nsILoadContext for the page load that we are
michael@0:    *   learning about.
michael@0:    */
michael@0:   void learn(in nsIURI targetURI,
michael@0:              in nsIURI sourceURI,
michael@0:              in SeerLearnReason reason,
michael@0:              in nsILoadContext loadContext);
michael@0: 
michael@0:   /**
michael@0:    * Clear out all our learned knowledge
michael@0:    *
michael@0:    * This removes everything from our database so that any predictions begun
michael@0:    * after this completes will start from a blank slate.
michael@0:    */
michael@0:   void reset();
michael@0: 
michael@0:   /**
michael@0:    * @deprecated THIS API IS FOR TESTING ONLY. IF YOU DON'T KNOW WHAT IT DOES,
michael@0:    * DON'T USE IT
michael@0:    */
michael@0:   void prepareForDnsTest(in long long timestamp, in string uri);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: // Wrapper functions to make use of the seer easier and less invasive
michael@0: class nsIChannel;
michael@0: class nsIDocument;
michael@0: class nsILoadContext;
michael@0: class nsILoadGroup;
michael@0: class nsINetworkSeerVerifier;
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace net {
michael@0: 
michael@0: nsresult SeerPredict(nsIURI *targetURI,
michael@0:                      nsIURI *sourceURI,
michael@0:                      SeerPredictReason reason,
michael@0:                      nsILoadContext *loadContext,
michael@0:                      nsINetworkSeerVerifier *verifier);
michael@0: 
michael@0: nsresult SeerLearn(nsIURI *targetURI,
michael@0:                    nsIURI *sourceURI,
michael@0:                    SeerLearnReason reason,
michael@0:                    nsILoadContext *loadContext);
michael@0: 
michael@0: nsresult SeerLearn(nsIURI *targetURI,
michael@0:                    nsIURI *sourceURI,
michael@0:                    SeerLearnReason reason,
michael@0:                    nsILoadGroup *loadGroup);
michael@0: 
michael@0: nsresult SeerLearn(nsIURI *targetURI,
michael@0:                    nsIURI *sourceURI,
michael@0:                    SeerLearnReason reason,
michael@0:                    nsIDocument *document);
michael@0: 
michael@0: nsresult SeerLearnRedirect(nsIURI *targetURI,
michael@0:                            nsIChannel *channel,
michael@0:                            nsILoadContext *loadContext);
michael@0: 
michael@0: } // mozilla::net
michael@0: } // mozilla
michael@0: %}