"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/docshell/base/nsIDocShell.idl" (17 Sep 2019, 43530 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) IDL source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "nsIDocShell.idl": 68.0.2_vs_69.0.

    1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
    2  *
    3  * This Source Code Form is subject to the terms of the Mozilla Public
    4  * License, v. 2.0. If a copy of the MPL was not distributed with this
    5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
    6 
    7 #include "domstubs.idl"
    8 #include "nsIDocShellTreeItem.idl"
    9 #include "nsIRequest.idl"
   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 namespace mozilla {
   22 class Encoding;
   23 class HTMLEditor;
   24 class PresShell;
   25 namespace dom {
   26 class BrowsingContext;
   27 class ClientSource;
   28 } // namespace dom
   29 }
   30 %}
   31 
   32 /**
   33  * The nsIDocShell interface.
   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 nsISimpleEnumerator;
   51 interface nsIInputStream;
   52 interface nsIRequest;
   53 interface nsISHEntry;
   54 interface nsILayoutHistoryState;
   55 interface nsISecureBrowserUI;
   56 interface nsIScriptGlobalObject;
   57 interface nsIStructuredCloneContainer;
   58 interface nsIDOMStorage;
   59 interface nsIPrincipal;
   60 interface nsIWebBrowserPrint;
   61 interface nsIPrivacyTransitionObserver;
   62 interface nsIReflowObserver;
   63 interface nsIScrollObserver;
   64 interface nsIRemoteTab;
   65 interface nsIBrowserChild;
   66 interface nsICommandParams;
   67 interface nsILoadURIDelegate;
   68 native BrowserChildRef(already_AddRefed<nsIBrowserChild>);
   69 native nsDocShellLoadStatePtr(nsDocShellLoadState*);
   70 
   71 webidl BrowsingContext;
   72 webidl ContentFrameMessageManager;
   73 webidl EventTarget;
   74 webidl Document;
   75 
   76 [scriptable, builtinclass, uuid(049234fe-da10-478b-bc5d-bc6f9a1ba63d)]
   77 interface nsIDocShell : nsIDocShellTreeItem
   78 {
   79   void setCancelContentJSEpoch(in long aEpoch);
   80 
   81   /**
   82    * Loads a given URI.  This will give priority to loading the requested URI
   83    * in the object implementing this interface.  If it can't be loaded here
   84    * however, the URL dispatcher will go through its normal process of content
   85    * loading.
   86    *
   87    * @param loadState   - This is the extended load info for this load.
   88    */
   89   [noscript]void loadURI(in nsDocShellLoadStatePtr loadState);
   90 
   91   /**
   92    * Do either a history.pushState() or history.replaceState() operation,
   93    * depending on the value of aReplace.
   94    */
   95   [implicit_jscontext]
   96   void addState(in jsval aData, in AString aTitle,
   97                 in AString aURL, in boolean aReplace);
   98 
   99   /**
  100    * Helper for addState and document.open that does just the
  101    * history-manipulation guts.
  102    *
  103    * Arguments the spec defines:
  104    *
  105    * @param aDocument the document we're manipulating.  This will get the new URI.
  106    * @param aNewURI the new URI.
  107    * @param aData The serialized state data.  May be null.
  108    * @param aTitle The new title.  May be empty.
  109    * @param aReplace whether this should replace the exising SHEntry.
  110    *
  111    * Arguments we need internally because deriving them from the
  112    * others is a bit complicated:
  113    *
  114    * @param aCurrentURI the current URI we're working with.  Might be null.
  115    * @param aEqualURIs whether the two URIs involved are equal.
  116    */
  117   [nostdcall]
  118   void updateURLAndHistory(in Document aDocument, in nsIURI aNewURI,
  119                            in nsIStructuredCloneContainer aData, in AString aTitle,
  120                            in boolean aReplace, in nsIURI aCurrentURI,
  121                            in boolean aEqualURIs);
  122 
  123   /**
  124    * Reset state to a new content model within the current document and the document
  125    * viewer.  Called by the document before initiating an out of band document.write().
  126    */
  127   void prepareForNewContentModel();
  128 
  129   /**
  130    * For editors and suchlike who wish to change the URI associated with the
  131    * document. Note if you want to get the current URI, use the read-only
  132    * property on nsIWebNavigation.
  133    */
  134   void setCurrentURI(in nsIURI aURI);
  135 
  136   /**
  137    * Notify the associated content viewer and all child docshells that they are
  138    * about to be hidden.  If |isUnload| is true, then the document is being
  139    * unloaded and all dynamic subframe history entries are removed as well.
  140    *
  141    * @param isUnload
  142    *        True to fire the unload event in addition to the pagehide event,
  143    *        and remove all dynamic subframe history entries.
  144    */
  145   [noscript] void firePageHideNotification(in boolean isUnload);
  146 
  147   /**
  148    * Presentation context for the currently loaded document.  This may be null.
  149    */
  150   [notxpcom,nostdcall] readonly attribute nsPresContext presContext;
  151 
  152   /**
  153    * Presentation shell for the currently loaded document.  This may be null.
  154    */
  155   [notxpcom,nostdcall] readonly attribute PresShell presShell;
  156 
  157   /**
  158    * Presentation shell for the oldest document, if this docshell is
  159    * currently transitioning between documents.
  160    */
  161   [notxpcom,nostdcall] readonly attribute PresShell eldestPresShell;
  162 
  163   /**
  164    * Content Viewer that is currently loaded for this DocShell.  This may
  165    * change as the underlying content changes.
  166    */
  167   readonly attribute nsIContentViewer contentViewer;
  168 
  169   /**
  170    * Get the id of the outer window that is or will be in this docshell.
  171    */
  172   [infallible] readonly attribute unsigned long long outerWindowID;
  173 
  174   /**
  175    * This attribute allows chrome to tie in to handle DOM events that may
  176    * be of interest to chrome.
  177    */
  178   attribute EventTarget chromeEventHandler;
  179 
  180   /**
  181    * This allows chrome to set a custom User agent on a specific docshell
  182    */
  183   attribute AString customUserAgent;
  184 
  185   /**
  186    * Whether CSS error reporting is enabled.
  187    */
  188   attribute boolean cssErrorReportingEnabled;
  189 
  190   /**
  191    * Whether to allow plugin execution
  192    */
  193   attribute boolean allowPlugins;
  194 
  195   /**
  196    * Whether to allow Javascript execution
  197    */
  198   attribute boolean allowJavascript;
  199 
  200   /**
  201    * Attribute stating if refresh based redirects can be allowed
  202    */
  203   attribute boolean allowMetaRedirects;
  204 
  205   /**
  206    * Attribute stating if it should allow subframes (framesets/iframes) or not
  207    */
  208   attribute boolean allowSubframes;
  209 
  210   /**
  211    * Attribute stating whether or not images should be loaded.
  212    */
  213   attribute boolean allowImages;
  214 
  215   /**
  216    * Attribute stating whether or not media (audio/video) should be loaded.
  217    */
  218   [infallible] attribute boolean allowMedia;
  219 
  220   /**
  221    * Attribute that determines whether DNS prefetch is allowed for this subtree
  222    * of the docshell tree.  Defaults to true.  Setting this will make it take
  223    * effect starting with the next document loaded in the docshell.
  224    */
  225   attribute boolean allowDNSPrefetch;
  226 
  227   /**
  228    * Attribute that determines whether window control (move/resize) is allowed.
  229    */
  230   attribute boolean allowWindowControl;
  231 
  232   /**
  233    * True if the docshell allows its content to be handled by a content listener
  234    * other than the docshell itself, including the external helper app service,
  235    * and false otherwise.  Defaults to true.
  236    */
  237   [infallible] attribute boolean allowContentRetargeting;
  238 
  239   /**
  240    * True if new child docshells should allow content retargeting.
  241    * Setting allowContentRetargeting also overwrites this value.
  242    */
  243   [infallible] attribute boolean allowContentRetargetingOnChildren;
  244 
  245   /**
  246    * True if this docShell should inherit the private browsing ID from
  247    * its parent when reparented.
  248    *
  249    * NOTE: This should *not* be set false in new code, or for docShells
  250    * inserted anywhere other than as children of panels.
  251    */
  252   [infallible] attribute boolean inheritPrivateBrowsingId;
  253 
  254   /**
  255    * Get an enumerator over this docShell and its children.
  256    *
  257    * @param aItemType  - Only include docShells of this type, or if typeAll,
  258    *                     include all child shells.
  259    *                     Uses types from nsIDocShellTreeItem.
  260    * @param aDirection - Whether to enumerate forwards or backwards.
  261    */
  262 
  263   cenum DocShellEnumeratorDirection : 8 {
  264     ENUMERATE_FORWARDS  = 0,
  265     ENUMERATE_BACKWARDS = 1
  266   };
  267 
  268   nsISimpleEnumerator getDocShellEnumerator(in long aItemType,
  269                                             in nsIDocShell_DocShellEnumeratorDirection aDirection);
  270 
  271   /**
  272    * The type of application that created this window.
  273    *
  274    * DO NOT DELETE, see bug 176166. For firefox, this value will always be
  275    * UNKNOWN. However, it is used heavily in Thunderbird/comm-central and we
  276    * don't really have a great replacement at the moment, so we'll just leave it
  277    * here.
  278    */
  279   cenum AppType : 8 {
  280     APP_TYPE_UNKNOWN = 0,
  281     APP_TYPE_MAIL    = 1,
  282     APP_TYPE_EDITOR  = 2
  283   };
  284 
  285   [infallible] attribute nsIDocShell_AppType appType;
  286 
  287   /**
  288    * certain docshells (like the message pane)
  289    * should not throw up auth dialogs
  290    * because it can act as a password trojan
  291    */
  292   attribute boolean allowAuth;
  293 
  294   /**
  295    * Set/Get the document scale factor.  When setting this attribute, a
  296    * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
  297    * not supporting zoom.  Implementations not supporting zoom should return
  298    * 1.0 all the time for the Get operation.  1.0 by the way is the default
  299    * of zoom.  This means 100% of normal scaling or in other words normal size
  300    * no zoom.
  301    */
  302   attribute float zoom;
  303 
  304   /*
  305    * The size, in CSS pixels, of the horizontal margins for the <body> of an
  306    * HTML document in this docshell; used to implement the marginwidth attribute
  307    * on HTML <frame>/<iframe> elements.  A value smaller than zero indicates
  308    * that the attribute was not set.
  309    */
  310   attribute long marginWidth;
  311 
  312   /*
  313    * The size, in CSS pixels, of the vertical margins for the <body> of an HTML
  314    * document in this docshell; used to implement the marginheight attribute on
  315    * HTML <frame>/<iframe> elements.  A value smaller than zero indicates that
  316    * the attribute was not set.
  317    */
  318   attribute long marginHeight;
  319 
  320   /*
  321    * Tells the docshell to offer focus to its tree owner.
  322    * This is currently only necessary for embedding chrome.
  323    * If forDocumentNavigation is true, then document navigation should be
  324    * performed, where only the root of documents are selected. Otherwise, the
  325    * next element in the parent should be returned. Returns true if focus was
  326    * successfully taken by the tree owner.
  327    */
  328   bool tabToTreeOwner(in boolean forward, in boolean forDocumentNavigation);
  329 
  330   /**
  331    * Current busy state for DocShell
  332    */
  333   cenum BusyFlags : 8 {
  334     BUSY_FLAGS_NONE             = 0,
  335     BUSY_FLAGS_BUSY             = 1,
  336     BUSY_FLAGS_BEFORE_PAGE_LOAD = 2,
  337     BUSY_FLAGS_PAGE_LOADING     = 4,
  338   };
  339 
  340   [infallible] readonly attribute nsIDocShell_BusyFlags busyFlags;
  341 
  342   /**
  343    * Load commands for the document
  344    */
  345   cenum LoadCommand : 8 {
  346     LOAD_CMD_NORMAL  = 0x1,   // Normal load
  347     LOAD_CMD_RELOAD  = 0x2,   // Reload
  348     LOAD_CMD_HISTORY = 0x4,   // Load from history
  349     LOAD_CMD_PUSHSTATE = 0x8, // History.pushState()
  350   };
  351 
  352   /*
  353    * Attribute to access the loadtype for the document. LoadType Enum is
  354    * defined in nsDocShellLoadTypes.h
  355    */
  356   [infallible] attribute unsigned long loadType;
  357 
  358   /*
  359    * Default load flags (as defined in nsIRequest) that will be set on all
  360    * requests made by this docShell and propagated to all child docShells and
  361    * to nsILoadGroup::defaultLoadFlags for the docShell's loadGroup.
  362    * Default is no flags.  Once set, only future requests initiated by the
  363    * docShell are affected, so in general, these flags should be set before
  364    * the docShell loads any content.
  365    */
  366   attribute nsLoadFlags defaultLoadFlags;
  367 
  368   /*
  369    * returns true if the docshell is being destroyed, false otherwise
  370    */
  371   boolean isBeingDestroyed();
  372 
  373   /*
  374    * Returns true if the docshell is currently executing the onLoad Handler
  375    */
  376   readonly attribute boolean isExecutingOnLoadHandler;
  377 
  378   attribute nsILayoutHistoryState layoutHistoryState;
  379 
  380   /**
  381    * The SecureBrowserUI object for this docshell.  This is set by XUL
  382    * <browser> or nsWebBrowser for their root docshell.
  383    */
  384   attribute nsISecureBrowserUI securityUI;
  385 
  386   /**
  387    * Object used to delegate URI loading to an upper context.
  388    * Currently only set for GeckoView to allow handling of load requests
  389    * at the application level.
  390    */
  391   attribute nsILoadURIDelegate loadURIDelegate;
  392 
  393   /**
  394    * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
  395    * and this docshell's children, recursively. The meta-refresh timers can be
  396    * restarted using resumeRefreshURIs().  If the timers are already suspended,
  397    * this has no effect.
  398    */
  399   void suspendRefreshURIs();
  400 
  401   /**
  402    * Restart the XPCOM timers for each meta-refresh URI in this docshell,
  403    * and this docshell's children, recursively.  If the timers are already
  404    * running, this has no effect.
  405    */
  406   void resumeRefreshURIs();
  407 
  408   /**
  409    * Begin firing WebProgressListener notifications for restoring a page
  410    * presentation. |viewer| is the content viewer whose document we are
  411    * starting to load.  If null, it defaults to the docshell's current content
  412    * viewer, creating one if necessary.  |top| should be true for the toplevel
  413    * docshell that is being restored; it will be set to false when this method
  414    * is called for child docshells.  This method will post an event to
  415    * complete the simulated load after returning to the event loop.
  416    */
  417   void beginRestore(in nsIContentViewer viewer, in boolean top);
  418 
  419   /**
  420    * Finish firing WebProgressListener notifications and DOM events for
  421    * restoring a page presentation.  This should only be called via
  422    * beginRestore().
  423    */
  424   void finishRestore();
  425 
  426   /* Track whether we're currently restoring a document presentation. */
  427   readonly attribute boolean restoringDocument;
  428 
  429   /* attribute to access whether error pages are enabled */
  430   attribute boolean useErrorPages;
  431 
  432   /**
  433    * Display a load error in a frame while keeping that frame's currentURI
  434    * pointing correctly to the page where the error ocurred, rather than to
  435    * the error document page. You must provide either the aURI or aURL parameter.
  436    *
  437    * @param  aError         The error code to be displayed
  438    * @param  aURI           nsIURI of the page where the error happened
  439    * @param  aURL           wstring of the page where the error happened
  440    * @param  aFailedChannel The channel related to this error
  441    *
  442    * Returns whether or not we displayed an error page (note: will always
  443    * return false if in-content error pages are disabled!)
  444    */
  445   boolean displayLoadError(in nsresult aError,
  446                            in nsIURI aURI,
  447                            in wstring aURL,
  448                            [optional] in nsIChannel aFailedChannel);
  449 
  450   /**
  451    * The channel that failed to load and resulted in an error page.
  452    * May be null. Relevant only to error pages.
  453    */
  454   readonly attribute nsIChannel failedChannel;
  455 
  456   /**
  457    * Keeps track of the previous nsISHEntry index and the current
  458    * nsISHEntry index at the time that the doc shell begins to load.
  459    * Used for ContentViewer eviction.
  460    */
  461   readonly attribute long previousEntryIndex;
  462   readonly attribute long loadedEntryIndex;
  463 
  464   /**
  465    * Notification that entries have been removed from the beginning of a
  466    * nsSHistory which has this as its rootDocShell.
  467    *
  468    * @param numEntries - The number of entries removed
  469    */
  470   void historyPurged(in long numEntries);
  471 
  472   /**
  473    * Gets the channel for the currently loaded document, if any.
  474    * For a new document load, this will be the channel of the previous document
  475    * until after OnLocationChange fires.
  476    */
  477   readonly attribute nsIChannel currentDocumentChannel;
  478 
  479   /**
  480    * The original offset of this child in its container. This property is -1 for
  481    * dynamically added docShells.
  482    */
  483   [notxpcom,nostdcall] attribute long childOffset;
  484 
  485   /**
  486    * Find out whether the docshell is currently in the middle of a page
  487    * transition. This is set just before the pagehide/unload events fire.
  488    */
  489   readonly attribute boolean isInUnload;
  490 
  491   /**
  492    * This attribute determines whether Mixed Active Content is loaded on the
  493    * document. When it is true, mixed active content was not blocked and has
  494    * loaded (or is about to load) on the page. When it is false, mixed active content
  495    * has not loaded on the page, either because there was no mixed active content
  496    * requests on the page or such requests were blocked by nsMixedContentBlocker.
  497    * This boolean is set to true in nsMixedContentBlocker if Mixed Active Content
  498    * is allowed (either explicitly on the page by the user or when the about:config
  499    * setting security.mixed_content.block_active_content is set to false).
  500    */
  501   [infallible] readonly attribute boolean hasMixedActiveContentLoaded;
  502 
  503    /**
  504    * This attribute determines whether a document has Mixed Active Content
  505    * that has been blocked from loading. When it is true, there is definitely
  506    * mixed active content on a page that has been blocked by
  507    * nsMixedContentBlocker.  When it is false, there may or may not be mixed
  508    * active content on a page, but if there is, it will load. Note that if the
  509    * about:config setting security.mixed_content.block_active_content is set
  510    * false, this boolean will be false, since blocking active content has been
  511    * disabled.
  512    */
  513   [infallible] readonly attribute boolean hasMixedActiveContentBlocked;
  514 
  515   /**
  516    * This attribute determines whether Mixed Display Content is loaded on the
  517    * document. When it is true, mixed display content was not blocked and has
  518    * loaded (or is about to load) on the page. Similar behavior to
  519    * hasMixedActiveContentLoaded.
  520    */
  521   [infallible] readonly attribute boolean hasMixedDisplayContentLoaded;
  522 
  523    /**
  524    * This attribute determines whether a document has Mixed Display Content
  525    * that has been blocked from loading. Similar behavior to
  526    * hasMixedActiveContentBlocked.
  527    */
  528   [infallible] readonly attribute boolean hasMixedDisplayContentBlocked;
  529 
  530    /**
  531    * This attribute determines whether a document has Tracking Content
  532    * that has been blocked from loading.
  533    */
  534   [infallible] readonly attribute boolean hasTrackingContentBlocked;
  535 
  536   /**
  537    * Disconnects this docshell's editor from its window, and stores the
  538    * editor data in the open document's session history entry.  This
  539    * should be called only during page transitions.
  540    */
  541   [noscript, notxpcom] void DetachEditorFromWindow();
  542 
  543   /**
  544    * If true, this browser is not visible in the traditional sense, but
  545    * is actively being rendered to the screen (ex. painted on a canvas)
  546    * and should be treated accordingly.
  547    **/
  548   attribute boolean isOffScreenBrowser;
  549 
  550   /**
  551    * Allows nsDocumentViewer to tell the top-level same-type docshell that
  552    * one of the documents under it is printing.
  553    */
  554   [noscript, notxpcom] void setIsPrinting(in boolean aIsPrinting);
  555 
  556   /**
  557    * This method should only be called on a docShell that has been specifically
  558    * created to display a print preview document.  If the current document
  559    * viewer isn't initialized for print preview when this method is called, it
  560    * is replaced with a new viewer with an about:blank document (with the URL
  561    * about:printpreview).  The viewer is then returned, ready for the print
  562    * preview document to be constructed when viewer.printPreview() is called.
  563    *
  564    * The same viewer will be returned on subsequent calls since various bits of
  565    * code assume that, once created, the viewer is never replaced.  Note,
  566    * however, that the viewer's document will be replaced with a new document
  567    * each time printPreview() is called on it (which is what we do to take
  568    * account of print preview settings changes).  Replacing the document
  569    * viewer's document breaks the normally unchanging 1:1 relationship between
  570    * a document and its viewer, but that seems to be okay.
  571    */
  572   nsIWebBrowserPrint initOrReusePrintPreviewViewer();
  573 
  574   /**
  575    * Propagated to the print preview document viewer.  Must only be called on
  576    * a document viewer that has been initialized for print preview.
  577    */
  578   void exitPrintPreview();
  579 
  580   /**
  581    * Whether this docshell can execute scripts based on its hierarchy.
  582    * The rule of thumb here is that we disable js if this docshell or any
  583    * of its parents disallow scripting.
  584    */
  585   [infallible] readonly attribute boolean canExecuteScripts;
  586 
  587   /**
  588    * Sets whether a docshell is active. An active docshell is one that is
  589    * visible, and thus is not a good candidate for certain optimizations
  590    * like image frame discarding. Docshells are active unless told otherwise.
  591    */
  592   [infallible] attribute boolean isActive;
  593 
  594   /**
  595    * The ID of the docshell in the session history.
  596    */
  597   readonly attribute nsIDPtr historyID;
  598 
  599   /**
  600    * Helper method for accessing this value from C++
  601    */
  602   [noscript, notxpcom] nsID HistoryID();
  603 
  604   /**
  605    * Sets whether a docshell is an app tab. An app tab docshell may behave
  606    * differently than a non-app tab docshell in some cases, such as when
  607    * handling link clicks. Docshells are not app tabs unless told otherwise.
  608    */
  609   attribute boolean isAppTab;
  610 
  611   /**
  612    * Create a new about:blank document and content viewer.
  613    * @param aPrincipal the principal to use for the new document.
  614    * @param aStoragePrincipal the storage principal to use for the new document.
  615    * @param aCsp the CSP to use for the new document.
  616    */
  617   void createAboutBlankContentViewer(in nsIPrincipal aPrincipal,
  618                                      in nsIPrincipal aStoragePrincipal,
  619                                      [optional] in nsIContentSecurityPolicy aCSP);
  620 
  621   /**
  622    * Upon getting, returns the canonical encoding label of the document
  623    * currently loaded into this docshell.
  624    *
  625    * Upon setting, sets forcedCharset for compatibility with legacy callers.
  626    */
  627   attribute ACString charset;
  628 
  629   /**
  630    * Called when the user chose an encoding override from the character
  631    * encoding menu. Separate from the setter for the charset property to avoid
  632    * extensions adding noise to the data.
  633    */
  634   void gatherCharsetMenuTelemetry();
  635 
  636   /**
  637    * The charset forced by the user.
  638    */
  639   attribute ACString forcedCharset;
  640 
  641   /**
  642    * In a child docshell, this is the charset of the parent docshell
  643    */
  644   [noscript, notxpcom, nostdcall] void setParentCharset(
  645     in Encoding parentCharset,
  646     in int32_t parentCharsetSource,
  647     in nsIPrincipal parentCharsetPrincipal);
  648   [noscript, notxpcom, nostdcall] void getParentCharset(
  649     out Encoding parentCharset,
  650     out int32_t parentCharsetSource,
  651     out nsIPrincipal parentCharsetPrincipal);
  652 
  653   /**
  654    * Whether the docShell records profile timeline markers at the moment
  655    */
  656   [infallible] attribute boolean recordProfileTimelineMarkers;
  657 
  658   /**
  659    * Return a DOMHighResTimeStamp representing the number of
  660    * milliseconds from an arbitrary point in time.  The reference
  661    * point is shared by all DocShells and is also used by timestamps
  662    * on markers.
  663    */
  664   DOMHighResTimeStamp now();
  665 
  666   /**
  667    * Returns and flushes the profile timeline markers gathered by the docShell
  668    */
  669   [implicit_jscontext]
  670   jsval popProfileTimelineMarkers();
  671 
  672   /**
  673    * Add an observer to the list of parties to be notified when this docshell's
  674    * private browsing status is changed. |obs| must support weak references.
  675    */
  676   void addWeakPrivacyTransitionObserver(in nsIPrivacyTransitionObserver obs);
  677 
  678   /**
  679    * Add an observer to the list of parties to be notified when reflows are
  680    * occurring. |obs| must support weak references.
  681    */
  682   void addWeakReflowObserver(in nsIReflowObserver obs);
  683 
  684   /**
  685    * Remove an observer from the list of parties to be notified about reflows.
  686    */
  687   void removeWeakReflowObserver(in nsIReflowObserver obs);
  688 
  689   /**
  690    * Notify all attached observers that a reflow has just occurred.
  691    *
  692    * @param interruptible if true, the reflow was interruptible.
  693    * @param start         timestamp when reflow started, in milliseconds since
  694    *                      navigationStart (accurate to 1/1000 of a ms)
  695    * @param end           timestamp when reflow ended, in milliseconds since
  696    *                      navigationStart (accurate to 1/1000 of a ms)
  697    */
  698   [noscript] void notifyReflowObservers(in bool interruptible,
  699                                         in DOMHighResTimeStamp start,
  700                                         in DOMHighResTimeStamp end);
  701 
  702   /**
  703    * Add an observer to the list of parties to be notified when scroll position
  704    * of some elements is changed.
  705    */
  706   [noscript] void addWeakScrollObserver(in nsIScrollObserver obs);
  707 
  708   /**
  709    * Add an observer to the list of parties to be notified when scroll position
  710    * of some elements is changed.
  711    */
  712   [noscript] void removeWeakScrollObserver(in nsIScrollObserver obs);
  713 
  714   /**
  715    * Notify all attached observers that the scroll position of some element
  716    * has changed.
  717    */
  718   [noscript] void notifyScrollObservers();
  719 
  720   /**
  721    * The type of iframe that this docshell lives.
  722    */
  723   cenum FrameType : 8 {
  724     FRAME_TYPE_REGULAR = 0,
  725     FRAME_TYPE_BROWSER = 1,
  726   };
  727   [infallible] attribute nsIDocShell_FrameType frameType;
  728 
  729   /**
  730    * Returns true if this docshell corresponds to an <iframe mozbrowser>.
  731    * <xul:browser> returns false here.
  732    */
  733   [infallible] readonly attribute boolean isMozBrowser;
  734 
  735   /**
  736    * Returns true if this docshell corresponds to an isolated <iframe
  737    * mozbrowser>.
  738    *
  739    * <xul:browser> is not considered to be a mozbrowser element.
  740    * <iframe mozbrowser noisolation> does not count as isolated since
  741    * isolation is disabled.  Isolation can only be disabled if the
  742    * containing document is chrome.
  743    */
  744   [infallible] readonly attribute boolean isIsolatedMozBrowserElement;
  745 
  746   /**
  747    * Returns true if this docshell corresponds to an isolated <iframe
  748    * mozbrowser> or if the docshell is contained in an isolated <iframe
  749    * mozbrowser>.
  750    *
  751    * <xul:browser> is not considered to be a mozbrowser element. <iframe
  752    * mozbrowser noisolation> does not count as isolated since isolation is
  753    * disabled.  Isolation can only be disabled if the containing document is
  754    * chrome.
  755    *
  756    * Our notion here of "contained in" means: Walk up the docshell hierarchy in
  757    * this process until we hit an <iframe mozbrowser> (or until the hierarchy
  758    * ends).  Return true iff the docshell we stopped on has
  759    * isIsolatedMozBrowserElement == true.
  760    */
  761   [infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
  762 
  763   /**
  764    * Returns true if this docshell corresponds to an <iframe mozbrowser>, or
  765    * if this docshell is contained in an <iframe mozbrowser>. <xul:browser>
  766    * returns false here.
  767    *
  768    * To compute this value, we walk up the docshell hierarchy.  If we encounter
  769    * a docshell with isMozBrowser before we hit the end of the hierarchy,
  770    * we return true.  Otherwise, we return false.
  771    */
  772   [infallible] readonly attribute boolean isInMozBrowser;
  773 
  774   /**
  775    * Returns true if this docshell is the top level content docshell.
  776    */
  777   [infallible] readonly attribute boolean isTopLevelContentDocShell;
  778 
  779   /**
  780    * Like nsIDocShellTreeItem::GetSameTypeParent, except this ignores <iframe
  781    * mozbrowser> boundaries.
  782    */
  783   nsIDocShell getSameTypeParentIgnoreBrowserBoundaries();
  784 
  785   /**
  786    * Like nsIDocShellTreeItem::GetSameTypeRootTreeItem, except this ignores
  787    * <iframe mozbrowser> boundaries.
  788    */
  789   nsIDocShell getSameTypeRootTreeItemIgnoreBrowserBoundaries();
  790 
  791   /**
  792    * True iff asynchronous panning and zooming is enabled for this
  793    * docshell.
  794    */
  795   readonly attribute bool asyncPanZoomEnabled;
  796 
  797   /**
  798    * The sandbox flags on the docshell. These reflect the value of the sandbox
  799    * attribute of the associated IFRAME or CSP-protectable content, if
  800    * existent. See the HTML5 spec for more details.
  801    * These flags on the docshell reflect the current state of the sandbox
  802    * attribute, which is modifiable. They are only used when loading new
  803    * content, sandbox flags are also immutably set on the document when it is
  804    * loaded.
  805    * The sandbox flags of a document depend on the sandbox flags on its
  806    * docshell and of its parent document, if any.
  807    * See nsSandboxFlags.h for the possible flags.
  808    */
  809   attribute unsigned long sandboxFlags;
  810 
  811   /**
  812    * When a new browsing context is opened by a sandboxed document, it needs to
  813    * keep track of the browsing context that opened it, so that it can be
  814    * navigated by it.  This is the "one permitted sandboxed navigator".
  815    */
  816   attribute nsIDocShell onePermittedSandboxedNavigator;
  817 
  818   /**
  819    * Returns true if we are sandboxed from aTargetDocShell.
  820    * aTargetDocShell - the browsing context we are attempting to navigate.
  821    */
  822   [noscript,notxpcom,nostdcall] bool isSandboxedFrom(in nsIDocShell aTargetDocShell);
  823 
  824   /**
  825    * This member variable determines whether a document has Mixed Active Content that
  826    * was initially blocked from loading, but the user has choosen to override the
  827    * block and allow the content to load. mMixedContentChannel is set to the document's
  828    * channel when the user allows mixed content. The nsMixedContentBlocker content policy
  829    * checks if the document's root channel matches the mMixedContentChannel.  If it matches,
  830    * then Mixed Content is loaded.  If it does match, mixed content is blocked.
  831    *
  832    * A match implies that there is definitely mixed active content on a page that was
  833    * initially blocked by nsMixedContentBlocker and then allowed and loaded by the user.
  834    * A miss imples that IF there is mixed active content on the page AND it was
  835    * blocked by nsMixedContentBlocker.cpp, the user has not choosen to override
  836    * the block. Note that if the about:config setting
  837    * security.mixed_content.block_active_content is set to false, this boolean
  838    * will be false, mMixedContentChannel will remain null since blocking active content has
  839    * been disabled and hence mMixedContentChannel will never be set.
  840    */
  841   attribute nsIChannel mixedContentChannel;
  842 
  843   /**
  844    * Checks whether the channel associated with the root docShell is equal to
  845    * mMixedContentChannel. If they are the same, allowMixedContent is set to true.
  846    * Checks if the root document has a secure connection. If it is, sets
  847    * rootHasSecureConnection to true. If the docShell is the root doc shell,
  848    * isRootDocShell is set to true.
  849    */
  850   void GetAllowMixedContentAndConnectionData(out boolean rootHasSecureConnection, out boolean allowMixedContent, out boolean isRootDocShell);
  851 
  852 
  853   /**
  854    * Are plugins allowed in the current document loaded in this docshell ?
  855    * (if there is one). This depends on whether plugins are allowed by this
  856    * docshell itself or if the document is sandboxed and hence plugins should
  857    * not be allowed.
  858    */
  859   [noscript, notxpcom] bool pluginsAllowedInCurrentDoc();
  860 
  861 
  862   /**
  863    * Attribute that determines whether fullscreen is allowed to be entered for
  864    * this subtree of the docshell tree. This is true when all iframes containing
  865    * this docshell have their "allowfullscreen" attribute set to "true".
  866    * fullscreenAllowed is only writable at content boundaries, where it is used
  867    * to propagate the value of the cross process parent's iframe's
  868    * "allowfullscreen" attribute to the child process. Setting
  869    * fullscreenAllowed on docshells which aren't content boundaries throws an
  870    * exception.
  871    */
  872   [infallible] readonly attribute boolean fullscreenAllowed;
  873 
  874   void setFullscreenAllowed(in boolean allowed);
  875 
  876   [notxpcom] uint32_t orientationLock();
  877   [notxpcom] void setOrientationLock(in uint32_t orientationLock);
  878 
  879   [noscript, infallible] attribute boolean affectPrivateSessionLifetime;
  880 
  881   /**
  882    * Indicates whether the UI may enable the character encoding menu. The UI
  883    * must disable the menu when this property is false.
  884    */
  885   [infallible] readonly attribute boolean mayEnableCharacterEncodingMenu;
  886 
  887   /**
  888    * Indicates that the character encoding was autodetected.
  889    */
  890   [infallible] readonly attribute boolean charsetAutodetected;
  891 
  892            attribute  nsIEditor editor;
  893   readonly attribute  boolean   editable;             /* this docShell is editable */
  894   readonly attribute  boolean   hasEditingSession;    /* this docShell has an editing session */
  895 
  896   /**
  897    * Make this docShell editable, setting a flag that causes
  898    * an editor to get created, either immediately, or after
  899    * a url has been loaded.
  900    *      @param  inWaitForUriLoad    true to wait for a URI before
  901    *                                  creating the editor.
  902    */
  903   void makeEditable(in boolean inWaitForUriLoad);
  904 
  905   /**
  906    * Get the SHEntry associated with a child docshell
  907    */
  908   nsISHEntry getChildSHEntry(in long aChildOffset);
  909 
  910   /**
  911    * Add a Child SHEntry for a frameset page, given the child's loadtype.
  912    * If aCloneChildren is true, then aCloneReference's children will be
  913    * cloned onto aHistoryEntry.
  914    */
  915   void addChildSHEntry(in nsISHEntry aCloneReference,
  916                        in nsISHEntry aHistoryEntry,
  917                        in long aChildOffset,
  918                        in unsigned long aLoadType,
  919                        in boolean aCloneChilden);
  920 
  921   /**
  922    * Whether this docshell should save entries in global history.
  923    */
  924   attribute boolean useGlobalHistory;
  925 
  926   /**
  927    * Removes nsISHEntry objects related to this docshell from session history.
  928    * Use this only with subdocuments, like iframes.
  929    */
  930   void removeFromSessionHistory();
  931 
  932   /**
  933    * Set when an iframe/frame is added dynamically.
  934    */
  935   [infallible] attribute boolean createdDynamically;
  936 
  937   /**
  938    * Returns false for mLSHE, true for mOSHE
  939    */
  940   boolean getCurrentSHEntry(out nsISHEntry aEntry);
  941 
  942   /**
  943     * Cherry picked parts of nsIController.
  944     * They are here, because we want to call these functions
  945     * from JS.
  946     */
  947   boolean isCommandEnabled(in string command);
  948   [can_run_script]
  949   void doCommand(in string command);
  950   [can_run_script]
  951   void doCommandWithParams(in string command, in nsICommandParams aParams);
  952 
  953   /**
  954    * Invisible DocShell are dummy construct to simulate DOM windows
  955    * without any actual visual representation. They have to be marked
  956    * at construction time, to avoid any painting activity.
  957    */
  958   [noscript, notxpcom] bool IsInvisible();
  959   [noscript, notxpcom] void SetInvisible(in bool aIsInvisibleDocshell);
  960 
  961 /**
  962  * Get the script global for the document in this docshell.
  963 */
  964   [noscript,notxpcom,nostdcall] nsIScriptGlobalObject GetScriptGlobalObject();
  965 
  966   /**
  967    * If deviceSizeIsPageSize is set to true, device-width/height media queries
  968    * will be calculated from the page size, not the device size.
  969    *
  970    * Used by the Responsive Design Mode and B2G Simulator.
  971    *
  972    * Default is False.
  973    * Default value can be overriden with
  974    * docshell.device_size_is_page_size pref.
  975    */
  976   [infallible] attribute boolean deviceSizeIsPageSize;
  977 
  978   /**
  979    * Regarding setOpener / getOpener - We can't use XPIDL's "attribute"
  980    * for notxpcom, so we're relegated to using explicit gets / sets. This
  981    * should be fine, considering that these methods should only ever be
  982    * called from native code.
  983    */
  984   [noscript,notxpcom,nostdcall] void setOpener(in nsIRemoteTab aOpener);
  985   [noscript,notxpcom,nostdcall] nsIRemoteTab getOpener();
  986 
  987   /**
  988    * Notify DocShell when the browser is about to start executing JS, and after
  989    * that execution has stopped.  This only occurs when the Timeline devtool
  990    * is collecting information.
  991    */
  992   [noscript,notxpcom,nostdcall] void notifyJSRunToCompletionStart(in string aReason,
  993                                                                   in wstring functionName,
  994                                                                   in wstring fileName,
  995                                                                   in unsigned long lineNumber,
  996                                                                   in jsval asyncStack,
  997                                                                   in string asyncCause);
  998   [noscript,notxpcom,nostdcall] void notifyJSRunToCompletionStop();
  999 
 1000   [noscript] void GetOSHEId(out uint32_t aSHEntryId);
 1001 
 1002   /**
 1003    * This attribute determines whether a document which is not about:blank has
 1004    * already be loaded by this docShell.
 1005    */
 1006   [infallible] readonly attribute boolean hasLoadedNonBlankURI;
 1007 
 1008   /**
 1009    * Allow usage of -moz-window-dragging:drag for content docshells.
 1010    * True for top level chrome docshells. Throws if set to false with
 1011    * top level chrome docshell.
 1012    */
 1013   attribute boolean windowDraggingAllowed;
 1014 
 1015   /**
 1016    * Sets/gets the current scroll restoration mode.
 1017    * @see https://html.spec.whatwg.org/#dom-history-scroll-restoration
 1018    */
 1019   attribute boolean currentScrollRestorationIsManual;
 1020 
 1021   /**
 1022    * Setter and getter for the origin attributes living on this docshell.
 1023    */
 1024   [implicit_jscontext]
 1025   jsval getOriginAttributes();
 1026 
 1027   [implicit_jscontext]
 1028   void setOriginAttributes(in jsval aAttrs);
 1029 
 1030   /**
 1031    * The editing session for this docshell.
 1032    */
 1033   readonly attribute nsIEditingSession editingSession;
 1034 
 1035   /**
 1036    * The browser child for this docshell.
 1037    */
 1038   [binaryname(ScriptableBrowserChild)] readonly attribute nsIBrowserChild browserChild;
 1039   [noscript,notxpcom,nostdcall] BrowserChildRef GetBrowserChild();
 1040 
 1041   [noscript,nostdcall,notxpcom] nsCommandManager GetCommandManager();
 1042 
 1043   cenum TouchEventsOverride: 8 {
 1044     /**
 1045      * Override platform/pref default behaviour and force-disable touch events.
 1046      */
 1047     TOUCHEVENTS_OVERRIDE_DISABLED = 0,
 1048     /**
 1049      * Override platform/pref default behaviour and force-enable touch events.
 1050      */
 1051     TOUCHEVENTS_OVERRIDE_ENABLED = 1,
 1052     /**
 1053      * Don't override the platform/pref default behaviour for touch events.
 1054      */
 1055     TOUCHEVENTS_OVERRIDE_NONE = 2,
 1056   };
 1057 
 1058   /**
 1059    * This allows chrome to override the default choice of whether touch events
 1060    * are available on a specific docshell. Possible values are listed below.
 1061    */
 1062   [infallible] attribute nsIDocShell_TouchEventsOverride touchEventsOverride;
 1063 
 1064   cenum MetaViewportOverride: 8 {
 1065     /**
 1066      * Override platform/pref default behaviour and force-disable support for
 1067      * <meta name="viewport">.
 1068      */
 1069     META_VIEWPORT_OVERRIDE_DISABLED = 0,
 1070     /**
 1071      * Override platform/pref default behaviour and force-enable support for
 1072      * <meta name="viewport">.
 1073      */
 1074     META_VIEWPORT_OVERRIDE_ENABLED = 1,
 1075     /**
 1076      * Don't override the platform/pref default behaviour for support for
 1077      * <meta name="viewport">.
 1078      */
 1079     META_VIEWPORT_OVERRIDE_NONE = 2,
 1080   };
 1081 
 1082   /**
 1083    * This allows chrome to override the default choice of whether the
 1084    * <meta name="viewport"> tag is respected in a specific docshell.
 1085    * Possible values are listed above.
 1086    */
 1087   [infallible] attribute nsIDocShell_MetaViewportOverride metaViewportOverride;
 1088 
 1089   /**
 1090    * This value is `true` if its corresponding unit of related browsing contexts
 1091    * (TabGroup) contains only 1 toplevel window, and that window is the outer
 1092    * window corresponding to this docshell.
 1093    *
 1094    * The value is `false` otherwise. This is the case if the docshell is an
 1095    * iframe, has window.opener set, or another window with window.opener
 1096    * referring to this window exists.
 1097    *
 1098    * If this value is `false`, it would be web content visible for a load
 1099    * occuring in this docshell to be performed within a different docshell.
 1100    */
 1101   [infallible] readonly attribute boolean isOnlyToplevelInTabGroup;
 1102 
 1103   /**
 1104    * Returns `true` if this docshell was created due to a Large-Allocation
 1105    * header, and has not seen the initiating load yet.
 1106    */
 1107   [infallible] readonly attribute boolean awaitingLargeAlloc;
 1108 
 1109   /**
 1110    * Attribute that determines whether tracking protection is enabled.
 1111    */
 1112   attribute boolean useTrackingProtection;
 1113 
 1114  /**
 1115   * Fire a dummy location change event asynchronously.
 1116   */
 1117   [noscript] void dispatchLocationChangeEvent();
 1118 
 1119 
 1120   /**
 1121    * Start delayed autoplay media which are in the current document.
 1122    */
 1123   [noscript] void startDelayedAutoplayMediaComponents();
 1124 
 1125   /**
 1126    * Take ownership of the ClientSource representing an initial about:blank
 1127    * document that was never needed.  As an optimization we avoid creating
 1128    * this document if no code calls GetDocument(), but we still need a
 1129    * ClientSource object to represent the about:blank window.  This may return
 1130    * nullptr; for example if the docshell has created a real window and document
 1131    * already.
 1132    */
 1133   [noscript, nostdcall, notxpcom]
 1134   UniqueClientSource TakeInitialClientSource();
 1135 
 1136   void setColorMatrix([array, size_is(aMatrixLen)] in float aMatrix,
 1137                       [optional] in unsigned long aMatrixLen);
 1138 
 1139   void getColorMatrix([optional] out unsigned long aMatrixLen,
 1140                       [array, size_is(aMatrixLen), retval] out float aMatrix);
 1141 
 1142   /**
 1143    * Initialize session history for this docshell. The docshell must be the root
 1144    * docshell.
 1145    */
 1146   void initSessionHistory();
 1147 
 1148 %{C++
 1149   /**
 1150    * These methods call nsDocShell::GetHTMLEditorInternal() and
 1151    * nsDocShell::SetHTMLEditorInternal() with static_cast.
 1152    */
 1153   mozilla::HTMLEditor* GetHTMLEditor();
 1154   nsresult SetHTMLEditor(mozilla::HTMLEditor* aHTMLEditor);
 1155 %}
 1156 
 1157   /**
 1158    * BrowsingContext associated with the DocShell.
 1159    */
 1160   readonly attribute BrowsingContext browsingContext;
 1161 
 1162   /**
 1163    * Allowed CSS display modes. This needs to be kept in
 1164    * sync with similar values in ServoStyleConsts.h
 1165    */
 1166   cenum DisplayMode: 8 {
 1167     DISPLAY_MODE_BROWSER = 0,
 1168     DISPLAY_MODE_MINIMAL_UI = 1,
 1169     DISPLAY_MODE_STANDALONE = 2,
 1170     DISPLAY_MODE_FULLSCREEN = 3,
 1171   };
 1172 
 1173   /**
 1174    * Display mode for this docshell. Defaults to DISPLAY_MODE_BROWSER.
 1175    * Media queries only look at the value in the top-most docshell.
 1176    */
 1177   [infallible] attribute nsIDocShell_DisplayMode displayMode;
 1178 
 1179   /**
 1180    * The message manager for this docshell.  This does not throw, but
 1181    * can return null if the docshell has no message manager.
 1182    */
 1183   [infallible] readonly attribute ContentFrameMessageManager messageManager;
 1184 
 1185   /**
 1186    * Asynchronously retrieve a JSON string representing a log of the
 1187    * content blocking events happened so far in the current tab from the
 1188    * content process.
 1189    *
 1190    * This returns a Promise which resolves to a string on success, and is
 1191    * rejected on failure.  For documentation on the string format, please
 1192    * see nsISecureBrowserUI.contentBlockingLogJSON.
 1193    */
 1194   Promise getContentBlockingLog();
 1195 
 1196   /**
 1197    * Return whether this docshell is "attempting to navigate" in the
 1198    * sense that's relevant to document.open.
 1199    */
 1200   [notxpcom, nostdcall] readonly attribute boolean isAttemptingToNavigate;
 1201 
 1202   /**
 1203    * Whether developer tools are watching activity in this docshell.
 1204    */
 1205   [infallible] attribute boolean watchedByDevtools;
 1206 
 1207   /*
 1208    * Whether or not this docshell is executing a nsIWebNavigation navigation
 1209    * method.
 1210    *
 1211    * This will be true when the following methods are executing:
 1212    *   nsIWebNavigation.binaryLoadURI
 1213    *   nsIWebNavigation.goBack
 1214    *   nsIWebNavigation.goForward
 1215    *   nsIWebNavigation.gotoIndex
 1216    *   nsIWebNavigation.loadURI
 1217    */
 1218   [infallible] readonly attribute boolean isNavigating;
 1219 };