summaryrefslogtreecommitdiffstats
path: root/docshell/shistory/nsISHistory.idl
blob: 9ca237c67018eeb86b414c4eeed679404a6be640 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIBFCacheEntry;
interface nsISHEntry;
interface nsISHistoryListener;
interface nsIURI;
webidl BrowsingContext;

%{C++
#include "nsTArrayForwardDeclare.h"
#include "mozilla/Maybe.h"
struct EntriesAndBrowsingContextData;
namespace mozilla {
namespace dom {
class SHEntrySharedParentState;
} // namespace dom
} // namespace mozilla
%}

[ref] native nsDocshellIDArray(nsTArray<nsID>);
native MaybeInt32(mozilla::Maybe<int32_t>);
[ptr] native SHEntrySharedParentStatePtr(mozilla::dom::SHEntrySharedParentState);
/**
 * An interface to the primary properties of the Session History
 * component. In an embedded browser environment, the nsIWebBrowser
 * object creates an instance of session history for each open window.
 * A handle to the session history object can be obtained from
 * nsIWebNavigation. In a non-embedded situation, the  owner of the
 * session history component must create a instance of it and set
 * it in the nsIWebNavigation object.
 * This interface is accessible from javascript.
 */

[builtinclass, scriptable, uuid(7b807041-e60a-4384-935f-af3061d8b815)]
interface nsISHistory: nsISupports
{
  /**
   * A readonly property of the interface that returns
   * the number of toplevel documents currently available
   * in session history.
   */
  [infallible] readonly attribute long count;

  /**
   * The index of the current document in session history. Not infallible
   * because setting can fail if the assigned value is out of range.
   */
  attribute long index;

  /**
   * A readonly property of the interface that returns
   * the index of the last document that started to load and
   * didn't finished yet. When document finishes the loading
   * value -1 is returned.
   */
  [infallible] readonly attribute long requestedIndex;

  /**
   * Artifically set the |requestedIndex| for this nsISHEntry to the given
   * index. This is used when resuming a cross-process load from a different
   * process.
   */
  [noscript, notxpcom]
  void internalSetRequestedIndex(in long aRequestedIndex);

  /**
   * Get the history entry at a given index. Returns non-null on success.
   *
   * @param index             The index value whose entry is requested.
   *                          The oldest entry is located at index == 0.
   * @return                  The found entry; never null.
   */
  nsISHEntry getEntryAtIndex(in long aIndex);

  /**
   * Called to purge older documents from history.
   * Documents can be removed from session history for various
   * reasons. For example to  control memory usage of the browser, to
   * prevent users from loading documents from history, to erase evidence of
   * prior page loads etc...
   *
   * @param numEntries        The number of toplevel documents to be
   *                          purged from history. During purge operation,
   *                          the latest documents are maintained and older
   *                          'numEntries' documents are removed from history.
   * @throws                  <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code>
   *                          Purge was vetod.
   * @throws                  <code>NS_ERROR_FAILURE</code> numEntries is
   *                          invalid or out of bounds with the size of history.
   */
  void purgeHistory(in long aNumEntries);

  /**
   * Called to register a listener for the session history component.
   * Listeners are notified when pages are loaded or purged from history.
   *
   * @param aListener         Listener object to be notified for all
   *                          page loads that initiate in session history.
   *
   * @note                    A listener object must implement
   *                          nsISHistoryListener and nsSupportsWeakReference
   *
   * @see nsISHistoryListener
   * @see nsSupportsWeakReference
   */
  void addSHistoryListener(in nsISHistoryListener aListener);

  /**
   * Called to remove a listener for the session history component.
   * Listeners are notified when pages are loaded from history.
   *
   * @param aListener         Listener object to be removed from
   *                          session history.
   *
   * @note                    A listener object must implement
   *                          nsISHistoryListener and nsSupportsWeakReference
   * @see nsISHistoryListener
   * @see nsSupportsWeakReference
   */
  void removeSHistoryListener(in nsISHistoryListener aListener);

  void reloadCurrentEntry();

  /**
   * Load the entry at the particular index.
   */
  [noscript]
  void gotoIndex(in long aIndex, in boolean aUserActivation);

  /**
   * If an element exists at the particular index and
   * whether it has user interaction.
   */
  [noscript,notxpcom]
  boolean hasUserInteractionAtIndex(in long aIndex);

  /**
   * Called to obtain the index to a given history entry.
   *
   * @param aEntry            The entry to obtain the index of.
   *
   * @return                  <code>NS_OK</code> index for the history entry
   *                          is obtained successfully.
   *                          <code>NS_ERROR_FAILURE</code> Error in obtaining
   *                          index for the given history entry.
   */
  [noscript, notxpcom]
  long getIndexOfEntry(in nsISHEntry aEntry);

  /**
   * Add a new Entry to the History List.
   *
   * @param aEntry            The entry to add.
   * @param aPersist          If true this specifies that the entry should
   *                          persist in the list. If false, this means that
   *                          when new entries are added this element will not
   *                          appear in the session history list.
   */
  void addEntry(in nsISHEntry aEntry, in boolean aPersist);

  /**
   * Update the index maintained by sessionHistory
   */
  void updateIndex();

  /**
   * Replace the nsISHEntry at a particular index
   *
   * @param aIndex            The index at which the entry should be replaced.
   * @param aReplaceEntry     The replacement entry for the index.
   */
  void replaceEntry(in long aIndex, in nsISHEntry aReplaceEntry);

  /**
   * Notifies all registered session history listeners about an impending
   * reload.
   *
   * @return                  Whether the operation can proceed.
   */
  boolean notifyOnHistoryReload();

  /**
   * Evict content viewers which don't lie in the "safe" range around aIndex.
   * In practice, this should leave us with no more than gHistoryMaxViewers
   * viewers associated with this SHistory object.
   *
   * Also make sure that the total number of content viewers in all windows is
   * not greater than our global max; if it is, evict viewers as appropriate.
   *
   * @param aIndex           The index around which the "safe" range is
   *                         centered.  In general, if you just navigated the
   *                         history, aIndex should be the index history was
   *                         navigated to.
   */
  void evictOutOfRangeDocumentViewers(in long aIndex);

  /**
   * Evict the content viewer associated with a bfcache entry that has timed
   * out.
   */
  [noscript, notxpcom]
  void evictExpiredDocumentViewerForEntry(in SHEntrySharedParentStatePtr aEntry);

  /**
   * Evict all the content viewers in this session history
   */
  void evictAllDocumentViewers();

  /**
   * Add a BFCache entry to expiration tracker so it gets evicted on
   * expiration.
   */
  [noscript, notxpcom]
  void addToExpirationTracker(in SHEntrySharedParentStatePtr aEntry);

  /**
   * Remove a BFCache entry from expiration tracker.
   */
  [noscript, notxpcom]
  void removeFromExpirationTracker(in SHEntrySharedParentStatePtr aEntry);

  /**
   * Remove dynamic entries found at given index.
   *
   * @param aIndex           Index to remove dynamic entries from. It will be
   *                         passed to RemoveEntries as aStartIndex.
   * @param aEntry (optional)  The entry to start looking in for dynamic
   *                         entries. Only the dynamic descendants of the
   *                         entry will be removed. If not given, all dynamic
   *                         entries at the index will be removed.
   */
  [noscript, notxpcom]
  void RemoveDynEntries(in long aIndex, in nsISHEntry aEntry);

  /**
   * Similar to RemoveDynEntries, but instead of specifying an index, use the
   * given BFCacheEntry to find the index and remove dynamic entries from the
   * index.
   *
   * The method takes no effect if the bfcache entry is not or no longer hold
   * by the SHistory instance.
   *
   * @param aEntry           The bfcache entry to look up for index to remove
   *                         dynamic entries from.
   */
  [noscript, notxpcom]
  void RemoveDynEntriesForBFCacheEntry(in nsIBFCacheEntry aEntry);

  /**
   * Removes entries from the history if their docshellID is in
   * aIDs array.
   */
  [noscript, notxpcom]
  void RemoveEntries(in nsDocshellIDArray aIDs, in long aStartIndex);

  /**
   * Collect docshellIDs from aEntry's children and remove those
   * entries from history.
   *
   * @param aEntry           Children docshellID's will be collected from
   *                         this entry and passed to RemoveEntries as aIDs.
  */
  [noscript, notxpcom]
  void RemoveFrameEntries(in nsISHEntry aEntry);

  [noscript]
  void Reload(in unsigned long aReloadFlags);

  [notxpcom] void EnsureCorrectEntryAtCurrIndex(in nsISHEntry aEntry);

  [notxpcom] void EvictDocumentViewersOrReplaceEntry(in nsISHEntry aNewSHEntry, in bool aReplace);

  nsISHEntry createEntry();

  [noscript] void AddToRootSessionHistory(in bool aCloneChildren, in nsISHEntry aOSHE,
                                          in BrowsingContext aRootBC, in nsISHEntry aEntry,
                                          in unsigned long aLoadType,
                                          in bool aShouldPersist,
                                          out MaybeInt32 aPreviousEntryIndex,
                                          out MaybeInt32 aLoadedEntryIndex);

  [noscript] void AddChildSHEntryHelper(in nsISHEntry aCloneRef, in nsISHEntry aNewEntry,
                                        in BrowsingContext aRootBC, in bool aCloneChildren);

  [noscript, notxpcom] boolean isEmptyOrHasEntriesForSingleTopLevelPage();
};