nsIDocShell.idl 39.9 KB
Newer Older
tbogard%aol.net's avatar
tbogard%aol.net committed
1
2
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
3
4
5
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
tbogard%aol.net's avatar
tbogard%aol.net committed
6

7
#include "domstubs.idl"
8
#include "nsIDocShellTreeItem.idl"
9
#include "nsIRequest.idl"
tbogard%aol.net's avatar
tbogard%aol.net committed
10

11
%{ C++
12
#include "js/TypeDecls.h"
13
#include "mozilla/Maybe.h"
14
#include "mozilla/NotNull.h"
15
#include "mozilla/UniquePtr.h"
16
#include "nsCOMPtr.h"
17
#include "nsIURI.h"
18
class nsCommandManager;
19
class nsPresContext;
20
class nsDocShellLoadState;
21
22
namespace mozilla {
class Encoding;
23
class HTMLEditor;
24
class PresShell;
25
namespace dom {
26
class BrowsingContext;
27
28
class ClientSource;
} // namespace dom
29
}
30
31
%}

tbogard%aol.net's avatar
tbogard%aol.net committed
32
/**
33
 * The nsIDocShell interface.
tbogard%aol.net's avatar
tbogard%aol.net committed
34
35
 */

36
[ptr] native nsPresContext(nsPresContext);
37
[ptr] native nsCommandManager(nsCommandManager);
38
[ptr] native PresShell(mozilla::PresShell);
39
[ref] native MaybeURI(mozilla::Maybe<nsCOMPtr<nsIURI>>);
40
[ref] native Encoding(const mozilla::Encoding*);
41
      native UniqueClientSource(mozilla::UniquePtr<mozilla::dom::ClientSource>);
42

43
interface nsIURI;
44
interface nsIChannel;
45
interface nsIContentViewer;
46
interface nsIContentSecurityPolicy;
47
interface nsIDocShellLoadInfo;
48
interface nsIEditor;
49
interface nsIEditingSession;
50
interface nsIInputStream;
51
interface nsIRequest;
52
interface nsISHEntry;
53
interface nsILayoutHistoryState;
54
interface nsISecureBrowserUI;
55
interface nsIScriptGlobalObject;
56
interface nsIStructuredCloneContainer;
57
interface nsIDOMStorage;
58
interface nsIPrincipal;
59
interface nsIWebBrowserPrint;
60
interface nsIPrivacyTransitionObserver;
61
interface nsIReflowObserver;
62
interface nsIScrollObserver;
63
interface nsIRemoteTab;
64
interface nsIBrowserChild;
65
interface nsICommandParams;
66
interface nsILoadURIDelegate;
67
native BrowserChildRef(already_AddRefed<nsIBrowserChild>);
68
native nsDocShellLoadStatePtr(nsDocShellLoadState*);
69

70
webidl BrowsingContext;
71
webidl ContentFrameMessageManager;
72
webidl EventTarget;
73
webidl Document;
74

75
[scriptable, builtinclass, uuid(049234fe-da10-478b-bc5d-bc6f9a1ba63d)]
76
interface nsIDocShell : nsIDocShellTreeItem
tbogard%aol.net's avatar
tbogard%aol.net committed
77
{
78
79
  void setCancelContentJSEpoch(in long aEpoch);

80
81
  /**
   * Loads a given URI.  This will give priority to loading the requested URI
82
   * in the object implementing this interface.  If it can't be loaded here
83
84
85
   * however, the URL dispatcher will go through its normal process of content
   * loading.
   *
86
87
88
   * @param aLoadState This is the extended load info for this load.
   * @param aSetNavigating If we should set isNavigating to true while initiating
   *                       the load.
89
   */
90
  [noscript]void loadURI(in nsDocShellLoadStatePtr aLoadState, in boolean aSetNavigating);
91

92
93
94
95
  /**
   * Do either a history.pushState() or history.replaceState() operation,
   * depending on the value of aReplace.
   */
96
  [implicit_jscontext]
97
98
  void addState(in jsval aData, in AString aTitle,
                in AString aURL, in boolean aReplace);
99

100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
  /**
   * Helper for addState and document.open that does just the
   * history-manipulation guts.
   *
   * Arguments the spec defines:
   *
   * @param aDocument the document we're manipulating.  This will get the new URI.
   * @param aNewURI the new URI.
   * @param aData The serialized state data.  May be null.
   * @param aTitle The new title.  May be empty.
   * @param aReplace whether this should replace the exising SHEntry.
   *
   * Arguments we need internally because deriving them from the
   * others is a bit complicated:
   *
   * @param aCurrentURI the current URI we're working with.  Might be null.
   * @param aEqualURIs whether the two URIs involved are equal.
   */
  [nostdcall]
  void updateURLAndHistory(in Document aDocument, in nsIURI aNewURI,
                           in nsIStructuredCloneContainer aData, in AString aTitle,
                           in boolean aReplace, in nsIURI aCurrentURI,
                           in boolean aEqualURIs);

124
125
126
127
128
129
  /**
   * Reset state to a new content model within the current document and the document
   * viewer.  Called by the document before initiating an out of band document.write().
   */
  void prepareForNewContentModel();

130
131
132
133
  /**
   * For editors and suchlike who wish to change the URI associated with the
   * document. Note if you want to get the current URI, use the read-only
   * property on nsIWebNavigation.
134
   */
135
  void setCurrentURI(in nsIURI aURI);
136
137
138

  /**
   * Notify the associated content viewer and all child docshells that they are
139
   * about to be hidden.  If |isUnload| is true, then the document is being
140
   * unloaded and all dynamic subframe history entries are removed as well.
141
   *
142
143
144
   * @param isUnload
   *        True to fire the unload event in addition to the pagehide event,
   *        and remove all dynamic subframe history entries.
145
   */
146
  [noscript] void firePageHideNotification(in boolean isUnload);
147

148
149
150
  /**
   * Presentation context for the currently loaded document.  This may be null.
   */
151
  [notxpcom,nostdcall] readonly attribute nsPresContext presContext;
152
153

  /**
154
   * Presentation shell for the currently loaded document.  This may be null.
155
   */
156
  [notxpcom,nostdcall] readonly attribute PresShell presShell;
157

158
159
160
161
  /**
   * Presentation shell for the oldest document, if this docshell is
   * currently transitioning between documents.
   */
162
  [notxpcom,nostdcall] readonly attribute PresShell eldestPresShell;
163

164
165
166
167
168
169
  /**
   * Content Viewer that is currently loaded for this DocShell.  This may
   * change as the underlying content changes.
   */
  readonly attribute nsIContentViewer contentViewer;

170
171
172
173
174
  /**
   * Get the id of the outer window that is or will be in this docshell.
   */
  [infallible] readonly attribute unsigned long long outerWindowID;

175
176
177
178
  /**
   * This attribute allows chrome to tie in to handle DOM events that may
   * be of interest to chrome.
   */
179
  attribute EventTarget chromeEventHandler;
180

181
  /**
182
183
   * This allows chrome to set a custom User agent on a specific docshell
   */
184
  attribute AString customUserAgent;
185

186
187
188
189
190
  /**
   * Whether CSS error reporting is enabled.
   */
  attribute boolean cssErrorReportingEnabled;

191
192
193
194
195
196
197
198
199
200
201
202
203
  /**
   * Whether to allow plugin execution
   */
  attribute boolean allowPlugins;

  /**
   * Whether to allow Javascript execution
   */
  attribute boolean allowJavascript;

  /**
   * Attribute stating if refresh based redirects can be allowed
   */
204
  attribute boolean allowMetaRedirects;
205
206
207
208
209
210

  /**
   * Attribute stating if it should allow subframes (framesets/iframes) or not
   */
  attribute boolean allowSubframes;

211
212
213
214
215
  /**
   * Attribute stating whether or not images should be loaded.
   */
  attribute boolean allowImages;

216
217
218
219
220
  /**
   * Attribute stating whether or not media (audio/video) should be loaded.
   */
  [infallible] attribute boolean allowMedia;

221
222
223
224
225
226
227
  /**
   * Attribute that determines whether DNS prefetch is allowed for this subtree
   * of the docshell tree.  Defaults to true.  Setting this will make it take
   * effect starting with the next document loaded in the docshell.
   */
  attribute boolean allowDNSPrefetch;

228
229
230
231
232
  /**
   * Attribute that determines whether window control (move/resize) is allowed.
   */
  attribute boolean allowWindowControl;

233
234
235
236
237
238
239
  /**
   * True if the docshell allows its content to be handled by a content listener
   * other than the docshell itself, including the external helper app service,
   * and false otherwise.  Defaults to true.
   */
  [infallible] attribute boolean allowContentRetargeting;

240
241
242
243
244
245
  /**
   * True if new child docshells should allow content retargeting.
   * Setting allowContentRetargeting also overwrites this value.
   */
  [infallible] attribute boolean allowContentRetargetingOnChildren;

246
247
248
249
250
251
252
253
254
  /**
   * True if this docShell should inherit the private browsing ID from
   * its parent when reparented.
   *
   * NOTE: This should *not* be set false in new code, or for docShells
   * inserted anywhere other than as children of panels.
   */
  [infallible] attribute boolean inheritPrivateBrowsingId;

255
  /**
256
   * Get an array of this docShell and its children.
257
258
259
260
261
262
263
   *
   * @param aItemType  - Only include docShells of this type, or if typeAll,
   *                     include all child shells.
   *                     Uses types from nsIDocShellTreeItem.
   * @param aDirection - Whether to enumerate forwards or backwards.
   */

264
265
266
267
  cenum DocShellEnumeratorDirection : 8 {
    ENUMERATE_FORWARDS  = 0,
    ENUMERATE_BACKWARDS = 1
  };
268

269
270
  Array<nsIDocShell> getAllDocShellsInSubtree(in long aItemType,
                                              in nsIDocShell_DocShellEnumeratorDirection aDirection);
271
272

  /**
273
274
275
276
277
278
   * The type of application that created this window.
   *
   * DO NOT DELETE, see bug 176166. For firefox, this value will always be
   * UNKNOWN. However, it is used heavily in Thunderbird/comm-central and we
   * don't really have a great replacement at the moment, so we'll just leave it
   * here.
279
   */
280
281
282
283
284
  cenum AppType : 8 {
    APP_TYPE_UNKNOWN = 0,
    APP_TYPE_MAIL    = 1,
    APP_TYPE_EDITOR  = 2
  };
285

286
  [infallible] attribute nsIDocShell_AppType appType;
287

288
  /**
289
   * certain docshells (like the message pane)
290
291
292
293
294
   * should not throw up auth dialogs
   * because it can act as a password trojan
   */
  attribute boolean allowAuth;

295
296
297
298
299
300
  /**
   * Set/Get the document scale factor.  When setting this attribute, a
   * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
   * not supporting zoom.  Implementations not supporting zoom should return
   * 1.0 all the time for the Get operation.  1.0 by the way is the default
   * of zoom.  This means 100% of normal scaling or in other words normal size
301
   * no zoom.
302
303
304
305
   */
  attribute float zoom;

  /*
306
   * The size, in CSS pixels, of the horizontal margins for the <body> of an
307
   * HTML document in this docshell; used to implement the marginwidth attribute
308
309
   * on HTML <frame>/<iframe> elements.  A value smaller than zero indicates
   * that the attribute was not set.
310
311
312
313
   */
  attribute long marginWidth;

  /*
314
   * The size, in CSS pixels, of the vertical margins for the <body> of an HTML
315
   * document in this docshell; used to implement the marginheight attribute on
316
317
   * HTML <frame>/<iframe> elements.  A value smaller than zero indicates that
   * the attribute was not set.
318
319
320
   */
  attribute long marginHeight;

321
322
323
  /*
   * Tells the docshell to offer focus to its tree owner.
   * This is currently only necessary for embedding chrome.
324
325
326
327
   * If forDocumentNavigation is true, then document navigation should be
   * performed, where only the root of documents are selected. Otherwise, the
   * next element in the parent should be returned. Returns true if focus was
   * successfully taken by the tree owner.
328
   */
329
  bool tabToTreeOwner(in boolean forward, in boolean forDocumentNavigation);
330

331
332
333
  /**
   * Current busy state for DocShell
   */
334
335
336
337
338
339
340
341
  cenum BusyFlags : 8 {
    BUSY_FLAGS_NONE             = 0,
    BUSY_FLAGS_BUSY             = 1,
    BUSY_FLAGS_BEFORE_PAGE_LOAD = 2,
    BUSY_FLAGS_PAGE_LOADING     = 4,
  };

  [infallible] readonly attribute nsIDocShell_BusyFlags busyFlags;
342

343
  /**
344
   * Load commands for the document
345
   */
346
347
348
349
350
351
  cenum LoadCommand : 8 {
    LOAD_CMD_NORMAL  = 0x1,   // Normal load
    LOAD_CMD_RELOAD  = 0x2,   // Reload
    LOAD_CMD_HISTORY = 0x4,   // Load from history
    LOAD_CMD_PUSHSTATE = 0x8, // History.pushState()
  };
352

353
  /*
354
355
   * Attribute to access the loadtype for the document. LoadType Enum is
   * defined in nsDocShellLoadTypes.h
356
   */
357
  [infallible] attribute unsigned long loadType;
358

359
360
  /*
   * Default load flags (as defined in nsIRequest) that will be set on all
361
362
   * requests made by this docShell and propagated to all child docShells and
   * to nsILoadGroup::defaultLoadFlags for the docShell's loadGroup.
363
364
365
366
367
368
   * Default is no flags.  Once set, only future requests initiated by the
   * docShell are affected, so in general, these flags should be set before
   * the docShell loads any content.
   */
  attribute nsLoadFlags defaultLoadFlags;

369
370
371
  /*
   * returns true if the docshell is being destroyed, false otherwise
   */
372
  boolean isBeingDestroyed();
373
374
375
376
377

  /*
   * Returns true if the docshell is currently executing the onLoad Handler
   */
  readonly attribute boolean isExecutingOnLoadHandler;
378
379
380

  attribute nsILayoutHistoryState layoutHistoryState;

381
382
383
384
385
386
  /**
   * The SecureBrowserUI object for this docshell.  This is set by XUL
   * <browser> or nsWebBrowser for their root docshell.
   */
  attribute nsISecureBrowserUI securityUI;

387
388
389
390
391
  /**
   * Object used to delegate URI loading to an upper context.
   * Currently only set for GeckoView to allow handling of load requests
   * at the application level.
   */
392
  readonly attribute nsILoadURIDelegate loadURIDelegate;
393

394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
  /**
   * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
   * and this docshell's children, recursively. The meta-refresh timers can be
   * restarted using resumeRefreshURIs().  If the timers are already suspended,
   * this has no effect.
   */
  void suspendRefreshURIs();

  /**
   * Restart the XPCOM timers for each meta-refresh URI in this docshell,
   * and this docshell's children, recursively.  If the timers are already
   * running, this has no effect.
   */
  void resumeRefreshURIs();

  /**
410
411
412
413
414
415
416
   * Begin firing WebProgressListener notifications for restoring a page
   * presentation. |viewer| is the content viewer whose document we are
   * starting to load.  If null, it defaults to the docshell's current content
   * viewer, creating one if necessary.  |top| should be true for the toplevel
   * docshell that is being restored; it will be set to false when this method
   * is called for child docshells.  This method will post an event to
   * complete the simulated load after returning to the event loop.
417
418
   */
  void beginRestore(in nsIContentViewer viewer, in boolean top);
419
420
421
422
423
424
425
426
427
428

  /**
   * Finish firing WebProgressListener notifications and DOM events for
   * restoring a page presentation.  This should only be called via
   * beginRestore().
   */
  void finishRestore();

  /* Track whether we're currently restoring a document presentation. */
  readonly attribute boolean restoringDocument;
429
430
431

  /* attribute to access whether error pages are enabled */
  attribute boolean useErrorPages;
432

433
434
435
436
437
438
439
440
441
  /**
   * Display a load error in a frame while keeping that frame's currentURI
   * pointing correctly to the page where the error ocurred, rather than to
   * the error document page. You must provide either the aURI or aURL parameter.
   *
   * @param  aError         The error code to be displayed
   * @param  aURI           nsIURI of the page where the error happened
   * @param  aURL           wstring of the page where the error happened
   * @param  aFailedChannel The channel related to this error
442
443
444
   *
   * Returns whether or not we displayed an error page (note: will always
   * return false if in-content error pages are disabled!)
445
   */
446
447
448
449
  boolean displayLoadError(in nsresult aError,
                           in nsIURI aURI,
                           in wstring aURL,
                           [optional] in nsIChannel aFailedChannel);
450

451
452
453
454
455
  /**
   * The channel that failed to load and resulted in an error page.
   * May be null. Relevant only to error pages.
   */
  readonly attribute nsIChannel failedChannel;
456

457
  /**
458
459
   * Keeps track of the previous nsISHEntry index and the current
   * nsISHEntry index at the time that the doc shell begins to load.
460
461
   * Used for ContentViewer eviction.
   */
462
463
  readonly attribute long previousEntryIndex;
  readonly attribute long loadedEntryIndex;
464
465
466
467
468
469
470
471
472

  /**
   * Notification that entries have been removed from the beginning of a
   * nsSHistory which has this as its rootDocShell.
   *
   * @param numEntries - The number of entries removed
   */
  void historyPurged(in long numEntries);

473
  /**
474
   * Gets the channel for the currently loaded document, if any.
475
476
477
478
   * For a new document load, this will be the channel of the previous document
   * until after OnLocationChange fires.
   */
  readonly attribute nsIChannel currentDocumentChannel;
479
480

  /**
481
482
   * The original offset of this child in its container. This property is -1 for
   * dynamically added docShells.
483
   */
484
  [notxpcom,nostdcall] attribute long childOffset;
485
486
487

  /**
   * Find out whether the docshell is currently in the middle of a page
488
   * transition. This is set just before the pagehide/unload events fire.
489
490
   */
  readonly attribute boolean isInUnload;
491

492
493
494
  /**
   * This attribute determines whether Mixed Active Content is loaded on the
   * document. When it is true, mixed active content was not blocked and has
495
496
497
   * loaded (or is about to load) on the page. When it is false, mixed active content
   * has not loaded on the page, either because there was no mixed active content
   * requests on the page or such requests were blocked by nsMixedContentBlocker.
498
499
500
501
   * This boolean is set to true in nsMixedContentBlocker if Mixed Active Content
   * is allowed (either explicitly on the page by the user or when the about:config
   * setting security.mixed_content.block_active_content is set to false).
   */
502
  [infallible] readonly attribute boolean hasMixedActiveContentLoaded;
503

504
505
506
507
508
509
510
511
512
513
   /**
   * This attribute determines whether a document has Mixed Active Content
   * that has been blocked from loading. When it is true, there is definitely
   * mixed active content on a page that has been blocked by
   * nsMixedContentBlocker.  When it is false, there may or may not be mixed
   * active content on a page, but if there is, it will load. Note that if the
   * about:config setting security.mixed_content.block_active_content is set
   * false, this boolean will be false, since blocking active content has been
   * disabled.
   */
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
  [infallible] readonly attribute boolean hasMixedActiveContentBlocked;

  /**
   * This attribute determines whether Mixed Display Content is loaded on the
   * document. When it is true, mixed display content was not blocked and has
   * loaded (or is about to load) on the page. Similar behavior to
   * hasMixedActiveContentLoaded.
   */
  [infallible] readonly attribute boolean hasMixedDisplayContentLoaded;

   /**
   * This attribute determines whether a document has Mixed Display Content
   * that has been blocked from loading. Similar behavior to
   * hasMixedActiveContentBlocked.
   */
  [infallible] readonly attribute boolean hasMixedDisplayContentBlocked;
530

531
532
533
534
535
536
   /**
   * This attribute determines whether a document has Tracking Content
   * that has been blocked from loading.
   */
  [infallible] readonly attribute boolean hasTrackingContentBlocked;

537
538
  /**
   * Disconnects this docshell's editor from its window, and stores the
539
540
   * editor data in the open document's session history entry.  This
   * should be called only during page transitions.
541
542
   */
  [noscript, notxpcom] void DetachEditorFromWindow();
543
544
545
546
547
548

  /**
   * If true, this browser is not visible in the traditional sense, but
   * is actively being rendered to the screen (ex. painted on a canvas)
   * and should be treated accordingly.
   **/
549
  attribute boolean isOffScreenBrowser;
550

551
552
553
554
  /**
   * Allows nsDocumentViewer to tell the top-level same-type docshell that
   * one of the documents under it is printing.
   */
555
  [noscript, notxpcom] void setIsPrinting(in boolean aIsPrinting);
556

557
  /**
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
   * This method should only be called on a docShell that has been specifically
   * created to display a print preview document.  If the current document
   * viewer isn't initialized for print preview when this method is called, it
   * is replaced with a new viewer with an about:blank document (with the URL
   * about:printpreview).  The viewer is then returned, ready for the print
   * preview document to be constructed when viewer.printPreview() is called.
   *
   * The same viewer will be returned on subsequent calls since various bits of
   * code assume that, once created, the viewer is never replaced.  Note,
   * however, that the viewer's document will be replaced with a new document
   * each time printPreview() is called on it (which is what we do to take
   * account of print preview settings changes).  Replacing the document
   * viewer's document breaks the normally unchanging 1:1 relationship between
   * a document and its viewer, but that seems to be okay.
   */
  nsIWebBrowserPrint initOrReusePrintPreviewViewer();

  /**
   * Propagated to the print preview document viewer.  Must only be called on
   * a document viewer that has been initialized for print preview.
578
   */
579
  void exitPrintPreview();
580
581
582
583

  /**
   * Whether this docshell can execute scripts based on its hierarchy.
   * The rule of thumb here is that we disable js if this docshell or any
584
   * of its parents disallow scripting.
585
   */
586
  [infallible] readonly attribute boolean canExecuteScripts;
587
588
589
590
591
592

  /**
   * Sets whether a docshell is active. An active docshell is one that is
   * visible, and thus is not a good candidate for certain optimizations
   * like image frame discarding. Docshells are active unless told otherwise.
   */
593
  [infallible] attribute boolean isActive;
594
595
596
597

  /**
   * The ID of the docshell in the session history.
   */
598
599
600
601
602
603
  readonly attribute nsIDPtr historyID;

  /**
   * Helper method for accessing this value from C++
   */
  [noscript, notxpcom] nsID HistoryID();
604
605
606
607
608
609
610

  /**
   * Sets whether a docshell is an app tab. An app tab docshell may behave
   * differently than a non-app tab docshell in some cases, such as when
   * handling link clicks. Docshells are not app tabs unless told otherwise.
   */
  attribute boolean isAppTab;
611
612
613
614

  /**
   * Create a new about:blank document and content viewer.
   * @param aPrincipal the principal to use for the new document.
615
   * @param aStoragePrincipal the storage principal to use for the new document.
616
   * @param aCsp the CSP to use for the new document.
617
   */
618
  void createAboutBlankContentViewer(in nsIPrincipal aPrincipal,
619
                                     in nsIPrincipal aStoragePrincipal,
620
                                     [optional] in nsIContentSecurityPolicy aCSP);
621

622
  /**
623
624
   * Upon getting, returns the canonical encoding label of the document
   * currently loaded into this docshell.
625
   *
626
   * Upon setting, sets forcedCharset for compatibility with legacy callers.
627
   */
628
  attribute ACString charset;
629

630
631
632
633
634
635
636
  /**
   * Called when the user chose an encoding override from the character
   * encoding menu. Separate from the setter for the charset property to avoid
   * extensions adding noise to the data.
   */
  void gatherCharsetMenuTelemetry();

637
  /**
638
   * The charset forced by the user.
639
   */
640
  attribute ACString forcedCharset;
641
642
643
644

  /**
   * In a child docshell, this is the charset of the parent docshell
   */
645
  [noscript, notxpcom, nostdcall] void setParentCharset(
646
    in Encoding parentCharset,
647
648
649
    in int32_t parentCharsetSource,
    in nsIPrincipal parentCharsetPrincipal);
  [noscript, notxpcom, nostdcall] void getParentCharset(
650
    out Encoding parentCharset,
651
652
    out int32_t parentCharsetSource,
    out nsIPrincipal parentCharsetPrincipal);
653

654
655
656
657
658
  /**
   * Whether the docShell records profile timeline markers at the moment
   */
  [infallible] attribute boolean recordProfileTimelineMarkers;

659
660
661
662
663
664
665
666
  /**
   * Return a DOMHighResTimeStamp representing the number of
   * milliseconds from an arbitrary point in time.  The reference
   * point is shared by all DocShells and is also used by timestamps
   * on markers.
   */
  DOMHighResTimeStamp now();

667
668
669
670
671
672
  /**
   * Returns and flushes the profile timeline markers gathered by the docShell
   */
  [implicit_jscontext]
  jsval popProfileTimelineMarkers();

673
674
675
676
677
678
  /**
   * Add an observer to the list of parties to be notified when this docshell's
   * private browsing status is changed. |obs| must support weak references.
   */
  void addWeakPrivacyTransitionObserver(in nsIPrivacyTransitionObserver obs);

679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
  /**
   * Add an observer to the list of parties to be notified when reflows are
   * occurring. |obs| must support weak references.
   */
  void addWeakReflowObserver(in nsIReflowObserver obs);

  /**
   * Remove an observer from the list of parties to be notified about reflows.
   */
  void removeWeakReflowObserver(in nsIReflowObserver obs);

  /**
   * Notify all attached observers that a reflow has just occurred.
   *
   * @param interruptible if true, the reflow was interruptible.
   * @param start         timestamp when reflow started, in milliseconds since
   *                      navigationStart (accurate to 1/1000 of a ms)
   * @param end           timestamp when reflow ended, in milliseconds since
   *                      navigationStart (accurate to 1/1000 of a ms)
   */
  [noscript] void notifyReflowObservers(in bool interruptible,
                                        in DOMHighResTimeStamp start,
                                        in DOMHighResTimeStamp end);

703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
  /**
   * Add an observer to the list of parties to be notified when scroll position
   * of some elements is changed.
   */
  [noscript] void addWeakScrollObserver(in nsIScrollObserver obs);

  /**
   * Add an observer to the list of parties to be notified when scroll position
   * of some elements is changed.
   */
  [noscript] void removeWeakScrollObserver(in nsIScrollObserver obs);

  /**
   * Notify all attached observers that the scroll position of some element
   * has changed.
   */
  [noscript] void notifyScrollObservers();

721
722
723
  /**
   * The type of iframe that this docshell lives.
   */
724
725
726
727
728
  cenum FrameType : 8 {
    FRAME_TYPE_REGULAR = 0,
    FRAME_TYPE_BROWSER = 1,
  };
  [infallible] attribute nsIDocShell_FrameType frameType;
729

730
  /**
731
732
   * Returns true if this docshell corresponds to an <iframe mozbrowser>.
   * <xul:browser> returns false here.
733
   */
734
  [infallible] readonly attribute boolean isMozBrowser;
735
736

  /**
737
738
739
   * Returns true if this docshell corresponds to an <iframe mozbrowser>, or
   * if this docshell is contained in an <iframe mozbrowser>. <xul:browser>
   * returns false here.
740
   *
741
   * To compute this value, we walk up the docshell hierarchy.  If we encounter
742
   * a docshell with isMozBrowser before we hit the end of the hierarchy,
743
   * we return true.  Otherwise, we return false.
744
   */
745
  [infallible] readonly attribute boolean isInMozBrowser;
746

747
748
749
750
751
  /**
   * Returns true if this docshell is the top level content docshell.
   */
  [infallible] readonly attribute boolean isTopLevelContentDocShell;

752
  /**
753
   * Like nsIDocShellTreeItem::GetSameTypeParent, except this ignores <iframe
754
   * mozbrowser> boundaries.
755
756
   *
   * @deprecated: Use `BrowsingContext::GetParent()` in the future.
757
   */
758
  nsIDocShell getSameTypeParentIgnoreBrowserBoundaries();
759

760
761
  /**
   * Like nsIDocShellTreeItem::GetSameTypeRootTreeItem, except this ignores
762
   * <iframe mozbrowser> boundaries.
763
764
   *
   * @deprecated: Use `BrowsingContext::Top()` in the future.
765
   */
766
  nsIDocShell getSameTypeRootTreeItemIgnoreBrowserBoundaries();
767

768
  /**
769
770
771
772
   * True iff asynchronous panning and zooming is enabled for this
   * docshell.
   */
  readonly attribute bool asyncPanZoomEnabled;
773

774
775
776
777
  /**
   * Returns true if we are sandboxed from aTargetDocShell.
   * aTargetDocShell - the browsing context we are attempting to navigate.
   */
778
  [noscript,notxpcom,nostdcall] bool isSandboxedFrom(in BrowsingContext aTargetBC);
779

780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
  /**
   * This member variable determines whether a document has Mixed Active Content that
   * was initially blocked from loading, but the user has choosen to override the
   * block and allow the content to load. mMixedContentChannel is set to the document's
   * channel when the user allows mixed content. The nsMixedContentBlocker content policy
   * checks if the document's root channel matches the mMixedContentChannel.  If it matches,
   * then Mixed Content is loaded.  If it does match, mixed content is blocked.
   *
   * A match implies that there is definitely mixed active content on a page that was
   * initially blocked by nsMixedContentBlocker and then allowed and loaded by the user.
   * A miss imples that IF there is mixed active content on the page AND it was
   * blocked by nsMixedContentBlocker.cpp, the user has not choosen to override
   * the block. Note that if the about:config setting
   * security.mixed_content.block_active_content is set to false, this boolean
   * will be false, mMixedContentChannel will remain null since blocking active content has
   * been disabled and hence mMixedContentChannel will never be set.
   */
  attribute nsIChannel mixedContentChannel;

  /**
   * Checks whether the channel associated with the root docShell is equal to
   * mMixedContentChannel. If they are the same, allowMixedContent is set to true.
802
803
804
   * Checks if the root document has a secure connection. If it is, sets
   * rootHasSecureConnection to true. If the docShell is the root doc shell,
   * isRootDocShell is set to true.
805
   */
806
  void GetAllowMixedContentAndConnectionData(out boolean rootHasSecureConnection, out boolean allowMixedContent, out boolean isRootDocShell);
807
808


809
810
811
812
813
814
815
  /**
   * Are plugins allowed in the current document loaded in this docshell ?
   * (if there is one). This depends on whether plugins are allowed by this
   * docshell itself or if the document is sandboxed and hence plugins should
   * not be allowed.
   */
  [noscript, notxpcom] bool pluginsAllowedInCurrentDoc();
816

817
818
819
820

  /**
   * Attribute that determines whether fullscreen is allowed to be entered for
   * this subtree of the docshell tree. This is true when all iframes containing
821
   * this docshell have their "allowfullscreen" attribute set to "true".
822
823
   * fullscreenAllowed is only writable at content boundaries, where it is used
   * to propagate the value of the cross process parent's iframe's
824
   * "allowfullscreen" attribute to the child process. Setting
825
826
827
828
   * fullscreenAllowed on docshells which aren't content boundaries throws an
   * exception.
   */
  [infallible] readonly attribute boolean fullscreenAllowed;
829

830
  void setFullscreenAllowed(in boolean allowed);
831

832
833
834
  [notxpcom] uint32_t orientationLock();
  [notxpcom] void setOrientationLock(in uint32_t orientationLock);

835
836
  [noscript, infallible] attribute boolean affectPrivateSessionLifetime;

837
838
839
840
841
  /**
   * Indicates whether the UI may enable the character encoding menu. The UI
   * must disable the menu when this property is false.
   */
  [infallible] readonly attribute boolean mayEnableCharacterEncodingMenu;
842

843
844
845
846
847
  /**
   * Indicates that the character encoding was autodetected.
   */
  [infallible] readonly attribute boolean charsetAutodetected;

848
849
850
           attribute  nsIEditor editor;
  readonly attribute  boolean   editable;             /* this docShell is editable */
  readonly attribute  boolean   hasEditingSession;    /* this docShell has an editing session */
851

852
853
854
855
856
857
  /**
   * Make this docShell editable, setting a flag that causes
   * an editor to get created, either immediately, or after
   * a url has been loaded.
   *      @param  inWaitForUriLoad    true to wait for a URI before
   *                                  creating the editor.
858
   */
859
  void makeEditable(in boolean inWaitForUriLoad);
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886


  /**
   * Add a Child SHEntry for a frameset page, given the child's loadtype.
   * If aCloneChildren is true, then aCloneReference's children will be
   * cloned onto aHistoryEntry.
   */
  void addChildSHEntry(in nsISHEntry aCloneReference,
                       in nsISHEntry aHistoryEntry,
                       in long aChildOffset,
                       in unsigned long aLoadType,
                       in boolean aCloneChilden);

  /**
   * Whether this docshell should save entries in global history.
   */
  attribute boolean useGlobalHistory;

  /**
   * Removes nsISHEntry objects related to this docshell from session history.
   * Use this only with subdocuments, like iframes.
   */
  void removeFromSessionHistory();

  /**
   * Set when an iframe/frame is added dynamically.
   */
887
  [infallible] attribute boolean createdDynamically;
888
889
890
891
892

  /**
   * Returns false for mLSHE, true for mOSHE
   */
  boolean getCurrentSHEntry(out nsISHEntry aEntry);
893
894
895
896
897
898
899

  /**
    * Cherry picked parts of nsIController.
    * They are here, because we want to call these functions
    * from JS.
    */
  boolean isCommandEnabled(in string command);
900
  [can_run_script]
901
  void doCommand(in string command);
902
  [can_run_script]
903
  void doCommandWithParams(in string command, in nsICommandParams aParams);
904
905
906
907
908
909
910

  /**
   * Invisible DocShell are dummy construct to simulate DOM windows
   * without any actual visual representation. They have to be marked
   * at construction time, to avoid any painting activity.
   */
  [noscript, notxpcom] bool IsInvisible();
911
  [noscript, notxpcom] void SetInvisible(in bool aIsInvisibleDocshell);
912
913
914
915
916

/**
 * Get the script global for the document in this docshell.
*/
  [noscript,notxpcom,nostdcall] nsIScriptGlobalObject GetScriptGlobalObject();
Wes Kocher's avatar
Wes Kocher committed
917

918
919
920
921
  /**
   * If deviceSizeIsPageSize is set to true, device-width/height media queries
   * will be calculated from the page size, not the device size.
   *
922
   * Used by the Responsive Design Mode and B2G Simulator.
923
924
925
926
   *
   * Default is False.
   * Default value can be overriden with
   * docshell.device_size_is_page_size pref.
927
928
   */
  [infallible] attribute boolean deviceSizeIsPageSize;
929
930
931
932
933
934
935

  /**
   * Regarding setOpener / getOpener - We can't use XPIDL's "attribute"
   * for notxpcom, so we're relegated to using explicit gets / sets. This
   * should be fine, considering that these methods should only ever be
   * called from native code.
   */
936
937
  [noscript,notxpcom,nostdcall] void setOpener(in nsIRemoteTab aOpener);
  [noscript,notxpcom,nostdcall] nsIRemoteTab getOpener();
938

939
940
941
942
943
  /**
   * Notify DocShell when the browser is about to start executing JS, and after
   * that execution has stopped.  This only occurs when the Timeline devtool
   * is collecting information.
   */
944
  [noscript,notxpcom,nostdcall] void notifyJSRunToCompletionStart(in string aReason,
945
946
                                                                  in AString functionName,
                                                                  in AString fileName,
947
948
                                                                  in unsigned long lineNumber,
                                                                  in jsval asyncStack,
949
                                                                  in string asyncCause);
950
951
  [noscript,notxpcom,nostdcall] void notifyJSRunToCompletionStop();

952
953
  [noscript] void GetOSHEId(out uint32_t aSHEntryId);

954
955
956
957
958
959
  /**
   * This attribute determines whether a document which is not about:blank has
   * already be loaded by this docShell.
   */
  [infallible] readonly attribute boolean hasLoadedNonBlankURI;

960
961
962
963
964
965
  /**
   * Allow usage of -moz-window-dragging:drag for content docshells.
   * True for top level chrome docshells. Throws if set to false with
   * top level chrome docshell.
   */
  attribute boolean windowDraggingAllowed;
966
967
968
969

  /**
   * Sets/gets the current scroll restoration mode.
   * @see https://html.spec.whatwg.org/#dom-history-scroll-restoration
970
   */
971
  attribute boolean currentScrollRestorationIsManual;
972

973
974
  /**
   * Setter and getter for the origin attributes living on this docshell.
975
   */
976
977
978
979
980
  [implicit_jscontext]
  jsval getOriginAttributes();

  [implicit_jscontext]
  void setOriginAttributes(in jsval aAttrs);
981
982
983
984
985

  /**
   * The editing session for this docshell.
   */
  readonly attribute nsIEditingSession editingSession;
986
987

  /**
988
   * The browser child for this docshell.
989
   */
990
991
  [binaryname(ScriptableBrowserChild)] readonly attribute nsIBrowserChild browserChild;
  [noscript,notxpcom,nostdcall] BrowserChildRef GetBrowserChild();
992

993
  [noscript,nostdcall,notxpcom] nsCommandManager GetCommandManager();
994

995
996
997
998
999
1000
  cenum TouchEventsOverride: 8 {
    /**
     * Override platform/pref default behaviour and force-disable touch events.
     */
    TOUCHEVENTS_OVERRIDE_DISABLED = 0,
    /**