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/. */
6 #include
"nsISupports.idl"
8 interface nsIBFCacheEntry
;
10 interface nsISHistoryListener
;
12 webidl BrowsingContext
;
15 #include
"nsTArrayForwardDeclare.h"
16 #include
"mozilla/Maybe.h"
17 struct EntriesAndBrowsingContextData
;
20 class SHEntrySharedParentState
;
22 } // namespace mozilla
25 [ref] native nsDocshellIDArray
(nsTArray
<nsID
>);
26 native MaybeInt32
(mozilla
::Maybe<int32_t
>);
27 [ptr] native SHEntrySharedParentStatePtr
(mozilla
::dom
::SHEntrySharedParentState
);
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.
39 [builtinclass
, scriptable
, uuid(7b807041
-e60a
-4384-935f
-af3061d8b815
)]
40 interface nsISHistory
: nsISupports
43 * A readonly property of the interface that returns
44 * the number of toplevel documents currently available
47 [infallible
] readonly attribute
long count
;
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.
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.
61 [infallible
] readonly attribute
long requestedIndex
;
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
69 void internalSetRequestedIndex
(in long aRequestedIndex
);
72 * Get the history entry at a given index. Returns non-null on success.
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.
78 nsISHEntry getEntryAtIndex
(in long aIndex
);
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...
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>
93 * @throws <code>NS_ERROR_FAILURE</code> numEntries is
94 * invalid or out of bounds with the size of history.
96 void purgeHistory
(in long aNumEntries
);
99 * Called to register a listener for the session history component.
100 * Listeners are notified when pages are loaded or purged from history.
102 * @param aListener Listener object to be notified for all
103 * page loads that initiate in session history.
105 * @note A listener object must implement
106 * nsISHistoryListener and nsSupportsWeakReference
108 * @see nsISHistoryListener
109 * @see nsSupportsWeakReference
111 void addSHistoryListener
(in nsISHistoryListener aListener
);
114 * Called to remove a listener for the session history component.
115 * Listeners are notified when pages are loaded from history.
117 * @param aListener Listener object to be removed from
120 * @note A listener object must implement
121 * nsISHistoryListener and nsSupportsWeakReference
122 * @see nsISHistoryListener
123 * @see nsSupportsWeakReference
125 void removeSHistoryListener
(in nsISHistoryListener aListener
);
127 void reloadCurrentEntry
();
130 * Load the entry at the particular index.
133 void gotoIndex
(in long aIndex
, in boolean aUserActivation
);
136 * If an element exists at the particular index and
137 * whether it has user interaction.
140 boolean hasUserInteractionAtIndex
(in long aIndex
);
143 * Called to obtain the index to a given history entry.
145 * @param aEntry The entry to obtain the index of.
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.
153 long getIndexOfEntry
(in nsISHEntry aEntry
);
156 * Add a new Entry to the History List.
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.
164 void addEntry
(in nsISHEntry aEntry
, in boolean aPersist
);
167 * Update the index maintained by sessionHistory
172 * Replace the nsISHEntry at a particular index
174 * @param aIndex The index at which the entry should be replaced.
175 * @param aReplaceEntry The replacement entry for the index.
177 void replaceEntry
(in long aIndex
, in nsISHEntry aReplaceEntry
);
180 * Notifies all registered session history listeners about an impending
183 * @return Whether the operation can proceed.
185 boolean notifyOnHistoryReload
();
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.
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.
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
200 void evictOutOfRangeDocumentViewers
(in long aIndex
);
203 * Evict the content viewer associated with a bfcache entry that has timed
207 void evictExpiredDocumentViewerForEntry
(in SHEntrySharedParentStatePtr aEntry
);
210 * Evict all the content viewers in this session history
212 void evictAllDocumentViewers
();
215 * Add a BFCache entry to expiration tracker so it gets evicted on
219 void addToExpirationTracker
(in SHEntrySharedParentStatePtr aEntry
);
222 * Remove a BFCache entry from expiration tracker.
225 void removeFromExpirationTracker
(in SHEntrySharedParentStatePtr aEntry
);
228 * Remove dynamic entries found at given index.
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.
238 void RemoveDynEntries
(in long aIndex
, in nsISHEntry aEntry
);
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
245 * The method takes no effect if the bfcache entry is not or no longer hold
246 * by the SHistory instance.
248 * @param aEntry The bfcache entry to look up for index to remove
249 * dynamic entries from.
252 void RemoveDynEntriesForBFCacheEntry
(in nsIBFCacheEntry aEntry
);
255 * Removes entries from the history if their docshellID is in
259 void RemoveEntries
(in nsDocshellIDArray aIDs
, in long aStartIndex
);
262 * Collect docshellIDs from aEntry's children and remove those
263 * entries from history.
265 * @param aEntry Children docshellID's will be collected from
266 * this entry and passed to RemoveEntries as aIDs.
269 void RemoveFrameEntries
(in nsISHEntry aEntry
);
272 void Reload
(in unsigned long aReloadFlags
);
274 [notxpcom
] void EnsureCorrectEntryAtCurrIndex
(in nsISHEntry aEntry
);
276 [notxpcom
] void EvictDocumentViewersOrReplaceEntry
(in nsISHEntry aNewSHEntry
, in bool aReplace
);
278 nsISHEntry createEntry
();
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
);
287 [noscript
] void AddChildSHEntryHelper
(in nsISHEntry aCloneRef
, in nsISHEntry aNewEntry
,
288 in BrowsingContext aRootBC
, in bool aCloneChildren
);
290 [noscript
, notxpcom
] boolean isEmptyOrHasEntriesForSingleTopLevelPage
();