/* -*- 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/. */
* The nsIDocShell interface.
[ptr] native nsPresContext(nsPresContext);
[ptr] native nsIPresShell(nsIPresShell);
[scriptable, builtinclass, uuid(9b283337-097d-4fa8-a2da-916318eaf828)]
interface nsIDocShell : nsISupports
* 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
* @param uri - The URI to load.
* @param loadInfo - This is the extended load info for this load. This
* most often will be null, but if you need to do
* additional setup for this load you can get a loadInfo
* object by calling createLoadInfo. Once you have this
* object you can set the needed properties on it and
* then pass it to loadURI.
* @param aLoadFlags - Flags to modify load behaviour. Flags are defined in
* nsIWebNavigation. Note that using flags outside
* LOAD_FLAGS_MASK is only allowed if passing in a
* non-null loadInfo. And even some of those might not
* be allowed. Use at your own risk.
[noscript]void loadURI(in nsIURI uri,
in nsIDocShellLoadInfo loadInfo,
in unsigned long aLoadFlags,
in boolean firstParty);
* Loads a given stream. This will give priority to loading the requested
* stream in the object implementing this interface. If it can't be loaded
* here however, the URL dispatched will go through its normal process of
* content loading.
* @param aStream - The input stream that provides access to the data
* to be loaded. This must be a blocking, threadsafe
* stream implementation.
* @param aURI - The URI representing the stream, or null.
* @param aContentType - The type (MIME) of data being loaded (empty if unknown).
* @param aContentCharset - The charset of the data being loaded (empty if unknown).
* @param aLoadInfo - This is the extended load info for this load. This
* most often will be null, but if you need to do
* additional setup for this load you can get a
* loadInfo object by calling createLoadInfo. Once
* you have this object you can set the needed
* properties on it and then pass it to loadStream.
[noscript]void loadStream(in nsIInputStream aStream,
in nsIURI aURI,
in ACString aContentType,
in ACString aContentCharset,
in nsIDocShellLoadInfo aLoadInfo);
const long INTERNAL_LOAD_FLAGS_NONE = 0x0;
const long INTERNAL_LOAD_FLAGS_INHERIT_OWNER = 0x1;
const long INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER = 0x2;
const long INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x4;
// This flag marks the first load in this object
// @see nsIWebNavigation::LOAD_FLAGS_FIRST_LOAD
const long INTERNAL_LOAD_FLAGS_FIRST_LOAD = 0x8;
const long INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER = 0x10;
const long INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES = 0x20;
* Loads the given URI. This method is identical to loadURI(...) except
* that its parameter list is broken out instead of being packaged inside
* of an nsIDocShellLoadInfo object...
* @param aURI - The URI to load.
* @param aReferrer - Referring URI
* @param aOwner - Owner (security principal)
* @param aInheritOwner - Flag indicating whether the owner of the current
* document should be inherited if aOwner is null.
* @param aStopActiveDoc - Flag indicating whether loading the current
* document should be stopped.
* @param aWindowTarget - Window target for the load.
* @param aTypeHint - A hint as to the content-type of the resulting
* data. May be null or empty if no hint.
* @param aPostDataStream - Post data stream (if POSTing)
* @param aHeadersStream - Stream containing "extra" request headers...
* @param aLoadFlags - Flags to modify load behaviour. Flags are defined
* in nsIWebNavigation.
* @param aSHEntry - Active Session History entry (if loading from SH)
[noscript]void internalLoad(in nsIURI aURI,
in nsIURI aReferrer,
in nsISupports aOwner,
in uint32_t aFlags,
in wstring aWindowTarget,
in string aTypeHint,
in nsIInputStream aPostDataStream,
in nsIInputStream aHeadersStream,
in unsigned long aLoadFlags,
in nsISHEntry aSHEntry,
in boolean firstParty,
out nsIDocShell aDocShell,
out nsIRequest aRequest);
* Do either a history.pushState() or history.replaceState() operation,
* depending on the value of aReplace.
void addState(in nsIVariant aData, in DOMString aTitle,
in DOMString aURL, in boolean aReplace);
* Creates a DocShellLoadInfo object that you can manipulate and then pass
* to loadURI.
void createLoadInfo(out nsIDocShellLoadInfo loadInfo);
* 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().
* For editors and suchlike who wish to change the URI associated with the
* document. Note if you want to get the current URI, use the read-only
* property on nsIWebNavigation.
void setCurrentURI(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 as well.
* @param isUnload if true, fire the unload event in addition to the pagehide
[noscript] void firePageHideNotification(in boolean isUnload);
* Presentation context for the currently loaded document. This may be null.
[noscript] readonly attribute nsPresContext presContext;
* Presentation shell for the currently loaded document. This may be null.
[noscript] readonly attribute nsIPresShell presShell;
* Presentation shell for the oldest document, if this docshell is
* currently transitioning between documents.
[noscript] readonly attribute nsIPresShell eldestPresShell;
* Content Viewer that is currently loaded for this DocShell. This may
* change as the underlying content changes.
readonly attribute nsIContentViewer contentViewer;
* This attribute allows chrome to tie in to handle DOM events that may
* be of interest to chrome.
attribute nsIDOMEventTarget chromeEventHandler;
* Whether to allow plugin execution
attribute boolean allowPlugins;
* 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 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;
* Get an enumerator over 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.
const long ENUMERATE_FORWARDS = 0;
const long ENUMERATE_BACKWARDS = 1;
nsISimpleEnumerator getDocShellEnumerator(in long aItemType,
in long aDirection);
* The type of application that created this window
const unsigned long APP_TYPE_UNKNOWN = 0;
const unsigned long APP_TYPE_MAIL = 1;
const unsigned long APP_TYPE_EDITOR = 2;
attribute unsigned long appType;
* certain dochshells (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;
* The size, in CSS pixels, of the horizontal margins for the <body> of an
* HTML document in this docshel; used to implement the marginwidth attribute
* on HTML <frame>/<iframe> elements. A value smaller than zero indicates
* that the attribute was not set.
attribute long marginWidth;
* The size, in CSS pixels, of the vertical margins for the <body> of an HTML
* document in this docshel; used to implement the marginheight attribute on
* HTML <frame>/<iframe> elements. A value smaller than zero indicates that
* the attribute was not set.
attribute long marginHeight;
* Tells the docshell to offer focus to its tree owner.
* This is currently only necessary for embedding chrome.
void tabToTreeOwner(in boolean forward,
out boolean tookFocus);
* Current busy state for DocShell
const unsigned long BUSY_FLAGS_NONE = 0;
const unsigned long BUSY_FLAGS_BUSY = 1;
const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD = 2;
const unsigned long BUSY_FLAGS_PAGE_LOADING = 4;
* Load commands for the document
const unsigned long LOAD_CMD_NORMAL = 0x1; // Normal load
const unsigned long LOAD_CMD_RELOAD = 0x2; // Reload
const unsigned long LOAD_CMD_HISTORY = 0x4; // Load from history
const unsigned long LOAD_CMD_PUSHSTATE = 0x8; // History.pushState()
readonly attribute unsigned long busyFlags;
* attribute to access the loadtype for the document
attribute unsigned long loadType;
* returns true if the docshell is being destroyed, false otherwise
* Returns true if the docshell is currently executing the onLoad Handler
readonly attribute boolean isExecutingOnLoadHandler;
attribute nsILayoutHistoryState layoutHistoryState;
readonly attribute boolean shouldSaveLayoutState;
* The SecureBrowserUI object for this docshell. This is set by XUL
* <browser> or nsWebBrowser for their root docshell.
attribute nsISecureBrowserUI securityUI;
* 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.
* 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.
* 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 nsIContentViewer viewer, in boolean top);
* Finish firing WebProgressListener notifications and DOM events for
* restoring a page presentation. This should only be called via
/* Track whether we're currently restoring a document presentation. */
readonly attribute boolean restoringDocument;
/* attribute to access whether error pages are enabled */
attribute boolean useErrorPages;
* Keeps track of the previous SHTransaction index and the current
* SHTransaction index at the time that the doc shell begins to load.
* Used for ContentViewer eviction.
readonly attribute long previousTransIndex;
readonly attribute long loadedTransIndex;
* 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);
* Retrieves the WebApps session storage object for the supplied principal.
* @param principal returns a storage for this principal
* @param documentURI new storage will be created with reference to this
* document.documentURI that will appear in storage event
* @param create If true and a session storage object doesn't
* already exist, a new one will be created.
nsIDOMStorage getSessionStorageForPrincipal(in nsIPrincipal principal,
in DOMString documentURI,
in boolean create);
* Add a WebApps session storage object to the docshell.
* @param principal the principal the storage object is associated with
* @param storage the storage object to add
void addSessionStorage(in nsIPrincipal principal, in nsIDOMStorage storage);
* Clones all session storage objects and attaches them to the given docshell.
* Useful when duplicating tabs and their states.
* @param docShell the docshell to clone the sessionstorage objects to
void cloneSessionStoragesTo(in nsIDocShell docShell);
* Removes all WebApps session storage objects attached to the docshell.
* 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;
* Set the offset of this child in its container.
[noscript] void setChildOffset(in unsigned long offset);
* Find out whether the docshell is currently in the middle of a page
* transition. This is set just before the pagehide/unload events fire.
readonly attribute boolean isInUnload;
* Find out if the currently loaded document came from a suspicious channel
* (such as a JAR channel where the server-returned content type isn't a
* known JAR type).
readonly attribute boolean channelIsUnsafe;
* 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();
* If true, this browser is not visible in the traditional sense, but
* is actively being rendered to the screen (ex. painted on a canvas)
* and should be treated accordingly.
attribute boolean isOffScreenBrowser;
* If the current content viewer isn't initialized for print preview,
* it is replaced with one which is and to which an about:blank document
* is loaded.
readonly attribute nsIWebBrowserPrint printPreview;
* Whether this docshell can execute scripts based on its hierarchy.
* The rule of thumb here is that we disable js if this docshell or any
* of its parents disallow scripting, unless the only reason for js being
* disabled in this docshell is a parent docshell having a document that
* is in design mode. In that case, we explicitly allow scripting on the
* current docshell.
readonly attribute boolean canExecuteScripts;
* Sets whether a docshell is active. An active docshell is one that is
* visible, and thus is not a good candidate for certain optimizations
* like image frame discarding. Docshells are active unless told otherwise.
attribute boolean isActive;
* The ID of the docshell in the session history.
readonly attribute unsigned long long historyID;
* Sets whether a docshell is an app tab. An app tab docshell may behave
* differently than a non-app tab docshell in some cases, such as when
* handling link clicks. Docshells are not app tabs unless told otherwise.
attribute boolean isAppTab;
* Create a new about:blank document and content viewer.
* @param aPrincipal the principal to use for the new document.
void createAboutBlankContentViewer(in nsIPrincipal aPrincipal);
* The charset attribute allows the user to view, hint, and set which
* converter is used to read the document's data.
* <P>Inside Mozilla all text is encoded as Unicode. By standardizing
* on Unicode every piece of code that handles characters no longer
* needs to:
* Have access to a character encoding parameter.
* Ask is the data stateful?
* Ask is the data single byte?
* Ask is the data multi-byte?
* If multi-byte: have access to a routine that can
* determine how many bytes in the current character.
* When the document is read in a converter is used to convert
* the document's data to Unicode.
* The charset attribute provides the ability to:
* See what converter was used when inputting the documents
* Override the character set for documents where the specified
* fallback, or auto-detected character set is incorrect
* Get/sets the encoding (converter) used to read the
* document. Get returns the encoding used. Set forces
* (overrides) the encoding. After forcing the charset the
* embedding application will need to cause the data to be
* reparsed in order to update the DOM / display.
* A force also sets the fallback encoding for this frame.
attribute string charset;
* The charset forced by the user. When the charset attribute is set this
* attribute is set to the same value.
* XXX Could this be replaced by a boolean?
attribute nsIAtom forcedCharset;
* In a child docshell, this is the charset of the parent docshell
attribute nsIAtom parentCharset;
* In a child docshell, this is the source of parentCharset
* @see nsIParser
attribute int32_t parentCharsetSource;
* 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);
* Mark the docshell as a browser frame.
* This should be used for <iframe mozbrowser> but not for <iframe mozapp>.
* This method should not be called more than once.
* Returns true iff the docshell is marked as a browser frame.
[infallible] readonly attribute boolean isBrowserElement;
* Returns true iif the docshell is marked as an app frame.
[infallible] readonly attribute boolean isApp;
* Returns true iif the docshell is marked as a type that behaves like a
* content boundary.
[infallible] readonly attribute boolean isContentBoundary;
* Returns true iif the docshell is inside a browser element.
[infallible] readonly attribute boolean isInBrowserElement;
* Returns true iif the docshell is inside an application. However, it will
* return false if the docshell is inside a browser element that is inside
* an application.
* Note: Do not use this method for permissions checks! An app may contain
* an <iframe> pointing at arbitrary web code. This iframe's docshell will
* have isInApp() == true, but the iframe's content is not "app code", and
* so should not be granted more trust than vanilla web content.
* (For example, suppose when web content calls API method X, we show a
* permission prompt, but when "app code" calls method X, we don't. In this
* case, it would be /incorrect/ to show the permission prompt if
* If you're doing a security check, use the content's principal instead of
* this method.
[infallible] readonly attribute boolean isInApp;
* Returns if the docshell has a docshell that behaves as a content boundary
* in his parent hierarchy.
[infallible] readonly attribute boolean isBelowContentBoundary;
* Set the app id this docshell is associated with. The id has to be a valid
* app id. If the docshell isn't associated with any app, the value should be
* nsIScriptSecurityManager::NO_APP_ID. However, this is the default value if
* nothing is et.
* This method is [noscript] to reduce the scope. It should be used at very
* specific moments.
* Calling setAppId() will mark the frame as an app frame.
[noscript] void setAppId(in unsigned long appId);
* Returns the app id of the app the docshell is in. Returns
* nsIScriptSecurityManager::NO_APP_ID if the docshell is not in an app.
[infallible] readonly attribute unsigned long appId;
* True iff asynchronous panning and zooming is enabled for this
readonly attribute bool asyncPanZoomEnabled;
* Like GetSameTypeParent, except this ignores <iframe mozbrowser>
* The sandbox flags on the docshell. These reflect the value of the sandbox
* attribute of the associated IFRAME or CSP-protectable content, if
* existent. See the HTML5 spec for more details.
* These flags on the docshell reflect the current state of the sandbox
* attribute, which is modifiable. They are only used when loading new
* content, sandbox flags are also immutably set on the document when it is
* The sandbox flags of a document depend on the sandbox flags on its
* docshell and of its parent document, if any.
* See nsSandboxFlags.h for the possible flags.
attribute unsigned long sandboxFlags;
* Are plugins allowed in the current document loaded in this docshell ?
* (if there is one). This depends on whether plugins are allowed by this
* docshell itself or if the document is sandboxed and hence plugins should
* not be allowed.
[noscript, notxpcom] bool pluginsAllowedInCurrentDoc();