docshell/shistory/nsISHistory.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIBFCacheEntry;
   9 interface nsISHEntry;
  10 interface nsISHistoryListener;
  11 interface nsIURI;
  12 webidl BrowsingContext;
  13
  14 %{C++
  15 #include "nsTArrayForwardDeclare.h"
  16 #include "mozilla/Maybe.h"
  17 struct EntriesAndBrowsingContextData;
  18 namespace mozilla {
  19 namespace dom {
  20 class SHEntrySharedParentState;
  21 } // namespace dom
  22 } // namespace mozilla
  23 %}
  24
  25 [ref] native nsDocshellIDArray(nsTArray<nsID>);
  26 native MaybeInt32(mozilla::Maybe<int32_t>);
  27 [ptr] native SHEntrySharedParentStatePtr(mozilla::dom::SHEntrySharedParentState);
  28 /**
  29  * An interface to the primary properties of the Session History
  30  * component. In an embedded browser environment, the nsIWebBrowser
  31  * object creates an instance of session history for each open window.
  32  * A handle to the session history object can be obtained from
  33  * nsIWebNavigation. In a non-embedded situation, the  owner of the
  34  * session history component must create a instance of it and set
  35  * it in the nsIWebNavigation object.
  36  * This interface is accessible from javascript.
  37  */
  38
  39 [builtinclass, scriptable, uuid(7b807041-e60a-4384-935f-af3061d8b815)]
  40 interface nsISHistory: nsISupports
  41 {
  42   /**
  43    * A readonly property of the interface that returns
  44    * the number of toplevel documents currently available
  45    * in session history.
  46    */
  47   [infallible] readonly attribute long count;
  48
  49   /**
  50    * The index of the current document in session history. Not infallible
  51    * because setting can fail if the assigned value is out of range.
  52    */
  53   attribute long index;
  54
  55   /**
  56    * A readonly property of the interface that returns
  57    * the index of the last document that started to load and
  58    * didn't finished yet. When document finishes the loading
  59    * value -1 is returned.
  60    */
  61   [infallible] readonly attribute long requestedIndex;
  62
  63   /**
  64    * Artifically set the |requestedIndex| for this nsISHEntry to the given
  65    * index. This is used when resuming a cross-process load from a different
  66    * process.
  67    */
  68   [noscript, notxpcom]
  69   void internalSetRequestedIndex(in long aRequestedIndex);
  70
  71   /**
  72    * Get the history entry at a given index. Returns non-null on success.
  73    *
  74    * @param index             The index value whose entry is requested.
  75    *                          The oldest entry is located at index == 0.
  76    * @return                  The found entry; never null.
  77    */
  78   nsISHEntry getEntryAtIndex(in long aIndex);
  79
  80   /**
  81    * Called to purge older documents from history.
  82    * Documents can be removed from session history for various
  83    * reasons. For example to  control memory usage of the browser, to
  84    * prevent users from loading documents from history, to erase evidence of
  85    * prior page loads etc...
  86    *
  87    * @param numEntries        The number of toplevel documents to be
  88    *                          purged from history. During purge operation,
  89    *                          the latest documents are maintained and older
  90    *                          'numEntries' documents are removed from history.
  91    * @throws                  <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code>
  92    *                          Purge was vetod.
  93    * @throws                  <code>NS_ERROR_FAILURE</code> numEntries is
  94    *                          invalid or out of bounds with the size of history.
  95    */
  96   void purgeHistory(in long aNumEntries);
  97
  98   /**
  99    * Called to register a listener for the session history component.
 100    * Listeners are notified when pages are loaded or purged from history.
 101    *
 102    * @param aListener         Listener object to be notified for all
 103    *                          page loads that initiate in session history.
 104    *
 105    * @note                    A listener object must implement
 106    *                          nsISHistoryListener and nsSupportsWeakReference
 107    *
 108    * @see nsISHistoryListener
 109    * @see nsSupportsWeakReference
 110    */
 111   void addSHistoryListener(in nsISHistoryListener aListener);
 112
 113   /**
 114    * Called to remove a listener for the session history component.
 115    * Listeners are notified when pages are loaded from history.
 116    *
 117    * @param aListener         Listener object to be removed from
 118    *                          session history.
 119    *
 120    * @note                    A listener object must implement
 121    *                          nsISHistoryListener and nsSupportsWeakReference
 122    * @see nsISHistoryListener
 123    * @see nsSupportsWeakReference
 124    */
 125   void removeSHistoryListener(in nsISHistoryListener aListener);
 126
 127   void reloadCurrentEntry();
 128
 129   /**
 130    * Load the entry at the particular index.
 131    */
 132   [noscript]
 133   void gotoIndex(in long aIndex, in boolean aUserActivation);
 134
 135   /**
 136    * If an element exists at the particular index and
 137    * whether it has user interaction.
 138    */
 139   [noscript,notxpcom]
 140   boolean hasUserInteractionAtIndex(in long aIndex);
 141
 142   /**
 143    * Called to obtain the index to a given history entry.
 144    *
 145    * @param aEntry            The entry to obtain the index of.
 146    *
 147    * @return                  <code>NS_OK</code> index for the history entry
 148    *                          is obtained successfully.
 149    *                          <code>NS_ERROR_FAILURE</code> Error in obtaining
 150    *                          index for the given history entry.
 151    */
 152   [noscript, notxpcom]
 153   long getIndexOfEntry(in nsISHEntry aEntry);
 154
 155   /**
 156    * Add a new Entry to the History List.
 157    *
 158    * @param aEntry            The entry to add.
 159    * @param aPersist          If true this specifies that the entry should
 160    *                          persist in the list. If false, this means that
 161    *                          when new entries are added this element will not
 162    *                          appear in the session history list.
 163    */
 164   void addEntry(in nsISHEntry aEntry, in boolean aPersist);
 165
 166   /**
 167    * Update the index maintained by sessionHistory
 168    */
 169   void updateIndex();
 170
 171   /**
 172    * Replace the nsISHEntry at a particular index
 173    *
 174    * @param aIndex            The index at which the entry should be replaced.
 175    * @param aReplaceEntry     The replacement entry for the index.
 176    */
 177   void replaceEntry(in long aIndex, in nsISHEntry aReplaceEntry);
 178
 179   /**
 180    * Notifies all registered session history listeners about an impending
 181    * reload.
 182    *
 183    * @return                  Whether the operation can proceed.
 184    */
 185   boolean notifyOnHistoryReload();
 186
 187   /**
 188    * Evict content viewers which don't lie in the "safe" range around aIndex.
 189    * In practice, this should leave us with no more than gHistoryMaxViewers
 190    * viewers associated with this SHistory object.
 191    *
 192    * Also make sure that the total number of content viewers in all windows is
 193    * not greater than our global max; if it is, evict viewers as appropriate.
 194    *
 195    * @param aIndex           The index around which the "safe" range is
 196    *                         centered.  In general, if you just navigated the
 197    *                         history, aIndex should be the index history was
 198    *                         navigated to.
 199    */
 200   void evictOutOfRangeDocumentViewers(in long aIndex);
 201
 202   /**
 203    * Evict the content viewer associated with a bfcache entry that has timed
 204    * out.
 205    */
 206   [noscript, notxpcom]
 207   void evictExpiredDocumentViewerForEntry(in SHEntrySharedParentStatePtr aEntry);
 208
 209   /**
 210    * Evict all the content viewers in this session history
 211    */
 212   void evictAllDocumentViewers();
 213
 214   /**
 215    * Add a BFCache entry to expiration tracker so it gets evicted on
 216    * expiration.
 217    */
 218   [noscript, notxpcom]
 219   void addToExpirationTracker(in SHEntrySharedParentStatePtr aEntry);
 220
 221   /**
 222    * Remove a BFCache entry from expiration tracker.
 223    */
 224   [noscript, notxpcom]
 225   void removeFromExpirationTracker(in SHEntrySharedParentStatePtr aEntry);
 226
 227   /**
 228    * Remove dynamic entries found at given index.
 229    *
 230    * @param aIndex           Index to remove dynamic entries from. It will be
 231    *                         passed to RemoveEntries as aStartIndex.
 232    * @param aEntry (optional)  The entry to start looking in for dynamic
 233    *                         entries. Only the dynamic descendants of the
 234    *                         entry will be removed. If not given, all dynamic
 235    *                         entries at the index will be removed.
 236    */
 237   [noscript, notxpcom]
 238   void RemoveDynEntries(in long aIndex, in nsISHEntry aEntry);
 239
 240   /**
 241    * Similar to RemoveDynEntries, but instead of specifying an index, use the
 242    * given BFCacheEntry to find the index and remove dynamic entries from the
 243    * index.
 244    *
 245    * The method takes no effect if the bfcache entry is not or no longer hold
 246    * by the SHistory instance.
 247    *
 248    * @param aEntry           The bfcache entry to look up for index to remove
 249    *                         dynamic entries from.
 250    */
 251   [noscript, notxpcom]
 252   void RemoveDynEntriesForBFCacheEntry(in nsIBFCacheEntry aEntry);
 253
 254   /**
 255    * Removes entries from the history if their docshellID is in
 256    * aIDs array.
 257    */
 258   [noscript, notxpcom]
 259   void RemoveEntries(in nsDocshellIDArray aIDs, in long aStartIndex);
 260
 261   /**
 262    * Collect docshellIDs from aEntry's children and remove those
 263    * entries from history.
 264    *
 265    * @param aEntry           Children docshellID's will be collected from
 266    *                         this entry and passed to RemoveEntries as aIDs.
 267   */
 268   [noscript, notxpcom]
 269   void RemoveFrameEntries(in nsISHEntry aEntry);
 270
 271   [noscript]
 272   void Reload(in unsigned long aReloadFlags);
 273
 274   [notxpcom] void EnsureCorrectEntryAtCurrIndex(in nsISHEntry aEntry);
 275
 276   [notxpcom] void EvictDocumentViewersOrReplaceEntry(in nsISHEntry aNewSHEntry, in bool aReplace);
 277
 278   nsISHEntry createEntry();
 279
 280   [noscript] void AddToRootSessionHistory(in bool aCloneChildren, in nsISHEntry aOSHE,
 281                                           in BrowsingContext aRootBC, in nsISHEntry aEntry,
 282                                           in unsigned long aLoadType,
 283                                           in bool aShouldPersist,
 284                                           out MaybeInt32 aPreviousEntryIndex,
 285                                           out MaybeInt32 aLoadedEntryIndex);
 286
 287   [noscript] void AddChildSHEntryHelper(in nsISHEntry aCloneRef, in nsISHEntry aNewEntry,
 288                                         in BrowsingContext aRootBC, in bool aCloneChildren);
 289
 290   [noscript, notxpcom] boolean isEmptyOrHasEntriesForSingleTopLevelPage();
 291 };