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