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