1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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/. */
7 * The interface to nsISHentry. Each document or subframe in
8 * Session History will have a nsISHEntry associated with it which will
9 * hold all information required to recreate the document from history
12 #include
"nsISupports.idl"
14 interface nsIContentSecurityPolicy
;
15 interface nsIMutableArray
;
16 interface nsILayoutHistoryState
;
17 interface nsIContentViewer
;
19 interface nsIInputStream
;
20 interface nsIDocShellTreeItem
;
21 interface nsIStructuredCloneContainer
;
22 interface nsIBFCacheEntry
;
23 interface nsIPrincipal
;
24 interface nsISHistory
;
25 interface nsIReferrerInfo
;
29 class nsDocShellEditorData
;
34 class SHEntrySharedParentState
;
38 class nsSHEntryShared
;
39 class nsDocShellLoadState
;
40 struct EntriesAndBrowsingContextData
;
42 [ref] native nsIntRect
(nsIntRect
);
43 [ptr] native nsDocShellEditorDataPtr
(nsDocShellEditorData
);
44 [ptr] native nsDocShellLoadStatePtr
(nsDocShellLoadState
);
45 [ptr] native SHEntrySharedParentStatePtr
(mozilla
::dom
::SHEntrySharedParentState
);
46 webidl BrowsingContext
;
48 [builtinclass
, scriptable
, uuid(0dad26b8
-a259
-42c7
-93f1
-2fa7fc076e45
)]
49 interface nsISHEntry
: nsISupports
52 * The URI of the current entry.
54 [infallible
] attribute nsIURI URI
;
57 * The original URI of the current entry. If an entry is the result of a
58 * redirect this attribute holds the original URI.
60 [infallible
] attribute nsIURI originalURI
;
63 * URL as stored from nsILoadInfo.resultPrincipalURI. See nsILoadInfo
66 [infallible
] attribute nsIURI resultPrincipalURI
;
69 * If non-null, the URI as it was before query stripping was performed.
71 [infallible
] attribute nsIURI unstrippedURI
;
74 * This flag remembers whether channel has LOAD_REPLACE set.
76 [infallible
] attribute
boolean loadReplace
;
79 * The title of the current entry.
81 // XXX: make it [infallible] when AString supports that (bug 1491187).
82 attribute AString title
;
85 * The name of the browsing context.
87 attribute AString name
;
90 * Was the entry created as a result of a subframe navigation?
91 * - Will be 'false' when a frameset page is visited for the first time.
92 * - Will be 'true' for all history entries created as a result of a
93 * subframe navigation.
95 [infallible
] attribute
boolean isSubFrame
;
98 * Whether the user interacted with the page while this entry was active.
99 * This includes interactions with subframe documents associated with
100 * child entries that are rooted at this entry.
101 * This field will only be set on top-level entries.
103 [infallible
] attribute
boolean hasUserInteraction
;
106 * Whether the load that created this entry was triggered by user activation.
107 * (e.g.: The user clicked a link)
108 * Remembering this flag enables replaying the sec-fetch-* headers.
110 [infallible
] attribute
boolean hasUserActivation
;
113 [infallible
] attribute nsIReferrerInfo referrerInfo
;
115 /** Content viewer, for fast restoration of presentation */
116 [infallible
] attribute nsIContentViewer contentViewer
;
118 [infallible
] readonly attribute
boolean isInBFCache
;
120 /** Whether the content viewer is marked "sticky" */
121 [infallible
] attribute
boolean sticky
;
123 /** Saved state of the global window object */
124 [infallible
] attribute nsISupports windowState
;
126 /** Saved refresh URI list for the content viewer */
127 [infallible
] attribute nsIMutableArray refreshURIList
;
129 /** Post Data for the document */
130 [infallible
] attribute nsIInputStream postData
;
132 /** LayoutHistoryState for scroll position and form values */
133 [infallible
] attribute nsILayoutHistoryState layoutHistoryState
;
135 /** parent of this entry */
136 [infallible
] attribute nsISHEntry parent
;
139 * The loadType for this entry. This is typically loadHistory except
140 * when reload is pressed, it has the appropriate reload flag
142 [infallible
] attribute
unsigned long loadType
;
145 * An ID to help identify this entry from others during
146 * subframe navigation
148 [infallible
] attribute
unsigned long ID;
150 /** The cache key for the entry */
151 [infallible
] attribute
unsigned long cacheKey
;
153 /** Should the layoutHistoryState be saved? */
154 [infallible
] attribute
boolean saveLayoutStateFlag
;
157 * attribute to indicate the content-type of the document that this
158 * is a session history entry for
160 // XXX: make it [infallible] when ACString supports that (bug 1491187).
161 attribute ACString contentType
;
164 * If we created this SHEntry via history.pushState or modified it via
165 * history.replaceState, and if we changed the SHEntry's URI via the
166 * push/replaceState call, and if the SHEntry's new URI differs from its
167 * old URI by more than just the hash, then we set this field to true.
169 * Additionally, if this SHEntry was created by calling pushState from a
170 * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
173 [infallible
] attribute
boolean URIWasModified
;
176 * Get the principal, if any, that was associated with the channel
177 * that the document that was loaded to create this history entry
180 [infallible
] attribute nsIPrincipal triggeringPrincipal
;
183 * Get the principal, if any, that is used when the inherit flag
186 [infallible
] attribute nsIPrincipal principalToInherit
;
189 * Get the storage principal, if any, that is used when the inherit flag is
192 [infallible
] attribute nsIPrincipal partitionedPrincipalToInherit
;
195 * Get the csp, if any, that was used for this document load. That
196 * is not the CSP that was applied to subresource loads within the
197 * document, but the CSP that was applied to this document load.
199 [infallible
] attribute nsIContentSecurityPolicy csp
;
202 * Get/set data associated with this history state via a pushState() call,
203 * serialized using structured clone.
205 [infallible
] attribute nsIStructuredCloneContainer stateData
;
208 * The history ID of the docshell.
210 // Would be [infallible], but we don't support that property for nsIDPtr.
211 attribute nsIDRef docshellID
;
214 * True if this SHEntry corresponds to a document created by a srcdoc
215 * iframe. Set when a value is assigned to srcdocData.
217 [infallible
] readonly attribute
boolean isSrcdocEntry
;
220 * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
221 * of the URI. Similar to a Data URI, this information is needed to
222 * recreate the document at a later stage.
223 * Setting this sets isSrcdocEntry to true
225 // XXX: make it [infallible] when AString supports that (bug 1491187).
226 attribute AString srcdocData
;
229 * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
230 * document for use in situations where it cannot otherwise be determined,
231 * for example with view-source.
233 [infallible
] attribute nsIURI baseURI
;
236 * Sets/gets the current scroll restoration state,
237 * if true == "manual", false == "auto".
239 [infallible
] attribute
boolean scrollRestorationIsManual
;
242 * Flag to indicate that the history entry was originally loaded in the
243 * current process. This flag does not survive a browser process switch.
245 [infallible
] readonly attribute
boolean loadedInThisProcess
;
248 * The session history it belongs to. This is set only on the root entries.
250 [noscript
, infallible
] attribute nsISHistory shistory
;
253 * A number that is assigned by the sHistory when the entry is activated
255 [noscript
, infallible
] attribute
unsigned long lastTouched
;
258 * The current number of nsISHEntries which are immediate children of this
261 [infallible
] readonly attribute
long childCount
;
264 * When an entry is serving is within nsISHistory's array of entries, this
265 * property specifies if it should persist. If not it will be replaced by
266 * new additions to the list.
268 [infallible
] attribute
boolean persist
;
271 * Set/Get the visual viewport scroll position if session history is
272 * changed through anchor navigation or pushState.
274 void setScrollPosition
(in long x
, in long y
);
275 void getScrollPosition
(out long x
, out long y
);
278 * Saved position and dimensions of the content viewer; we must adjust the
279 * root view's widget accordingly if this has changed when the presentation
282 [noscript
, notxpcom
] void getViewerBounds
(in nsIntRect bounds
);
283 [noscript
, notxpcom
] void setViewerBounds
([const] in nsIntRect bounds
);
286 * Saved child docshells corresponding to contentViewer. The child shells
287 * are restored as children of the parent docshell, in this order, when the
288 * parent docshell restores a saved presentation.
291 /** Append a child shell to the end of our list. */
292 [noscript
, notxpcom
] void addChildShell
(in nsIDocShellTreeItem shell
);
295 * Get the child shell at |index|; returns null if |index| is out of bounds.
297 [noscript
] nsIDocShellTreeItem childShellAt
(in long index
);
300 * Clear the child shell list.
302 [noscript
, notxpcom
] void clearChildShells
();
305 * Ensure that the cached presentation members are self-consistent.
306 * If either |contentViewer| or |windowState| are null, then all of the
307 * following members are cleared/reset:
308 * contentViewer, sticky, windowState, viewerBounds, childShells,
311 [noscript
, notxpcom
] void syncPresentationState
();
314 * Initialises `layoutHistoryState` if it doesn't already exist
315 * and returns a reference to it.
317 nsILayoutHistoryState initLayoutHistoryState
();
319 /** Additional ways to create an entry */
320 [noscript
] void create
(in nsIURI URI
, in AString title
,
321 in nsIInputStream inputStream
,
322 in unsigned long cacheKey
,
323 in ACString contentType
,
324 in nsIPrincipal triggeringPrincipal
,
325 in nsIPrincipal principalToInherit
,
326 in nsIPrincipal partitionedPrincipalToInherit
,
327 in nsIContentSecurityPolicy aCsp
,
328 in nsIDRef docshellID
,
329 in boolean dynamicCreation
,
330 in nsIURI originalURI
,
331 in nsIURI resultPrincipalURI
,
332 in nsIURI unstrippedURI
,
334 in nsIReferrerInfo referrerInfo
,
338 in bool saveLayoutState
,
340 in bool userActivation
);
345 * Gets the owning pointer to the editor data assosicated with
346 * this shistory entry. This forgets its pointer, so free it when
349 [noscript
, notxpcom
] nsDocShellEditorDataPtr forgetEditorData
();
352 * Sets the owning pointer to the editor data assosicated with
353 * this shistory entry. Unless forgetEditorData() is called, this
354 * shentry will destroy the editor data when it's destroyed.
356 [noscript
, notxpcom
] void setEditorData
(in nsDocShellEditorDataPtr aData
);
358 /** Returns true if this shistory entry is storing a detached editor. */
359 [noscript
, notxpcom
] boolean hasDetachedEditor
();
362 * Returns true if the related docshell was added because of
363 * dynamic addition of an iframe/frame.
365 [noscript
, notxpcom
] boolean isDynamicallyAdded
();
368 * Returns true if any of the child entries returns true
369 * when isDynamicallyAdded is called on it.
371 boolean hasDynamicallyAddedChild
();
374 * Does this SHEntry point to the given BFCache entry? If so, evicting
375 * the BFCache entry will evict the SHEntry, since the two entries
376 * correspond to the same document.
379 boolean hasBFCacheEntry
(in SHEntrySharedParentStatePtr aEntry
);
382 * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
383 * aEntry's BFCacheEntry.
385 void adoptBFCacheEntry
(in nsISHEntry aEntry
);
388 * Create a new BFCache entry and drop our reference to our old one. This
389 * call unlinks this SHEntry from any other SHEntries for its document.
391 void abandonBFCacheEntry
();
394 * Does this SHEntry correspond to the same document as aEntry? This is
395 * true iff the two SHEntries have the same BFCacheEntry. So in particular,
396 * sharesDocumentWith(aEntry) is guaranteed to return true if it's
397 * preceded by a call to adoptBFCacheEntry(aEntry).
399 boolean sharesDocumentWith
(in nsISHEntry aEntry
);
402 * Sets an SHEntry to reflect that it is a history type load. This is the
403 * equivalent to doing
405 * shEntry.loadType = 4;
407 * in js, but is easier to maintain and less opaque.
409 void setLoadTypeAsHistory
();
412 * Add a new child SHEntry. If offset is -1 adds to the end of the list.
414 void AddChild
(in nsISHEntry aChild
, in long aOffset
,
415 [optional,default(false
)] in bool aUseRemoteSubframes
);
418 * Remove a child SHEntry.
420 [noscript
] void RemoveChild
(in nsISHEntry aChild
);
423 * Get child at an index.
425 nsISHEntry GetChildAt
(in long aIndex
);
428 * If this entry has no dynamically added child, get the child SHEntry
429 * at the given offset. The loadtype of the returned entry is set
430 * to its parent's loadtype.
432 [notxpcom
] void GetChildSHEntryIfHasNoDynamicallyAddedChild
(in long aChildOffset
,
433 out nsISHEntry aChild
);
436 * Replaces a child which is for the same docshell as aNewChild
438 * @throw if nothing was replaced.
440 [noscript
] void ReplaceChild
(in nsISHEntry aNewChild
);
443 * Remove all children of this entry and call abandonBFCacheEntry.
445 [notxpcom
] void ClearEntry
();
448 * Create nsDocShellLoadState and fill it with information.
449 * Don't set nsSHEntry here to avoid serializing it.
451 [noscript
] nsDocShellLoadStatePtr CreateLoadInfo
();
453 [infallible
] readonly attribute
unsigned long long bfcacheID
;
456 * Sync up the docshell and session history trees for subframe navigation.
458 * @param aEntry new entry
459 * @param aTopBC top BC corresponding to the root ancestor
460 of the docshell that called this method
461 * @param aIgnoreBC current BC
463 [notxpcom
] void SyncTreesForSubframeNavigation
(in nsISHEntry aEntry
,
464 in BrowsingContext aTopBC
,
465 in BrowsingContext aIgnoreBC
);
468 * If browser.history.collectWireframes is true, this will get populated
469 * with a Wireframe upon document navigation / pushState. This will only
470 * be set for nsISHEntry's accessed in the parent process with
471 * sessionHistoryInParent enabled. See Document.webidl for more details on
472 * what a Wireframe is.
474 [implicit_jscontext
] attribute jsval wireframe
;