nsISHEntry.idl (16866B)
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 nsIPolicyContainer; 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 policyContainer, if any, that was used for this document load. That 197 * is not the policyContainer that was applied to subresource loads within the 198 * document, but the policyContainer that was applied to this document load. 199 */ 200 [infallible] attribute nsIPolicyContainer policyContainer; 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 * A transient entry will be replaced if a new entry is added for it's 266 * docshell. 267 */ 268 [infallible] boolean isTransient(); 269 270 /** 271 * Flag the entry to be replaced if a new entry is added for it's 272 * docshell. 273 */ 274 void setTransient(); 275 276 /** 277 * Set/Get the visual viewport scroll position if session history is 278 * changed through anchor navigation or pushState. 279 */ 280 void setScrollPosition(in long x, in long y); 281 void getScrollPosition(out long x, out long y); 282 283 /** 284 * Saved position and dimensions of the content viewer; we must adjust the 285 * root view's widget accordingly if this has changed when the presentation 286 * is restored. 287 */ 288 [noscript, notxpcom] void getViewerBounds(in nsIntRect bounds); 289 [noscript, notxpcom] void setViewerBounds([const] in nsIntRect bounds); 290 291 /** 292 * Saved child docshells corresponding to documentViewer. The child shells 293 * are restored as children of the parent docshell, in this order, when the 294 * parent docshell restores a saved presentation. 295 */ 296 297 /** Append a child shell to the end of our list. */ 298 [noscript, notxpcom] void addChildShell(in nsIDocShellTreeItem shell); 299 300 /** 301 * Get the child shell at |index|; returns null if |index| is out of bounds. 302 */ 303 [noscript] nsIDocShellTreeItem childShellAt(in long index); 304 305 /** 306 * Clear the child shell list. 307 */ 308 [noscript, notxpcom] void clearChildShells(); 309 310 /** 311 * Ensure that the cached presentation members are self-consistent. 312 * If either |documentViewer| or |windowState| are null, then all of the 313 * following members are cleared/reset: 314 * documentViewer, sticky, windowState, viewerBounds, childShells, 315 * refreshURIList. 316 */ 317 [noscript, notxpcom] void syncPresentationState(); 318 319 /** 320 * Initialises `layoutHistoryState` if it doesn't already exist 321 * and returns a reference to it. 322 */ 323 nsILayoutHistoryState initLayoutHistoryState(); 324 325 /** Additional ways to create an entry */ 326 [noscript] void create(in nsIURI URI, in AString title, 327 in nsIInputStream inputStream, 328 in unsigned long cacheKey, 329 in ACString contentType, 330 in nsIPrincipal triggeringPrincipal, 331 in nsIPrincipal principalToInherit, 332 in nsIPrincipal partitionedPrincipalToInherit, 333 in nsIPolicyContainer policyContainer, 334 in nsIDRef docshellID, 335 in boolean dynamicCreation, 336 in nsIURI originalURI, 337 in nsIURI resultPrincipalURI, 338 in nsIURI unstrippedURI, 339 in boolean loadReplace, 340 in nsIReferrerInfo referrerInfo, 341 in AString srcdoc, 342 in boolean srcdocEntry, 343 in nsIURI baseURI, 344 in boolean saveLayoutState, 345 in boolean expired, 346 in boolean userActivation); 347 348 nsISHEntry clone(); 349 350 /** 351 * Gets the owning pointer to the editor data assosicated with 352 * this shistory entry. This forgets its pointer, so free it when 353 * you're done. 354 */ 355 [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData(); 356 357 /** 358 * Sets the owning pointer to the editor data assosicated with 359 * this shistory entry. Unless forgetEditorData() is called, this 360 * shentry will destroy the editor data when it's destroyed. 361 */ 362 [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData); 363 364 /** Returns true if this shistory entry is storing a detached editor. */ 365 [noscript, notxpcom] boolean hasDetachedEditor(); 366 367 /** 368 * Returns true if the related docshell was added because of 369 * dynamic addition of an iframe/frame. 370 */ 371 [noscript, notxpcom] boolean isDynamicallyAdded(); 372 373 /** 374 * Returns true if any of the child entries returns true 375 * when isDynamicallyAdded is called on it. 376 */ 377 boolean hasDynamicallyAddedChild(); 378 379 /** 380 * Does this SHEntry point to the given BFCache entry? If so, evicting 381 * the BFCache entry will evict the SHEntry, since the two entries 382 * correspond to the same document. 383 */ 384 [noscript, notxpcom] 385 boolean hasBFCacheEntry(in SHEntrySharedParentStatePtr aEntry); 386 387 /** 388 * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to 389 * aEntry's BFCacheEntry. 390 */ 391 void adoptBFCacheEntry(in nsISHEntry aEntry); 392 393 /** 394 * Create a new BFCache entry and drop our reference to our old one. This 395 * call unlinks this SHEntry from any other SHEntries for its document. 396 */ 397 void abandonBFCacheEntry(); 398 399 /** 400 * Does this SHEntry correspond to the same document as aEntry? This is 401 * true iff the two SHEntries have the same BFCacheEntry. So in particular, 402 * sharesDocumentWith(aEntry) is guaranteed to return true if it's 403 * preceded by a call to adoptBFCacheEntry(aEntry). 404 */ 405 boolean sharesDocumentWith(in nsISHEntry aEntry); 406 407 /** 408 * Sets an SHEntry to reflect that it is a history type load. This is the 409 * equivalent to doing 410 * 411 * shEntry.loadType = 4; 412 * 413 * in js, but is easier to maintain and less opaque. 414 */ 415 void setLoadTypeAsHistory(); 416 417 /** 418 * Add a new child SHEntry. If offset is -1 adds to the end of the list. 419 */ 420 void AddChild(in nsISHEntry aChild, in long aOffset, 421 [optional,default(false)] in boolean aUseRemoteSubframes); 422 423 /** 424 * Remove a child SHEntry. 425 */ 426 [noscript] void RemoveChild(in nsISHEntry aChild); 427 428 /** 429 * Get child at an index. 430 */ 431 nsISHEntry GetChildAt(in long aIndex); 432 433 /** 434 * If this entry has no dynamically added child, get the child SHEntry 435 * at the given offset. The loadtype of the returned entry is set 436 * to its parent's loadtype. 437 */ 438 [notxpcom] void GetChildSHEntryIfHasNoDynamicallyAddedChild(in long aChildOffset, 439 out nsISHEntry aChild); 440 441 /** 442 * Replaces a child which is for the same docshell as aNewChild 443 * with aNewChild. 444 * @throw if nothing was replaced. 445 */ 446 [noscript] void ReplaceChild(in nsISHEntry aNewChild); 447 448 /** 449 * Remove all children of this entry and call abandonBFCacheEntry. 450 */ 451 [notxpcom] void ClearEntry(); 452 453 /** 454 * Create nsDocShellLoadState and fill it with information. 455 * Don't set nsSHEntry here to avoid serializing it. 456 */ 457 [noscript] nsDocShellLoadStatePtr CreateLoadInfo(); 458 459 [infallible] readonly attribute unsigned long long bfcacheID; 460 461 /** 462 * Sync up the docshell and session history trees for subframe navigation. 463 * 464 * @param aEntry new entry 465 * @param aTopBC top BC corresponding to the root ancestor 466 of the docshell that called this method 467 * @param aIgnoreBC current BC 468 */ 469 [notxpcom] void SyncTreesForSubframeNavigation(in nsISHEntry aEntry, 470 in BrowsingContext aTopBC, 471 in BrowsingContext aIgnoreBC); 472 473 /** 474 * If browser.history.collectWireframes is true, this will get populated 475 * with a Wireframe upon document navigation / pushState. This will only 476 * be set for nsISHEntry's accessed in the parent process with 477 * sessionHistoryInParent enabled. See Document.webidl for more details on 478 * what a Wireframe is. 479 */ 480 [implicit_jscontext] attribute jsval wireframe; 481 482 /** 483 * https://html.spec.whatwg.org/#she-navigation-api-key 484 * Only used with SHIP enabled. 485 */ 486 attribute nsIDRef navigationKey; 487 /** 488 * https://html.spec.whatwg.org/#she-navigation-api-id 489 * Only used with SHIP enabled. 490 */ 491 attribute nsIDRef navigationId; 492 };