1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsINetworkSeer.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,170 @@
1.4 +/* vim: set ts=2 sts=2 et sw=2: */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsILoadContext;
1.13 +interface nsINetworkSeerVerifier;
1.14 +
1.15 +typedef unsigned long SeerPredictReason;
1.16 +typedef unsigned long SeerLearnReason;
1.17 +
1.18 +/**
1.19 + * nsINetworkSeer - learn about pages users visit, and allow us to take
1.20 + * predictive actions upon future visits.
1.21 + * NOTE: nsINetworkSeer should only be used on the main thread
1.22 + */
1.23 +[scriptable, uuid(25e323b6-99e0-4274-b5b3-1a9eb56e28ac)]
1.24 +interface nsINetworkSeer : nsISupports
1.25 +{
1.26 + /**
1.27 + * Prediction reasons
1.28 + *
1.29 + * PREDICT_LINK - we are being asked to take predictive action because
1.30 + * the user is hovering over a link.
1.31 + *
1.32 + * PREDICT_LOAD - we are being asked to take predictive action because
1.33 + * the user has initiated a pageload.
1.34 + *
1.35 + * PREDICT_STARTUP - we are being asked to take predictive action
1.36 + * because the browser is starting up.
1.37 + */
1.38 + const SeerPredictReason PREDICT_LINK = 0;
1.39 + const SeerPredictReason PREDICT_LOAD = 1;
1.40 + const SeerPredictReason PREDICT_STARTUP = 2;
1.41 +
1.42 + /**
1.43 + * Start taking predictive actions
1.44 + *
1.45 + * Calling this will cause the seer to (possibly) start
1.46 + * taking actions such as DNS prefetch and/or TCP preconnect based on
1.47 + * (1) the host name that we are given, and (2) the reason we are being
1.48 + * asked to take actions.
1.49 + *
1.50 + * @param targetURI - The URI we are being asked to take actions based on.
1.51 + * @param sourceURI - The URI that is currently loaded. This is so we can
1.52 + * avoid doing predictive actions for link hover on an HTTPS page (for
1.53 + * example).
1.54 + * @param reason - The reason we are being asked to take actions. Can be
1.55 + * any of the PREDICT_* values above.
1.56 + * In the case of PREDICT_LINK, targetURI should be the URI of the link
1.57 + * that is being hovered over, and sourceURI should be the URI of the page
1.58 + * on which the link appears.
1.59 + * In the case of PREDICT_LOAD, targetURI should be the URI of the page that
1.60 + * is being loaded and sourceURI should be null.
1.61 + * In the case of PREDICT_STARTUP, both targetURI and sourceURI should be
1.62 + * null.
1.63 + * @param loadContext - The nsILoadContext of the page load we are predicting
1.64 + * about.
1.65 + * @param verifier - An nsINetworkSeerVerifier used in testing to ensure we're
1.66 + * predicting the way we expect to. Not necessary (or desired) for normal
1.67 + * operation.
1.68 + */
1.69 + void predict(in nsIURI targetURI,
1.70 + in nsIURI sourceURI,
1.71 + in SeerPredictReason reason,
1.72 + in nsILoadContext loadContext,
1.73 + in nsINetworkSeerVerifier verifier);
1.74 +
1.75 +
1.76 + /*
1.77 + * Reasons we are learning something
1.78 + *
1.79 + * LEARN_LOAD_TOPLEVEL - we are learning about the toplevel resource of a
1.80 + * pageload (NOTE: this should ONLY be used by tests)
1.81 + *
1.82 + * LEARN_LOAD_SUBRESOURCE - we are learning a subresource from a pageload
1.83 + *
1.84 + * LEARN_LOAD_REDIRECT - we are learning about the re-direct of a URI
1.85 + *
1.86 + * LEARN_STARTUP - we are learning about a page loaded during startup
1.87 + */
1.88 + const SeerLearnReason LEARN_LOAD_TOPLEVEL = 0;
1.89 + const SeerLearnReason LEARN_LOAD_SUBRESOURCE = 1;
1.90 + const SeerLearnReason LEARN_LOAD_REDIRECT = 2;
1.91 + const SeerLearnReason LEARN_STARTUP = 3;
1.92 +
1.93 + /**
1.94 + * Add to our compendium of knowledge
1.95 + *
1.96 + * This adds to our prediction database to make things (hopefully)
1.97 + * smarter next time we predict something.
1.98 + *
1.99 + * @param targetURI - The URI that was loaded that we are keeping track of.
1.100 + * @param sourceURI - The URI that caused targetURI to be loaded (for page
1.101 + * loads). This means the DOCUMENT URI.
1.102 + * @param reason - The reason we are learning this bit of knowledge.
1.103 + * Reason can be any of the LEARN_* values.
1.104 + * In the case of LEARN_LOAD_SUBRESOURCE, targetURI should be the URI of a
1.105 + * subresource of a page, and sourceURI should be the top-level URI.
1.106 + * In the case of LEARN_LOAD_REDIRECT, targetURI is the NEW URI of a
1.107 + * top-level resource that was redirected to, and sourceURI is the
1.108 + * ORIGINAL URI of said top-level resource.
1.109 + * In the case of LEARN_STARTUP, targetURI should be the URI of a page
1.110 + * that was loaded immediately after browser startup, and sourceURI should
1.111 + * be null.
1.112 + * @param loadContext - The nsILoadContext for the page load that we are
1.113 + * learning about.
1.114 + */
1.115 + void learn(in nsIURI targetURI,
1.116 + in nsIURI sourceURI,
1.117 + in SeerLearnReason reason,
1.118 + in nsILoadContext loadContext);
1.119 +
1.120 + /**
1.121 + * Clear out all our learned knowledge
1.122 + *
1.123 + * This removes everything from our database so that any predictions begun
1.124 + * after this completes will start from a blank slate.
1.125 + */
1.126 + void reset();
1.127 +
1.128 + /**
1.129 + * @deprecated THIS API IS FOR TESTING ONLY. IF YOU DON'T KNOW WHAT IT DOES,
1.130 + * DON'T USE IT
1.131 + */
1.132 + void prepareForDnsTest(in long long timestamp, in string uri);
1.133 +};
1.134 +
1.135 +%{C++
1.136 +// Wrapper functions to make use of the seer easier and less invasive
1.137 +class nsIChannel;
1.138 +class nsIDocument;
1.139 +class nsILoadContext;
1.140 +class nsILoadGroup;
1.141 +class nsINetworkSeerVerifier;
1.142 +
1.143 +namespace mozilla {
1.144 +namespace net {
1.145 +
1.146 +nsresult SeerPredict(nsIURI *targetURI,
1.147 + nsIURI *sourceURI,
1.148 + SeerPredictReason reason,
1.149 + nsILoadContext *loadContext,
1.150 + nsINetworkSeerVerifier *verifier);
1.151 +
1.152 +nsresult SeerLearn(nsIURI *targetURI,
1.153 + nsIURI *sourceURI,
1.154 + SeerLearnReason reason,
1.155 + nsILoadContext *loadContext);
1.156 +
1.157 +nsresult SeerLearn(nsIURI *targetURI,
1.158 + nsIURI *sourceURI,
1.159 + SeerLearnReason reason,
1.160 + nsILoadGroup *loadGroup);
1.161 +
1.162 +nsresult SeerLearn(nsIURI *targetURI,
1.163 + nsIURI *sourceURI,
1.164 + SeerLearnReason reason,
1.165 + nsIDocument *document);
1.166 +
1.167 +nsresult SeerLearnRedirect(nsIURI *targetURI,
1.168 + nsIChannel *channel,
1.169 + nsILoadContext *loadContext);
1.170 +
1.171 +} // mozilla::net
1.172 +} // mozilla
1.173 +%}
