diff -r 000000000000 -r 6474c204b198 netwerk/base/public/nsINetworkSeer.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/netwerk/base/public/nsINetworkSeer.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,170 @@ +/* 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 +%}