/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * 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/. */ #include "domstubs.idl" #include "nsIDocShellTreeItem.idl" #include "nsIRequest.idl" %{ C++ #include "js/TypeDecls.h" #include "mozilla/Maybe.h" #include "mozilla/NotNull.h" #include "mozilla/UniquePtr.h" #include "nsCOMPtr.h" #include "nsIURI.h" class nsCommandManager; class nsPresContext; class nsDocShellLoadState; namespace mozilla { class Encoding; class HTMLEditor; class PresShell; namespace dom { class BrowsingContext; class ClientSource; } // namespace dom } %} /** * The nsIDocShell interface. */ [ptr] native nsPresContext(nsPresContext); [ptr] native nsCommandManager(nsCommandManager); [ptr] native PresShell(mozilla::PresShell); [ref] native MaybeURI(mozilla::Maybe>); [ref] native Encoding(const mozilla::Encoding*); native UniqueClientSource(mozilla::UniquePtr); interface nsIURI; interface nsIChannel; interface nsIContentSecurityPolicy; interface nsIDocumentViewer; interface nsIEditor; interface nsIEditingSession; interface nsIInputStream; interface nsIRequest; interface nsISHEntry; interface nsILayoutHistoryState; interface nsISecureBrowserUI; interface nsIScriptGlobalObject; interface nsIStructuredCloneContainer; interface nsIDOMStorage; interface nsIPrincipal; interface nsIPrivacyTransitionObserver; interface nsIReflowObserver; interface nsIScrollObserver; interface nsIRemoteTab; interface nsIBrowserChild; interface nsICommandParams; interface nsILoadURIDelegate; native BrowserChildRef(already_AddRefed); native nsDocShellLoadStatePtr(nsDocShellLoadState*); webidl BrowsingContext; webidl ContentFrameMessageManager; webidl EventTarget; webidl Document; /** * nsIDocShell is an interface corresponding to the native nsDocShell object, * which is a legacy in-process object roughly corresponding to a 'browsing * context', as created for a browser tab or an iframe, for example. * * nsIDocShell has a 1:1 relationship with its paired dom::BrowsingContext and * nsGlobalWindowOuter. It may be replaced during navigation. * * See also the comment documenting dom::BrowsingContext and the documentation * at: * * https://html.spec.whatwg.org/multipage/document-sequences.html#browsing-context * https://firefox-source-docs.mozilla.org/dom/navigation/embedding.html * https://firefox-source-docs.mozilla.org/dom/navigation/nav_replace.html */ [scriptable, builtinclass, uuid(049234fe-da10-478b-bc5d-bc6f9a1ba63d)] interface nsIDocShell : nsIDocShellTreeItem { void setCancelContentJSEpoch(in long aEpoch); /** * Loads a given URI. This will give priority to loading the requested URI * in the object implementing this interface. If it can't be loaded here * however, the URL dispatcher will go through its normal process of content * loading. * * @param aLoadState This is the extended load info for this load. * @param aSetNavigating If we should set isNavigating to true while initiating * the load. */ [noscript]void loadURI(in nsDocShellLoadStatePtr aLoadState, in boolean aSetNavigating); /** * Do either a history.pushState() or history.replaceState() operation, * depending on the value of aReplace. */ [implicit_jscontext] void addState(in jsval aData, in AString aTitle, in AString aURL, in boolean aReplace); /** * 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(); /** * Helper for the session store to change the URI associated with the * document. */ void setCurrentURIForSessionStore(in nsIURI aURI); /** * Notify the associated content viewer and all child docshells that they are * about to be hidden. If |isUnload| is true, then the document is being * unloaded and all dynamic subframe history entries are removed as well. * * @param isUnload * True to fire the unload event in addition to the pagehide event, * and remove all dynamic subframe history entries. */ [noscript] void firePageHideNotification(in boolean isUnload); /** * Presentation context for the currently loaded document. This may be null. */ [notxpcom,nostdcall] readonly attribute nsPresContext presContext; /** * Presentation shell for the currently loaded document. This may be null. */ [notxpcom,nostdcall] readonly attribute PresShell presShell; /** * Presentation shell for the oldest document, if this docshell is * currently transitioning between documents. */ [notxpcom,nostdcall] readonly attribute PresShell eldestPresShell; /** * Document Viewer that is currently loaded for this DocShell. This may * change as the underlying content changes. */ [infallible] readonly attribute nsIDocumentViewer docViewer; /** * Get the id of the outer window that is or will be in this docshell. */ [infallible] readonly attribute unsigned long long outerWindowID; /** * This attribute allows chrome to tie in to handle DOM events that may * be of interest to chrome. */ attribute EventTarget chromeEventHandler; /** * This allows chrome to set a custom User agent on a specific docshell */ attribute AString customUserAgent; /** * Whether CSS error reporting is enabled. */ attribute boolean cssErrorReportingEnabled; /** * Attribute stating if refresh based redirects can be allowed */ attribute boolean allowMetaRedirects; /** * Attribute stating if it should allow subframes (framesets/iframes) or not */ attribute boolean allowSubframes; /** * Attribute stating whether or not images should be loaded. */ attribute boolean allowImages; /** * Attribute stating whether or not media (audio/video) should be loaded. */ [infallible] attribute boolean allowMedia; /** * 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; /** * Attribute that determines whether window control (move/resize) is allowed. */ attribute boolean allowWindowControl; /** * 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; /** * True if new child docshells should allow content retargeting. * Setting allowContentRetargeting also overwrites this value. */ [infallible] attribute boolean allowContentRetargetingOnChildren; /** * Get an array of this docShell and its children. * * @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. */ cenum DocShellEnumeratorDirection : 8 { ENUMERATE_FORWARDS = 0, ENUMERATE_BACKWARDS = 1 }; Array getAllDocShellsInSubtree(in long aItemType, in nsIDocShell_DocShellEnumeratorDirection aDirection); /** * 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. */ cenum AppType : 8 { APP_TYPE_UNKNOWN = 0, APP_TYPE_MAIL = 1, APP_TYPE_EDITOR = 2 }; [infallible] attribute nsIDocShell_AppType appType; /** * certain docshells (like the message pane) * should not throw up auth dialogs * because it can act as a password trojan */ attribute boolean allowAuth; /** * 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 * no zoom. */ attribute float zoom; /* * Tells the docshell to offer focus to its tree owner. * This is currently only necessary for embedding chrome. * 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. */ bool tabToTreeOwner(in boolean forward, in boolean forDocumentNavigation); /** * Current busy state for DocShell */ 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; /** * Load commands for the document */ 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() }; /* * Attribute to access the loadtype for the document. LoadType Enum is * defined in nsDocShellLoadTypes.h */ [infallible] attribute unsigned long loadType; /* * Default load flags (as defined in nsIRequest) that will be set on all * requests made by this docShell and propagated to all child docShells and * to nsILoadGroup::defaultLoadFlags for the docShell's loadGroup. * 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; /* * returns true if the docshell is being destroyed, false otherwise */ boolean isBeingDestroyed(); /* * Returns true if the docshell is currently executing the onLoad Handler */ readonly attribute boolean isExecutingOnLoadHandler; attribute nsILayoutHistoryState layoutHistoryState; /** * 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. */ readonly attribute nsILoadURIDelegate loadURIDelegate; /** * 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(); /** * 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. */ void beginRestore(in nsIDocumentViewer viewer, in boolean top); /** * Finish firing WebProgressListener notifications and DOM events for * restoring a page presentation. This should only be called via * beginRestore(). */ void finishRestore(); void clearCachedUserAgent(); void clearCachedPlatform(); /* Track whether we're currently restoring a document presentation. */ readonly attribute boolean restoringDocument; /* attribute to access whether error pages are enabled */ attribute boolean useErrorPages; /** * 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 * * Returns whether or not we displayed an error page (note: will always * return false if in-content error pages are disabled!) */ boolean displayLoadError(in nsresult aError, in nsIURI aURI, in wstring aURL, [optional] in nsIChannel aFailedChannel); /** * The channel that failed to load and resulted in an error page. * May be null. Relevant only to error pages. */ readonly attribute nsIChannel failedChannel; /** * Keeps track of the previous nsISHEntry index and the current * nsISHEntry index at the time that the doc shell begins to load. * Used for ContentViewer eviction. */ readonly attribute long previousEntryIndex; readonly attribute long loadedEntryIndex; /** * 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); /** * Gets the channel for the currently loaded document, if any. * For a new document load, this will be the channel of the previous document * until after OnLocationChange fires. */ readonly attribute nsIChannel currentDocumentChannel; /** * Find out whether the docshell is currently in the middle of a page * transition. This is set just before the pagehide/unload events fire. */ [infallible] readonly attribute boolean isInUnload; /** * Disconnects this docshell's editor from its window, and stores the * editor data in the open document's session history entry. This * should be called only during page transitions. */ [noscript, notxpcom] void DetachEditorFromWindow(); /** * Propagated to the print preview document viewer. Must only be called on * a document viewer that has been initialized for print preview. */ void exitPrintPreview(); /** * The ID of the docshell in the session history. */ readonly attribute nsIDRef historyID; /** * Helper method for accessing this value from C++ */ [noscript, notxpcom] nsIDRef HistoryID(); /** * Create a new about:blank document and content viewer. * @param aPrincipal the principal to use for the new document. * @param aPartitionedPrincipal the partitioned principal to use for the new * document. * @param aCsp the CSP to use for the new document. */ void createAboutBlankDocumentViewer(in nsIPrincipal aPrincipal, in nsIPrincipal aPartitionedPrincipal, [optional] in nsIContentSecurityPolicy aCSP); /** * Upon getting, returns the canonical encoding label of the document * currently loaded into this docshell. */ readonly attribute ACString charset; void forceEncodingDetection(); /** * In a child docshell, this is the charset of the parent docshell */ [noscript, notxpcom, nostdcall] void setParentCharset( in Encoding parentCharset, in int32_t parentCharsetSource, in nsIPrincipal parentCharsetPrincipal); [noscript, notxpcom, nostdcall] void getParentCharset( out Encoding parentCharset, out int32_t parentCharsetSource, out nsIPrincipal parentCharsetPrincipal); /** * 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(); /** * 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); /** * 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); /** * 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(); /** * Returns true if this docshell is the top level content docshell. */ [infallible] readonly attribute boolean isTopLevelContentDocShell; /** * True iff asynchronous panning and zooming is enabled for this * docshell. */ readonly attribute bool asyncPanZoomEnabled; /** * 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; attribute nsIEditor editor; readonly attribute boolean editable; /* this docShell is editable */ readonly attribute boolean hasEditingSession; /* this docShell has an editing session */ /** * 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. */ void makeEditable(in boolean inWaitForUriLoad); /** * Returns false for mLSHE, true for mOSHE */ boolean getCurrentSHEntry(out nsISHEntry aEntry); /** * Cherry picked parts of nsIController. * They are here, because we want to call these functions * from JS. */ boolean isCommandEnabled(in string command); [can_run_script] void doCommand(in string command); [can_run_script] void doCommandWithParams(in string command, in nsICommandParams aParams); /** * 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(); [noscript, notxpcom] void SetInvisible(in bool aIsInvisibleDocshell); /** * Get the script global for the document in this docshell. */ [noscript,notxpcom,nostdcall] nsIScriptGlobalObject GetScriptGlobalObject(); [noscript,notxpcom,nostdcall] Document getExtantDocument(); /** * This attribute determines whether a document which is not about:blank has * already be loaded by this docShell. */ [infallible] readonly attribute boolean hasLoadedNonBlankURI; /** * 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; /** * Sets/gets the current scroll restoration mode. * @see https://html.spec.whatwg.org/#dom-history-scroll-restoration */ attribute boolean currentScrollRestorationIsManual; /** * Setter and getter for the origin attributes living on this docshell. */ [implicit_jscontext] jsval getOriginAttributes(); [implicit_jscontext] void setOriginAttributes(in jsval aAttrs); /** * The editing session for this docshell. */ readonly attribute nsIEditingSession editingSession; /** * The browser child for this docshell. */ [binaryname(ScriptableBrowserChild)] readonly attribute nsIBrowserChild browserChild; [noscript,notxpcom,nostdcall] BrowserChildRef GetBrowserChild(); [noscript,nostdcall,notxpcom] nsCommandManager GetCommandManager(); cenum MetaViewportOverride: 8 { /** * Override platform/pref default behaviour and force-disable support for * . */ META_VIEWPORT_OVERRIDE_DISABLED = 0, /** * Override platform/pref default behaviour and force-enable support for * . */ META_VIEWPORT_OVERRIDE_ENABLED = 1, /** * Don't override the platform/pref default behaviour for support for * . */ META_VIEWPORT_OVERRIDE_NONE = 2, }; /** * This allows chrome to override the default choice of whether the * tag is respected in a specific docshell. * Possible values are listed above. */ [infallible, setter_can_run_script] attribute nsIDocShell_MetaViewportOverride metaViewportOverride; /** * Attribute that determines whether tracking protection is enabled. */ attribute boolean useTrackingProtection; /** * Fire a dummy location change event asynchronously. */ [noscript] void dispatchLocationChangeEvent(); /** * Start delayed autoplay media which are in the current document. */ [noscript] void startDelayedAutoplayMediaComponents(); /** * Take ownership of the ClientSource representing an initial about:blank * document that was never needed. As an optimization we avoid creating * this document if no code calls GetDocument(), but we still need a * ClientSource object to represent the about:blank window. This may return * nullptr; for example if the docshell has created a real window and document * already. */ [noscript, nostdcall, notxpcom] UniqueClientSource TakeInitialClientSource(); void setColorMatrix(in Array aMatrix); /** * Returns true if the current load is a forced reload, * e.g. started by holding shift whilst triggering reload. */ readonly attribute bool isForceReloading; Array getColorMatrix(); %{C++ /** * These methods call nsDocShell::GetHTMLEditorInternal() and * nsDocShell::SetHTMLEditorInternal() with static_cast. */ mozilla::HTMLEditor* GetHTMLEditor(); nsresult SetHTMLEditor(mozilla::HTMLEditor* aHTMLEditor); %} /** * The message manager for this docshell. This does not throw, but * can return null if the docshell has no message manager. */ [infallible] readonly attribute ContentFrameMessageManager messageManager; /** * This returns a Promise which resolves to a boolean. True when the * document has Tracking Content that has been blocked from loading, false * otherwise. */ Promise getHasTrackingContentBlocked(); /** * Return whether this docshell is "attempting to navigate" in the * sense that's relevant to document.open. */ [notxpcom, nostdcall] readonly attribute boolean isAttemptingToNavigate; /* * Whether or not this docshell is executing a nsIWebNavigation navigation * method. * * This will be true when the following methods are executing: * nsIWebNavigation.binaryLoadURI * nsIWebNavigation.goBack * nsIWebNavigation.goForward * nsIWebNavigation.gotoIndex * nsIWebNavigation.loadURI */ [infallible] readonly attribute boolean isNavigating; /** * @see nsISHEntry synchronizeLayoutHistoryState(). */ void synchronizeLayoutHistoryState(); /** * This attempts to save any applicable layout history state (like * scroll position) in the nsISHEntry. This is normally done * automatically when transitioning from page to page in the * same process. We expose this function to support transitioning * from page to page across processes as a workaround for bug 1630234 * until session history state is moved into the parent process. */ void persistLayoutHistoryState(); };