"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/docshell/shistory/nsISHistory.idl" (17 Sep 2019, 8882 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) IDL source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes reports for "nsISHistory.idl": 60.7.2_vs_68.0 or 67.0.4_vs_68.0.

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