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 nsIDocumentViewer;
  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     /** Document viewer, for fast restoration of presentation */
 116     [infallible] attribute nsIDocumentViewer documentViewer;
 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     [infallible] readonly attribute boolean hasPostData;
 132
 133     /** LayoutHistoryState for scroll position and form values */
 134     [infallible] attribute nsILayoutHistoryState layoutHistoryState;
 135
 136     /** parent of this entry */
 137     [infallible] attribute nsISHEntry parent;
 138
 139     /**
 140      * The loadType for this entry. This is typically loadHistory except
 141      * when reload is pressed, it has the appropriate reload flag
 142      */
 143     [infallible] attribute unsigned long loadType;
 144
 145     /**
 146      * An ID to help identify this entry from others during
 147      * subframe navigation
 148      */
 149     [infallible] attribute unsigned long ID;
 150
 151     /** The cache key for the entry */
 152     [infallible] attribute unsigned long cacheKey;
 153
 154     /** Should the layoutHistoryState be saved? */
 155     [infallible] attribute boolean saveLayoutStateFlag;
 156
 157     /**
 158      * attribute to indicate the content-type of the document that this
 159      * is a session history entry for
 160      */
 161     // XXX: make it [infallible] when ACString supports that (bug 1491187).
 162     attribute ACString contentType;
 163
 164     /**
 165      * If we created this SHEntry via history.pushState or modified it via
 166      * history.replaceState, and if we changed the SHEntry's URI via the
 167      * push/replaceState call, and if the SHEntry's new URI differs from its
 168      * old URI by more than just the hash, then we set this field to true.
 169      *
 170      * Additionally, if this SHEntry was created by calling pushState from a
 171      * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
 172      * true.
 173      */
 174     [infallible] attribute boolean URIWasModified;
 175
 176     /**
 177      * Get the principal, if any, that was associated with the channel
 178      * that the document that was loaded to create this history entry
 179      * came from.
 180      */
 181     [infallible] attribute nsIPrincipal triggeringPrincipal;
 182
 183     /**
 184      * Get the principal, if any, that is used when the inherit flag
 185      * is set.
 186      */
 187     [infallible] attribute nsIPrincipal principalToInherit;
 188
 189     /**
 190      * Get the storage principal, if any, that is used when the inherit flag is
 191      * set.
 192      */
 193     [infallible] attribute nsIPrincipal partitionedPrincipalToInherit;
 194
 195     /**
 196      * Get the csp, if any, that was used for this document load. That
 197      * is not the CSP that was applied to subresource loads within the
 198      * document, but the CSP that was applied to this document load.
 199      */
 200     [infallible] attribute nsIContentSecurityPolicy csp;
 201
 202     /**
 203      * Get/set data associated with this history state via a pushState() call,
 204      * serialized using structured clone.
 205      **/
 206     [infallible] attribute nsIStructuredCloneContainer stateData;
 207
 208     /**
 209      * The history ID of the docshell.
 210      */
 211     // Would be [infallible], but we don't support that property for nsIDPtr.
 212     attribute nsIDRef docshellID;
 213
 214     /**
 215      * True if this SHEntry corresponds to a document created by a srcdoc
 216      * iframe. Set when a value is assigned to srcdocData.
 217      */
 218     [infallible] readonly attribute boolean isSrcdocEntry;
 219
 220     /**
 221      * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
 222      * of the URI.  Similar to a Data URI, this information is needed to
 223      * recreate the document at a later stage.
 224      * Setting this sets isSrcdocEntry to true
 225      */
 226     // XXX: make it [infallible] when AString supports that (bug 1491187).
 227     attribute AString srcdocData;
 228
 229     /**
 230      * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
 231      * document for use in situations where it cannot otherwise be determined,
 232      * for example with view-source.
 233      */
 234     [infallible] attribute nsIURI baseURI;
 235
 236     /**
 237      * Sets/gets the current scroll restoration state,
 238      * if true == "manual", false == "auto".
 239      */
 240     [infallible] attribute boolean scrollRestorationIsManual;
 241
 242     /**
 243      * Flag to indicate that the history entry was originally loaded in the
 244      * current process. This flag does not survive a browser process switch.
 245      */
 246     [infallible] readonly attribute boolean loadedInThisProcess;
 247
 248     /**
 249      * The session history it belongs to. This is set only on the root entries.
 250      */
 251     [noscript, infallible] attribute nsISHistory shistory;
 252
 253     /**
 254      * A number that is assigned by the sHistory when the entry is activated
 255      */
 256     [noscript, infallible] attribute unsigned long lastTouched;
 257
 258     /**
 259      * The current number of nsISHEntries which are immediate children of this
 260      * SHEntry.
 261      */
 262     [infallible] readonly attribute long childCount;
 263
 264     /**
 265      * When an entry is serving is within nsISHistory's array of entries, this
 266      * property specifies if it should persist. If not it will be replaced by
 267      * new additions to the list.
 268      */
 269     [infallible] attribute boolean persist;
 270
 271     /**
 272      * Set/Get the visual viewport scroll position if session history is
 273      * changed through anchor navigation or pushState.
 274      */
 275     void setScrollPosition(in long x, in long y);
 276     void getScrollPosition(out long x, out long y);
 277
 278     /**
 279      * Saved position and dimensions of the content viewer; we must adjust the
 280      * root view's widget accordingly if this has changed when the presentation
 281      * is restored.
 282      */
 283     [noscript, notxpcom] void getViewerBounds(in nsIntRect bounds);
 284     [noscript, notxpcom] void setViewerBounds([const] in nsIntRect bounds);
 285
 286     /**
 287      * Saved child docshells corresponding to documentViewer.  The child shells
 288      * are restored as children of the parent docshell, in this order, when the
 289      * parent docshell restores a saved presentation.
 290      */
 291
 292     /** Append a child shell to the end of our list. */
 293     [noscript, notxpcom] void addChildShell(in nsIDocShellTreeItem shell);
 294
 295     /**
 296      * Get the child shell at |index|; returns null if |index| is out of bounds.
 297      */
 298     [noscript] nsIDocShellTreeItem childShellAt(in long index);
 299
 300     /**
 301      * Clear the child shell list.
 302      */
 303     [noscript, notxpcom] void clearChildShells();
 304
 305     /**
 306      * Ensure that the cached presentation members are self-consistent.
 307      * If either |documentViewer| or |windowState| are null, then all of the
 308      * following members are cleared/reset:
 309      *  documentViewer, sticky, windowState, viewerBounds, childShells,
 310      *  refreshURIList.
 311      */
 312     [noscript, notxpcom] void syncPresentationState();
 313
 314     /**
 315      * Initialises `layoutHistoryState` if it doesn't already exist
 316      * and returns a reference to it.
 317      */
 318     nsILayoutHistoryState initLayoutHistoryState();
 319
 320     /** Additional ways to create an entry */
 321     [noscript] void create(in nsIURI URI, in AString title,
 322                            in nsIInputStream inputStream,
 323                            in unsigned long cacheKey,
 324                            in ACString contentType,
 325                            in nsIPrincipal triggeringPrincipal,
 326                            in nsIPrincipal principalToInherit,
 327                            in nsIPrincipal partitionedPrincipalToInherit,
 328                            in nsIContentSecurityPolicy aCsp,
 329                            in nsIDRef docshellID,
 330                            in boolean dynamicCreation,
 331                            in nsIURI originalURI,
 332                            in nsIURI resultPrincipalURI,
 333                            in nsIURI unstrippedURI,
 334                            in bool loadReplace,
 335                            in nsIReferrerInfo referrerInfo,
 336                            in AString srcdoc,
 337                            in bool srcdocEntry,
 338                            in nsIURI baseURI,
 339                            in bool saveLayoutState,
 340                            in bool expired,
 341                            in bool userActivation);
 342
 343     nsISHEntry clone();
 344
 345     /**
 346      * Gets the owning pointer to the editor data assosicated with
 347      * this shistory entry. This forgets its pointer, so free it when
 348      * you're done.
 349      */
 350     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
 351
 352     /**
 353      * Sets the owning pointer to the editor data assosicated with
 354      * this shistory entry. Unless forgetEditorData() is called, this
 355      * shentry will destroy the editor data when it's destroyed.
 356      */
 357     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
 358
 359     /** Returns true if this shistory entry is storing a detached editor. */
 360     [noscript, notxpcom] boolean hasDetachedEditor();
 361
 362     /**
 363      * Returns true if the related docshell was added because of
 364      * dynamic addition of an iframe/frame.
 365      */
 366     [noscript, notxpcom] boolean isDynamicallyAdded();
 367
 368     /**
 369      * Returns true if any of the child entries returns true
 370      * when isDynamicallyAdded is called on it.
 371      */
 372     boolean hasDynamicallyAddedChild();
 373
 374     /**
 375      * Does this SHEntry point to the given BFCache entry? If so, evicting
 376      * the BFCache entry will evict the SHEntry, since the two entries
 377      * correspond to the same document.
 378      */
 379     [noscript, notxpcom]
 380     boolean hasBFCacheEntry(in SHEntrySharedParentStatePtr aEntry);
 381
 382     /**
 383      * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
 384      * aEntry's BFCacheEntry.
 385      */
 386     void adoptBFCacheEntry(in nsISHEntry aEntry);
 387
 388     /**
 389      * Create a new BFCache entry and drop our reference to our old one. This
 390      * call unlinks this SHEntry from any other SHEntries for its document.
 391      */
 392     void abandonBFCacheEntry();
 393
 394     /**
 395      * Does this SHEntry correspond to the same document as aEntry? This is
 396      * true iff the two SHEntries have the same BFCacheEntry. So in particular,
 397      * sharesDocumentWith(aEntry) is guaranteed to return true if it's
 398      * preceded by a call to adoptBFCacheEntry(aEntry).
 399      */
 400     boolean sharesDocumentWith(in nsISHEntry aEntry);
 401
 402     /**
 403      * Sets an SHEntry to reflect that it is a history type load. This is the
 404      * equivalent to doing
 405      *
 406      * shEntry.loadType = 4;
 407      *
 408      * in js, but is easier to maintain and less opaque.
 409      */
 410     void setLoadTypeAsHistory();
 411
 412     /**
 413      * Add a new child SHEntry. If offset is -1 adds to the end of the list.
 414      */
 415     void AddChild(in nsISHEntry aChild, in long aOffset,
 416                   [optional,default(false)] in bool aUseRemoteSubframes);
 417
 418     /**
 419      * Remove a child SHEntry.
 420      */
 421     [noscript] void RemoveChild(in nsISHEntry aChild);
 422
 423     /**
 424      * Get child at an index.
 425      */
 426     nsISHEntry GetChildAt(in long aIndex);
 427
 428     /**
 429      * If this entry has no dynamically added child, get the child SHEntry
 430      * at the given offset. The loadtype of the returned entry is set
 431      * to its parent's loadtype.
 432      */
 433     [notxpcom] void GetChildSHEntryIfHasNoDynamicallyAddedChild(in long aChildOffset,
 434                                                                 out nsISHEntry aChild);
 435
 436     /**
 437      * Replaces a child which is for the same docshell as aNewChild
 438      * with aNewChild.
 439      * @throw if nothing was replaced.
 440      */
 441     [noscript] void ReplaceChild(in nsISHEntry aNewChild);
 442
 443     /**
 444     * Remove all children of this entry and call abandonBFCacheEntry.
 445     */
 446     [notxpcom] void ClearEntry();
 447
 448     /**
 449      * Create nsDocShellLoadState and fill it with information.
 450      * Don't set nsSHEntry here to avoid serializing it.
 451      */
 452     [noscript] nsDocShellLoadStatePtr CreateLoadInfo();
 453
 454     [infallible] readonly attribute unsigned long long bfcacheID;
 455
 456     /**
 457      * Sync up the docshell and session history trees for subframe navigation.
 458      *
 459      * @param aEntry                    new entry
 460      * @param aTopBC                    top BC corresponding to the root ancestor
 461                                         of the docshell that called this method
 462      * @param aIgnoreBC                 current BC
 463      */
 464     [notxpcom] void SyncTreesForSubframeNavigation(in nsISHEntry aEntry,
 465                                                    in BrowsingContext aTopBC,
 466                                                    in BrowsingContext aIgnoreBC);
 467
 468     /**
 469      * If browser.history.collectWireframes is true, this will get populated
 470      * with a Wireframe upon document navigation / pushState. This will only
 471      * be set for nsISHEntry's accessed in the parent process with
 472      * sessionHistoryInParent enabled. See Document.webidl for more details on
 473      * what a Wireframe is.
 474      */
 475     [implicit_jscontext] attribute jsval wireframe;
 476 };