docshell/shistory/nsISHistoryListener.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIURI;
  10
  11 /**
  12  * nsISHistoryListener defines the interface one can implement to receive
  13  * notifications about activities in session history and (for reloads) to be
  14  * able to cancel them.
  15  *
  16  * A session history listener will be notified when pages are added, removed
  17  * and loaded from session history. In the case of reloads, it can prevent them
  18  * from happening by returning false from the corresponding callback method.
  19  *
  20  * A session history listener can be registered on a particular nsISHistory
  21  * instance via the nsISHistory::addSHistoryListener() method.
  22  *
  23  * Listener methods should not alter the session history. Things are likely to
  24  * go haywire if they do.
  25  */
  26 [scriptable, uuid(125c0833-746a-400e-9b89-d2d18545c08a)]
  27 interface nsISHistoryListener : nsISupports
  28 {
  29   /**
  30    * Called when a new document is added to session history. New documents are
  31    * added to session history by docshell when new pages are loaded in a frame
  32    * or content area, for example via nsIWebNavigation::loadURI()
  33    *
  34    * @param aNewURI     The URI of the document to be added to session history.
  35    * @param aOldIndex   The index of the current history item before the
  36    *                    operation.
  37    */
  38   void OnHistoryNewEntry(in nsIURI aNewURI, in long aOldIndex);
  39
  40   /**
  41    * Called before the current document is reloaded, for example due to a
  42    * nsIWebNavigation::reload() call.
  43    */
  44   boolean OnHistoryReload();
  45
  46   /**
  47    * Called before navigating to a session history entry by index, for example,
  48    * when nsIWebNavigation::gotoIndex() is called.
  49    */
  50   void OnHistoryGotoIndex();
  51
  52   /**
  53    * Called before entries are removed from the start of session history.
  54    * Entries can be removed from session history for various reasons, for
  55    * example to control the memory usage of the browser, to prevent users from
  56    * loading documents from history, to erase evidence of prior page loads, etc.
  57    *
  58    * To purge documents from session history call nsISHistory::PurgeHistory().
  59    *
  60    * @param aNumEntries  The number of entries being removed.
  61    */
  62   void OnHistoryPurge(in long aNumEntries);
  63
  64   /**
  65    * Called before entries are removed from the end of session history. This
  66    * occurs when navigating to a new page while on a previous session entry.
  67    *
  68    * @param aNumEntries  The number of entries being removed.
  69    */
  70   void OnHistoryTruncate(in long aNumEntries);
  71
  72   /**
  73    * Called before an entry is replaced in the session history. Entries are
  74    * replaced when navigating away from non-persistent history entries (such as
  75    * about pages) and when history.replaceState is called.
  76    */
  77   void OnHistoryReplaceEntry();
  78
  79
  80   /**
  81    * Called whenever a content viewer is evicted. A content viewer is evicted
  82    * whenever a bfcache entry has timed out or the number of total content
  83    * viewers has exceeded the global max. This is used for testing only.
  84    *
  85    * @param aNumEvicted - number of content viewers evicted
  86    */
  87   void OnContentViewerEvicted(in unsigned long aNumEvicted);
  88 };