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/. */
5
6/**
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
10 */
11
12#include "nsISupports.idl"
13
14interface nsIContentSecurityPolicy;
15interface nsIMutableArray;
16interface nsILayoutHistoryState;
17interface nsIContentViewer;
18interface nsIURI;
19interface nsIInputStream;
20interface nsIDocShellTreeItem;
21interface nsIStructuredCloneContainer;
22interface nsIBFCacheEntry;
23interface nsIPrincipal;
24interface nsISHistory;
25interface nsIReferrerInfo;
26
27%{C++
28#include "nsRect.h"
29class nsDocShellEditorData;
30
31namespace mozilla {
32namespace dom {
33
34class SHEntrySharedParentState;
35
36}
37}
38class nsSHEntryShared;
39class nsDocShellLoadState;
40struct EntriesAndBrowsingContextData;
41%}
42[ref] native nsIntRect(nsIntRect);
43[ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);
44[ptr] native nsDocShellLoadStatePtr(nsDocShellLoadState);
45[ptr] native SHEntrySharedParentStatePtr(mozilla::dom::SHEntrySharedParentState);
46webidl BrowsingContext;
47
48[builtinclass, scriptable, uuid(0dad26b8-a259-42c7-93f1-2fa7fc076e45)]
49interface nsISHEntry : nsISupports
50{
51    /**
52     * The URI of the current entry.
53     */
54    [infallible] attribute nsIURI URI;
55
56    /**
57     * The original URI of the current entry. If an entry is the result of a
58     * redirect this attribute holds the original URI.
59     */
60    [infallible] attribute nsIURI originalURI;
61
62    /**
63     * URL as stored from nsILoadInfo.resultPrincipalURI.  See nsILoadInfo
64     * for more details.
65     */
66    [infallible] attribute nsIURI resultPrincipalURI;
67
68    /**
69     *  This flag remembers whether channel has LOAD_REPLACE set.
70     */
71    [infallible] attribute boolean loadReplace;
72
73    /**
74     * The title of the current entry.
75     */
76    // XXX: make it [infallible] when AString supports that (bug 1491187).
77    attribute AString title;
78
79    /**
80     * The name of the browsing context.
81     */
82    attribute AString name;
83
84    /**
85     * Was the entry created as a result of a subframe navigation?
86     * - Will be 'false' when a frameset page is visited for the first time.
87     * - Will be 'true' for all history entries created as a result of a
88     *   subframe navigation.
89     */
90    [infallible] attribute boolean isSubFrame;
91
92    /**
93     * Whether the user interacted with the page while this entry was active.
94     * This includes interactions with subframe documents associated with
95     * child entries that are rooted at this entry.
96     * This field will only be set on top-level entries.
97     */
98    [infallible] attribute boolean hasUserInteraction;
99
100    /**
101     * Whether the load that created this entry was triggered by user activation.
102     * (e.g.: The user clicked a link)
103     * Remembering this flag enables replaying the sec-fetch-* headers.
104     */
105    [infallible] attribute boolean hasUserActivation;
106
107    /** Referrer Info*/
108    [infallible] attribute nsIReferrerInfo referrerInfo;
109
110    /** Content viewer, for fast restoration of presentation */
111    [infallible] attribute nsIContentViewer contentViewer;
112
113    [infallible] readonly attribute boolean isInBFCache;
114
115    /** Whether the content viewer is marked "sticky" */
116    [infallible] attribute boolean sticky;
117
118    /** Saved state of the global window object */
119    [infallible] attribute nsISupports windowState;
120
121    /** Saved refresh URI list for the content viewer */
122    [infallible] attribute nsIMutableArray refreshURIList;
123
124    /** Post Data for the document */
125    [infallible] attribute nsIInputStream postData;
126
127    /** LayoutHistoryState for scroll position and form values */
128    [infallible] attribute nsILayoutHistoryState layoutHistoryState;
129
130    /** parent of this entry */
131    [infallible] attribute nsISHEntry parent;
132
133    /**
134     * The loadType for this entry. This is typically loadHistory except
135     * when reload is pressed, it has the appropriate reload flag
136     */
137    [infallible] attribute unsigned long loadType;
138
139    /**
140     * An ID to help identify this entry from others during
141     * subframe navigation
142     */
143    [infallible] attribute unsigned long ID;
144
145    /** The cache key for the entry */
146    [infallible] attribute unsigned long cacheKey;
147
148    /** Should the layoutHistoryState be saved? */
149    [infallible] attribute boolean saveLayoutStateFlag;
150
151    /**
152     * attribute to indicate the content-type of the document that this
153     * is a session history entry for
154     */
155    // XXX: make it [infallible] when ACString supports that (bug 1491187).
156    attribute ACString contentType;
157
158    /**
159     * If we created this SHEntry via history.pushState or modified it via
160     * history.replaceState, and if we changed the SHEntry's URI via the
161     * push/replaceState call, and if the SHEntry's new URI differs from its
162     * old URI by more than just the hash, then we set this field to true.
163     *
164     * Additionally, if this SHEntry was created by calling pushState from a
165     * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
166     * true.
167     */
168    [infallible] attribute boolean URIWasModified;
169
170    /**
171     * Get the principal, if any, that was associated with the channel
172     * that the document that was loaded to create this history entry
173     * came from.
174     */
175    [infallible] attribute nsIPrincipal triggeringPrincipal;
176
177    /**
178     * Get the principal, if any, that is used when the inherit flag
179     * is set.
180     */
181    [infallible] attribute nsIPrincipal principalToInherit;
182
183    /**
184     * Get the storage principal, if any, that is used when the inherit flag is
185     * set.
186     */
187    [infallible] attribute nsIPrincipal partitionedPrincipalToInherit;
188
189    /**
190     * Get the csp, if any, that was used for this document load. That
191     * is not the CSP that was applied to subresource loads within the
192     * document, but the CSP that was applied to this document load.
193     */
194    [infallible] attribute nsIContentSecurityPolicy csp;
195
196    /**
197     * Get/set data associated with this history state via a pushState() call,
198     * serialized using structured clone.
199     **/
200    [infallible] attribute nsIStructuredCloneContainer stateData;
201
202    /**
203     * The history ID of the docshell.
204     */
205    // Would be [infallible], but we don't support that property for nsIDPtr.
206    attribute nsIDRef docshellID;
207
208    /**
209     * True if this SHEntry corresponds to a document created by a srcdoc
210     * iframe. Set when a value is assigned to srcdocData.
211     */
212    [infallible] readonly attribute boolean isSrcdocEntry;
213
214    /**
215     * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
216     * of the URI.  Similar to a Data URI, this information is needed to
217     * recreate the document at a later stage.
218     * Setting this sets isSrcdocEntry to true
219     */
220    // XXX: make it [infallible] when AString supports that (bug 1491187).
221    attribute AString srcdocData;
222
223    /**
224     * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
225     * document for use in situations where it cannot otherwise be determined,
226     * for example with view-source.
227     */
228    [infallible] attribute nsIURI baseURI;
229
230    /**
231     * Sets/gets the current scroll restoration state,
232     * if true == "manual", false == "auto".
233     */
234    [infallible] attribute boolean scrollRestorationIsManual;
235
236    /**
237     * Flag to indicate that the history entry was originally loaded in the
238     * current process. This flag does not survive a browser process switch.
239     */
240    [infallible] readonly attribute boolean loadedInThisProcess;
241
242    /**
243     * The session history it belongs to. This is set only on the root entries.
244     */
245    [noscript, infallible] attribute nsISHistory shistory;
246
247    /**
248     * A number that is assigned by the sHistory when the entry is activated
249     */
250    [noscript, infallible] attribute unsigned long lastTouched;
251
252    /**
253     * The current number of nsISHEntries which are immediate children of this
254     * SHEntry.
255     */
256    [infallible] readonly attribute long childCount;
257
258    /**
259     * When an entry is serving is within nsISHistory's array of entries, this
260     * property specifies if it should persist. If not it will be replaced by
261     * new additions to the list.
262     */
263    [infallible] attribute boolean persist;
264
265    /**
266     * Set/Get the visual viewport scroll position if session history is
267     * changed through anchor navigation or pushState.
268     */
269    void setScrollPosition(in long x, in long y);
270    void getScrollPosition(out long x, out long y);
271
272    /**
273     * Saved position and dimensions of the content viewer; we must adjust the
274     * root view's widget accordingly if this has changed when the presentation
275     * is restored.
276     */
277    [noscript, notxpcom] void getViewerBounds(in nsIntRect bounds);
278    [noscript, notxpcom] void setViewerBounds([const] in nsIntRect bounds);
279
280    /**
281     * Saved child docshells corresponding to contentViewer.  The child shells
282     * are restored as children of the parent docshell, in this order, when the
283     * parent docshell restores a saved presentation.
284     */
285
286    /** Append a child shell to the end of our list. */
287    [noscript, notxpcom] void addChildShell(in nsIDocShellTreeItem shell);
288
289    /**
290     * Get the child shell at |index|; returns null if |index| is out of bounds.
291     */
292    [noscript] nsIDocShellTreeItem childShellAt(in long index);
293
294    /**
295     * Clear the child shell list.
296     */
297    [noscript, notxpcom] void clearChildShells();
298
299    /**
300     * Ensure that the cached presentation members are self-consistent.
301     * If either |contentViewer| or |windowState| are null, then all of the
302     * following members are cleared/reset:
303     *  contentViewer, sticky, windowState, viewerBounds, childShells,
304     *  refreshURIList.
305     */
306    [noscript, notxpcom] void syncPresentationState();
307
308    /**
309     * Initialises `layoutHistoryState` if it doesn't already exist
310     * and returns a reference to it.
311     */
312    nsILayoutHistoryState initLayoutHistoryState();
313
314    /** Additional ways to create an entry */
315    [noscript] void create(in nsIURI URI, in AString title,
316                           in nsIInputStream inputStream,
317                           in unsigned long cacheKey,
318                           in ACString contentType,
319                           in nsIPrincipal triggeringPrincipal,
320                           in nsIPrincipal principalToInherit,
321                           in nsIPrincipal partitionedPrincipalToInherit,
322                           in nsIContentSecurityPolicy aCsp,
323                           in nsIDRef docshellID,
324                           in boolean dynamicCreation,
325                           in nsIURI originalURI,
326                           in nsIURI resultPrincipalURI,
327                           in bool loadReplace,
328                           in nsIReferrerInfo referrerInfo,
329                           in AString srcdoc,
330                           in bool srcdocEntry,
331                           in nsIURI baseURI,
332                           in bool saveLayoutState,
333                           in bool expired,
334                           in bool userActivation);
335
336    nsISHEntry clone();
337
338    /**
339     * Gets the owning pointer to the editor data assosicated with
340     * this shistory entry. This forgets its pointer, so free it when
341     * you're done.
342     */
343    [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
344
345    /**
346     * Sets the owning pointer to the editor data assosicated with
347     * this shistory entry. Unless forgetEditorData() is called, this
348     * shentry will destroy the editor data when it's destroyed.
349     */
350    [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
351
352    /** Returns true if this shistory entry is storing a detached editor. */
353    [noscript, notxpcom] boolean hasDetachedEditor();
354
355    /**
356     * Returns true if the related docshell was added because of
357     * dynamic addition of an iframe/frame.
358     */
359    [noscript, notxpcom] boolean isDynamicallyAdded();
360
361    /**
362     * Returns true if any of the child entries returns true
363     * when isDynamicallyAdded is called on it.
364     */
365    boolean hasDynamicallyAddedChild();
366
367    /**
368     * Does this SHEntry point to the given BFCache entry? If so, evicting
369     * the BFCache entry will evict the SHEntry, since the two entries
370     * correspond to the same document.
371     */
372    [noscript, notxpcom]
373    boolean hasBFCacheEntry(in SHEntrySharedParentStatePtr aEntry);
374
375    /**
376     * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
377     * aEntry's BFCacheEntry.
378     */
379    void adoptBFCacheEntry(in nsISHEntry aEntry);
380
381    /**
382     * Create a new BFCache entry and drop our reference to our old one. This
383     * call unlinks this SHEntry from any other SHEntries for its document.
384     */
385    void abandonBFCacheEntry();
386
387    /**
388     * Does this SHEntry correspond to the same document as aEntry? This is
389     * true iff the two SHEntries have the same BFCacheEntry. So in particular,
390     * sharesDocumentWith(aEntry) is guaranteed to return true if it's
391     * preceded by a call to adoptBFCacheEntry(aEntry).
392     */
393    boolean sharesDocumentWith(in nsISHEntry aEntry);
394
395    /**
396     * Sets an SHEntry to reflect that it is a history type load. This is the
397     * equivalent to doing
398     *
399     * shEntry.loadType = 4;
400     *
401     * in js, but is easier to maintain and less opaque.
402     */
403    void setLoadTypeAsHistory();
404
405    /**
406     * Add a new child SHEntry. If offset is -1 adds to the end of the list.
407     */
408    void AddChild(in nsISHEntry aChild, in long aOffset,
409                  [optional,default(false)] in bool aUseRemoteSubframes);
410
411    /**
412     * Remove a child SHEntry.
413     */
414    [noscript] void RemoveChild(in nsISHEntry aChild);
415
416    /**
417     * Get child at an index.
418     */
419    nsISHEntry GetChildAt(in long aIndex);
420
421    /**
422     * If this entry has no dynamically added child, get the child SHEntry
423     * at the given offset. The loadtype of the returned entry is set
424     * to its parent's loadtype.
425     */
426    [notxpcom] void GetChildSHEntryIfHasNoDynamicallyAddedChild(in long aChildOffset,
427                                                                out nsISHEntry aChild);
428
429    /**
430     * Replaces a child which is for the same docshell as aNewChild
431     * with aNewChild.
432     * @throw if nothing was replaced.
433     */
434    [noscript] void ReplaceChild(in nsISHEntry aNewChild);
435
436    /**
437    * Remove all children of this entry and call abandonBFCacheEntry.
438    */
439    [notxpcom] void ClearEntry();
440
441    /**
442     * Create nsDocShellLoadState and fill it with information.
443     * Don't set nsSHEntry here to avoid serializing it.
444     */
445    [noscript] nsDocShellLoadStatePtr CreateLoadInfo();
446
447    [infallible] readonly attribute unsigned long long bfcacheID;
448
449    /**
450     * Sync up the docshell and session history trees for subframe navigation.
451     *
452     * @param aEntry                    new entry
453     * @param aTopBC                    top BC corresponding to the root ancestor
454                                        of the docshell that called this method
455     * @param aIgnoreBC                 current BC
456     */
457    [notxpcom] void SyncTreesForSubframeNavigation(in nsISHEntry aEntry,
458                                                   in BrowsingContext aTopBC,
459                                                   in BrowsingContext aIgnoreBC);
460
461    /**
462     * If browser.history.collectWireframes is true, this will get populated
463     * with a Wireframe upon document navigation / pushState. This will only
464     * be set for nsISHEntry's accessed in the parent process with
465     * sessionHistoryInParent enabled. See Document.webidl for more details on
466     * what a Wireframe is.
467     */
468    [implicit_jscontext] readonly attribute jsval wireframe;
469};
470