diff options
Diffstat (limited to '')
| -rw-r--r-- | docshell/base/nsIDocShell.idl | 766 |
1 files changed, 766 insertions, 0 deletions
diff --git a/docshell/base/nsIDocShell.idl b/docshell/base/nsIDocShell.idl new file mode 100644 index 0000000000..21f09a517e --- /dev/null +++ b/docshell/base/nsIDocShell.idl @@ -0,0 +1,766 @@ +/* -*- 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<nsCOMPtr<nsIURI>>); +[ref] native Encoding(const mozilla::Encoding*); + native UniqueClientSource(mozilla::UniquePtr<mozilla::dom::ClientSource>); + +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<nsIBrowserChild>); +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<nsIDocShell> 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 name="viewport">. + */ + META_VIEWPORT_OVERRIDE_DISABLED = 0, + /** + * Override platform/pref default behaviour and force-enable support for + * <meta name="viewport">. + */ + META_VIEWPORT_OVERRIDE_ENABLED = 1, + /** + * Don't override the platform/pref default behaviour for support for + * <meta name="viewport">. + */ + META_VIEWPORT_OVERRIDE_NONE = 2, + }; + + /** + * This allows chrome to override the default choice of whether the + * <meta name="viewport"> 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<float> 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<float> 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(); +}; |