docshell/shistory/nsISHEntry.idl

   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
  14 interface nsIContentSecurityPolicy;
  15 interface nsIMutableArray;
  16 interface nsILayoutHistoryState;
  17 interface nsIContentViewer;
  18 interface nsIURI;
  19 interface nsIInputStream;
  20 interface nsIDocShellTreeItem;
  21 interface nsIStructuredCloneContainer;
  22 interface nsIBFCacheEntry;
  23 interface nsIPrincipal;
  24 interface nsISHistory;
  25 interface nsIReferrerInfo;
  26
  27 %{C++
  28 #include "nsRect.h"
  29 class nsDocShellEditorData;
  30
  31 namespace mozilla {
  32 namespace dom {
  33
  34 class SHEntrySharedParentState;
  35
  36 }
  37 }
  38 class nsSHEntryShared;
  39 class nsDocShellLoadState;
  40 struct EntriesAndBrowsingContextData;
  41 %}
  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;
  47
  48 [builtinclass, scriptable, uuid(0dad26b8-a259-42c7-93f1-2fa7fc076e45)]
  49 interface 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      * If non-null, the URI as it was before query stripping was performed.
  70      */
  71     [infallible] attribute nsIURI unstrippedURI;
  72
  73     /**
  74      *  This flag remembers whether channel has LOAD_REPLACE set.
  75      */
  76     [infallible] attribute boolean loadReplace;
  77
  78     /**
  79      * The title of the current entry.
  80      */
  81     // XXX: make it [infallible] when AString supports that (bug 1491187).
  82     attribute AString title;
  83
  84     /**
  85      * The name of the browsing context.
  86      */
  87     attribute AString name;
  88
  89     /**
  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.
  94      */
  95     [infallible] attribute boolean isSubFrame;
  96
  97     /**
  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.
 102      */
 103     [infallible] attribute boolean hasUserInteraction;
 104
 105     /**
 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.
 109      */
 110     [infallible] attribute boolean hasUserActivation;
 111
 112     /** Referrer Info*/
 113     [infallible] attribute nsIReferrerInfo referrerInfo;
 114
 115     /** Content viewer, for fast restoration of presentation */
 116     [infallible] attribute nsIContentViewer contentViewer;
 117
 118     [infallible] readonly attribute boolean isInBFCache;
 119
 120     /** Whether the content viewer is marked "sticky" */
 121     [infallible] attribute boolean sticky;
 122
 123     /** Saved state of the global window object */
 124     [infallible] attribute nsISupports windowState;
 125
 126     /** Saved refresh URI list for the content viewer */
 127     [infallible] attribute nsIMutableArray refreshURIList;
 128
 129     /** Post Data for the document */
 130     [infallible] attribute nsIInputStream postData;
 131
 132     /** LayoutHistoryState for scroll position and form values */
 133     [infallible] attribute nsILayoutHistoryState layoutHistoryState;
 134
 135     /** parent of this entry */
 136     [infallible] attribute nsISHEntry parent;
 137
 138     /**
 139      * The loadType for this entry. This is typically loadHistory except
 140      * when reload is pressed, it has the appropriate reload flag
 141      */
 142     [infallible] attribute unsigned long loadType;
 143
 144     /**
 145      * An ID to help identify this entry from others during
 146      * subframe navigation
 147      */
 148     [infallible] attribute unsigned long ID;
 149
 150     /** The cache key for the entry */
 151     [infallible] attribute unsigned long cacheKey;
 152
 153     /** Should the layoutHistoryState be saved? */
 154     [infallible] attribute boolean saveLayoutStateFlag;
 155
 156     /**
 157      * attribute to indicate the content-type of the document that this
 158      * is a session history entry for
 159      */
 160     // XXX: make it [infallible] when ACString supports that (bug 1491187).
 161     attribute ACString contentType;
 162
 163     /**
 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.
 168      *
 169      * Additionally, if this SHEntry was created by calling pushState from a
 170      * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
 171      * true.
 172      */
 173     [infallible] attribute boolean URIWasModified;
 174
 175     /**
 176      * Get the principal, if any, that was associated with the channel
 177      * that the document that was loaded to create this history entry
 178      * came from.
 179      */
 180     [infallible] attribute nsIPrincipal triggeringPrincipal;
 181
 182     /**
 183      * Get the principal, if any, that is used when the inherit flag
 184      * is set.
 185      */
 186     [infallible] attribute nsIPrincipal principalToInherit;
 187
 188     /**
 189      * Get the storage principal, if any, that is used when the inherit flag is
 190      * set.
 191      */
 192     [infallible] attribute nsIPrincipal partitionedPrincipalToInherit;
 193
 194     /**
 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.
 198      */
 199     [infallible] attribute nsIContentSecurityPolicy csp;
 200
 201     /**
 202      * Get/set data associated with this history state via a pushState() call,
 203      * serialized using structured clone.
 204      **/
 205     [infallible] attribute nsIStructuredCloneContainer stateData;
 206
 207     /**
 208      * The history ID of the docshell.
 209      */
 210     // Would be [infallible], but we don't support that property for nsIDPtr.
 211     attribute nsIDRef docshellID;
 212
 213     /**
 214      * True if this SHEntry corresponds to a document created by a srcdoc
 215      * iframe. Set when a value is assigned to srcdocData.
 216      */
 217     [infallible] readonly attribute boolean isSrcdocEntry;
 218
 219     /**
 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
 224      */
 225     // XXX: make it [infallible] when AString supports that (bug 1491187).
 226     attribute AString srcdocData;
 227
 228     /**
 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.
 232      */
 233     [infallible] attribute nsIURI baseURI;
 234
 235     /**
 236      * Sets/gets the current scroll restoration state,
 237      * if true == "manual", false == "auto".
 238      */
 239     [infallible] attribute boolean scrollRestorationIsManual;
 240
 241     /**
 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.
 244      */
 245     [infallible] readonly attribute boolean loadedInThisProcess;
 246
 247     /**
 248      * The session history it belongs to. This is set only on the root entries.
 249      */
 250     [noscript, infallible] attribute nsISHistory shistory;
 251
 252     /**
 253      * A number that is assigned by the sHistory when the entry is activated
 254      */
 255     [noscript, infallible] attribute unsigned long lastTouched;
 256
 257     /**
 258      * The current number of nsISHEntries which are immediate children of this
 259      * SHEntry.
 260      */
 261     [infallible] readonly attribute long childCount;
 262
 263     /**
 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.
 267      */
 268     [infallible] attribute boolean persist;
 269
 270     /**
 271      * Set/Get the visual viewport scroll position if session history is
 272      * changed through anchor navigation or pushState.
 273      */
 274     void setScrollPosition(in long x, in long y);
 275     void getScrollPosition(out long x, out long y);
 276
 277     /**
 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
 280      * is restored.
 281      */
 282     [noscript, notxpcom] void getViewerBounds(in nsIntRect bounds);
 283     [noscript, notxpcom] void setViewerBounds([const] in nsIntRect bounds);
 284
 285     /**
 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.
 289      */
 290
 291     /** Append a child shell to the end of our list. */
 292     [noscript, notxpcom] void addChildShell(in nsIDocShellTreeItem shell);
 293
 294     /**
 295      * Get the child shell at |index|; returns null if |index| is out of bounds.
 296      */
 297     [noscript] nsIDocShellTreeItem childShellAt(in long index);
 298
 299     /**
 300      * Clear the child shell list.
 301      */
 302     [noscript, notxpcom] void clearChildShells();
 303
 304     /**
 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,
 309      *  refreshURIList.
 310      */
 311     [noscript, notxpcom] void syncPresentationState();
 312
 313     /**
 314      * Initialises `layoutHistoryState` if it doesn't already exist
 315      * and returns a reference to it.
 316      */
 317     nsILayoutHistoryState initLayoutHistoryState();
 318
 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,
 333                            in bool loadReplace,
 334                            in nsIReferrerInfo referrerInfo,
 335                            in AString srcdoc,
 336                            in bool srcdocEntry,
 337                            in nsIURI baseURI,
 338                            in bool saveLayoutState,
 339                            in bool expired,
 340                            in bool userActivation);
 341
 342     nsISHEntry clone();
 343
 344     /**
 345      * Gets the owning pointer to the editor data assosicated with
 346      * this shistory entry. This forgets its pointer, so free it when
 347      * you're done.
 348      */
 349     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
 350
 351     /**
 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.
 355      */
 356     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
 357
 358     /** Returns true if this shistory entry is storing a detached editor. */
 359     [noscript, notxpcom] boolean hasDetachedEditor();
 360
 361     /**
 362      * Returns true if the related docshell was added because of
 363      * dynamic addition of an iframe/frame.
 364      */
 365     [noscript, notxpcom] boolean isDynamicallyAdded();
 366
 367     /**
 368      * Returns true if any of the child entries returns true
 369      * when isDynamicallyAdded is called on it.
 370      */
 371     boolean hasDynamicallyAddedChild();
 372
 373     /**
 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.
 377      */
 378     [noscript, notxpcom]
 379     boolean hasBFCacheEntry(in SHEntrySharedParentStatePtr aEntry);
 380
 381     /**
 382      * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
 383      * aEntry's BFCacheEntry.
 384      */
 385     void adoptBFCacheEntry(in nsISHEntry aEntry);
 386
 387     /**
 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.
 390      */
 391     void abandonBFCacheEntry();
 392
 393     /**
 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).
 398      */
 399     boolean sharesDocumentWith(in nsISHEntry aEntry);
 400
 401     /**
 402      * Sets an SHEntry to reflect that it is a history type load. This is the
 403      * equivalent to doing
 404      *
 405      * shEntry.loadType = 4;
 406      *
 407      * in js, but is easier to maintain and less opaque.
 408      */
 409     void setLoadTypeAsHistory();
 410
 411     /**
 412      * Add a new child SHEntry. If offset is -1 adds to the end of the list.
 413      */
 414     void AddChild(in nsISHEntry aChild, in long aOffset,
 415                   [optional,default(false)] in bool aUseRemoteSubframes);
 416
 417     /**
 418      * Remove a child SHEntry.
 419      */
 420     [noscript] void RemoveChild(in nsISHEntry aChild);
 421
 422     /**
 423      * Get child at an index.
 424      */
 425     nsISHEntry GetChildAt(in long aIndex);
 426
 427     /**
 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.
 431      */
 432     [notxpcom] void GetChildSHEntryIfHasNoDynamicallyAddedChild(in long aChildOffset,
 433                                                                 out nsISHEntry aChild);
 434
 435     /**
 436      * Replaces a child which is for the same docshell as aNewChild
 437      * with aNewChild.
 438      * @throw if nothing was replaced.
 439      */
 440     [noscript] void ReplaceChild(in nsISHEntry aNewChild);
 441
 442     /**
 443     * Remove all children of this entry and call abandonBFCacheEntry.
 444     */
 445     [notxpcom] void ClearEntry();
 446
 447     /**
 448      * Create nsDocShellLoadState and fill it with information.
 449      * Don't set nsSHEntry here to avoid serializing it.
 450      */
 451     [noscript] nsDocShellLoadStatePtr CreateLoadInfo();
 452
 453     [infallible] readonly attribute unsigned long long bfcacheID;
 454
 455     /**
 456      * Sync up the docshell and session history trees for subframe navigation.
 457      *
 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
 462      */
 463     [notxpcom] void SyncTreesForSubframeNavigation(in nsISHEntry aEntry,
 464                                                    in BrowsingContext aTopBC,
 465                                                    in BrowsingContext aIgnoreBC);
 466
 467     /**
 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.
 473      */
 474     [implicit_jscontext] attribute jsval wireframe;
 475 };