The Tor Browser: comparison netwerk/base/public/nsINetworkSeer.idl

--1:000000000000
+:e221250c3b5e
+/* 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
+%}

The Tor Browser / file comparison

comparison: netwerk/base/public/nsINetworkSeer.idl

netwerk/base/public/nsINetworkSeer.idl