nsISHistory.idl (10695B)
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 [can_run_script] 128 void reloadCurrentEntry(); 129 130 /** 131 * Load the entry at the particular index. 132 */ 133 [noscript, can_run_script] 134 void gotoIndex(in long aIndex, in boolean aUserActivation); 135 136 /** 137 * If an element exists at the particular index and 138 * whether it has user interaction. 139 */ 140 [noscript,notxpcom] 141 boolean hasUserInteractionAtIndex(in long aIndex); 142 143 /** 144 * Called to obtain the index to a given history entry. 145 * 146 * @param aEntry The entry to obtain the index of. 147 * 148 * @return <code>NS_OK</code> index for the history entry 149 * is obtained successfully. 150 * <code>NS_ERROR_FAILURE</code> Error in obtaining 151 * index for the given history entry. 152 */ 153 [noscript, notxpcom] 154 long getIndexOfEntry(in nsISHEntry aEntry); 155 156 /** 157 * Add a new Entry to the History List. 158 * 159 * @param aEntry The entry to add. 160 */ 161 void addEntry(in nsISHEntry aEntry); 162 163 /** 164 * Update the index maintained by sessionHistory 165 */ 166 void updateIndex(); 167 168 /** 169 * Replace the nsISHEntry at a particular index 170 * 171 * @param aIndex The index at which the entry should be replaced. 172 * @param aReplaceEntry The replacement entry for the index. 173 */ 174 void replaceEntry(in long aIndex, in nsISHEntry aReplaceEntry); 175 176 /** 177 * Notifies all registered session history listeners about an impending 178 * reload. 179 * 180 * @return Whether the operation can proceed. 181 */ 182 boolean notifyOnHistoryReload(); 183 184 /** 185 * Evict content viewers which don't lie in the "safe" range around aIndex. 186 * In practice, this should leave us with no more than gHistoryMaxViewers 187 * viewers associated with this SHistory object. 188 * 189 * Also make sure that the total number of content viewers in all windows is 190 * not greater than our global max; if it is, evict viewers as appropriate. 191 * 192 * @param aIndex The index around which the "safe" range is 193 * centered. In general, if you just navigated the 194 * history, aIndex should be the index history was 195 * navigated to. 196 */ 197 void evictOutOfRangeDocumentViewers(in long aIndex); 198 199 /** 200 * Evict the content viewer associated with a bfcache entry that has timed 201 * out. 202 */ 203 [noscript, notxpcom] 204 void evictExpiredDocumentViewerForEntry(in SHEntrySharedParentStatePtr aEntry); 205 206 /** 207 * Evict all the content viewers in this session history 208 */ 209 void evictAllDocumentViewers(); 210 211 /** 212 * Add a BFCache entry to expiration tracker so it gets evicted on 213 * expiration. 214 */ 215 [noscript, notxpcom] 216 void addToExpirationTracker(in SHEntrySharedParentStatePtr aEntry); 217 218 /** 219 * Remove a BFCache entry from expiration tracker. 220 */ 221 [noscript, notxpcom] 222 void removeFromExpirationTracker(in SHEntrySharedParentStatePtr aEntry); 223 224 /** 225 * Remove dynamic entries found at given index. 226 * 227 * @param aIndex Index to remove dynamic entries from. It will be 228 * passed to RemoveEntries as aStartIndex. 229 * @param aEntry (optional) The entry to start looking in for dynamic 230 * entries. Only the dynamic descendants of the 231 * entry will be removed. If not given, all dynamic 232 * entries at the index will be removed. 233 */ 234 [noscript, notxpcom] 235 void RemoveDynEntries(in long aIndex, in nsISHEntry aEntry); 236 237 /** 238 * Similar to RemoveDynEntries, but instead of specifying an index, use the 239 * given BFCacheEntry to find the index and remove dynamic entries from the 240 * index. 241 * 242 * The method takes no effect if the bfcache entry is not or no longer hold 243 * by the SHistory instance. 244 * 245 * @param aEntry The bfcache entry to look up for index to remove 246 * dynamic entries from. 247 */ 248 [noscript, notxpcom] 249 void RemoveDynEntriesForBFCacheEntry(in nsIBFCacheEntry aEntry); 250 251 /** 252 * Removes entries from the history if their docshellID is in 253 * aIDs array. 254 */ 255 [noscript, notxpcom] 256 void RemoveEntries(in nsDocshellIDArray aIDs, in long aStartIndex); 257 258 /** 259 * Collect docshellIDs from aEntry's children and remove those 260 * entries from history. 261 * 262 * @param aEntry Children docshellID's will be collected from 263 * this entry and passed to RemoveEntries as aIDs. 264 */ 265 [noscript, notxpcom] 266 void RemoveFrameEntries(in nsISHEntry aEntry); 267 268 [can_run_script] void reload(in unsigned long aReloadFlags); 269 270 [notxpcom] void EnsureCorrectEntryAtCurrIndex(in nsISHEntry aEntry); 271 272 [notxpcom] void EvictDocumentViewersOrReplaceEntry(in nsISHEntry aNewSHEntry, in boolean aReplace); 273 274 nsISHEntry createEntry(); 275 276 [noscript] void AddToRootSessionHistory(in boolean aCloneChildren, in nsISHEntry aOSHE, 277 in BrowsingContext aRootBC, in nsISHEntry aEntry, 278 in unsigned long aLoadType, 279 out MaybeInt32 aPreviousEntryIndex, 280 out MaybeInt32 aLoadedEntryIndex); 281 282 /** 283 * Add the new entry aNewEntry for the docshell that is associated with aOldEntry. 284 * 285 * If aOldEntry is transient, it will be replaced by aNewEntry. Otherwise, a new top-level entry 286 * is created. 287 * 288 * @param aCloneChildren whether aNewEntry should have the same child SH entries as aOldEntry 289 */ 290 [noscript] void AddNestedSHEntry(in nsISHEntry aOldEntry, in nsISHEntry aNewEntry, 291 in BrowsingContext aRootBC, in boolean aCloneChildren); 292 293 /** 294 * Determine if we can navigate back in history from the entry at aIndex 295 * to an entry that has user interaction. 296 */ 297 boolean canGoBackFromEntryAtIndex(in long aIndex); 298 };