nsIDocShell

??? need a description here ???
Inherits from: nsISupports Last changed in Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9)

Implemented by @mozilla.org/docshell;1. Do not create an instance directly. Instead, retrieve an nsIDocShell from a browser or other document container element. Note that out-of-process browsers do not have an nsIDocShell; instead you can access the nsIDocShell object from a frame script.

Method overview

void addSessionStorage(in nsIPrincipal principal, in nsIDOMStorage storage);
void addState(in nsIVariant aData, in DOMString aTitle, in DOMString aURL, in boolean aReplace);
void beginRestore(in nsIContentViewer viewer, in boolean top);
void createAboutBlankContentViewer(in nsIPrincipal aPrincipal);
void createLoadInfo(out nsIDocShellLoadInfo loadInfo);
void DetachEditorFromWindow(); Violates the XPCOM interface guidelines
void finishRestore();
void firePageHideNotification(in boolean isUnload); Native code only!
void fireUnloadNotification(); Native code only! Obsolete since Gecko 1.8
nsISimpleEnumerator getDocShellEnumerator(in long aItemType, in long aDirection);
nsIDOMStorage getSessionStorageForPrincipal(in nsIPrincipal principal, in DOMString documentURI, in boolean create);
nsIDOMStorage getSessionStorageForURI(in nsIURI uri, in DOMString documentURI);
void historyPurged(in long numEntries);
void internalLoad(in nsIURI aURI, in nsIURI aReferrer, in nsISupports aOwner, in PRUint32 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); Native code only!
boolean isBeingDestroyed();
void loadStream(in nsIInputStream aStream, in nsIURI aURI, in ACString aContentType, in ACString aContentCharset, in nsIDocShellLoadInfo aLoadInfo); Native code only!
void loadURI(in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags, in boolean firstParty); Native code only!
void prepareForNewContentModel();
void resumeRefreshURIs();
void setChildOffset(in unsigned long offset); Native code only!
void setCurrentURI(in nsIURI aURI);
void suspendRefreshURIs();
void tabToTreeOwner(in boolean forward, out boolean tookFocus);

Attributes

Attribute Type Description
allowAuth boolean Certain dochshells (like the message pane) should not throw up auth dialogs because it can act as a password trojan.
allowDNSPrefetch boolean 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.
allowImages boolean Attribute stating whether or not images should be loaded.
allowJavascript boolean Whether to allow Javascript execution.
allowMetaRedirects boolean Attribute stating if refresh based redirects can be allowed.
allowPlugins boolean Whether to allow plugin execution.
allowSubframes boolean Attribute stating if it should allow subframes (framesets/iframes) or not.
allowWindowControl boolean Specifies whether or not content is allowed to control the window (that is, to resize or move the window). Default is true, which lets content control the window.
appType unsigned long The type of application that created this window. Types are defined in Constants.
busyFlags unsigned long Current busy state for DocShell. Valid states are defined in Constants. Read only.
canExecuteScripts boolean 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. Read only.
canvasHasFocus boolean Tells the docshell whether the canvas should have focus. Called by the focus manager when the user tabs to the frame rather than an element. Obsolete since Gecko 1.9.2
channelIsUnsafe boolean Find out if the currently loaded document came from a suspicious channel (such as a JAR channel where the server-returned content type is not a known JAR type). Read only.
charset string

The converter to use when reading the document's data.

In Mozilla code, all text is encoded as Unicode. When reading a document, a converter is used to translate the text from its original format into Unicode. This attribute lets you:

  • See what converter was used when retrieving the document's data.
  • Override that character set for documents for which the specified fallback or auto-detected character set is incorrect.

Reading this value reports the encoding that was used when loading the data into the document. Setting this attribute overrides the encoding; however, to update the DOM or display of the content, you need have the data reparsed.

Overriding the character set also sets the fallback encoding for the container frame.

Note: Prior to Gecko 12.0, this attribute was part of a separate nsIDocCharset interface.

chromeEventHandler nsIDOMEventTarget Events generated in the frame bubble up to its chromeEventHandler. In the case of a content frame or subframe this is the containing chrome frame. In the case of a chrome frame this is the same as the frame element. This attribute allows chrome to tie in to handle DOM events that may be of interest to chrome.
contentViewer nsIContentViewer Content Viewer that is currently loaded for this DocShell. This may change as the underlying content changes. Read only.
currentDocumentChannel nsIChannel 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. Read only.
documentCharsetInfo nsIDocumentCharsetInfo

The document character set info. This is used by a load to determine priorities for charset detection and so on. Obsolete since Gecko 12.0

Note: The properties of the old nsIDocumentCharsetInfo interface were merged into nsIDocShell in Gecko 12.0.

eldestPresShell nsIPresShell Presentation shell for the oldest document, if this docshell is currently transitioning between documents. Read only. Native code only!
forcedCharset nsIAtom

A character set to override the page's default character set while processing; this is tried before using any other character set during page loads.

Note: Prior to Gecko 12.0, this attribute was part of a separate nsIDocCharsetInfo interface.

hasFocus boolean Tells the DocShell that it now has focus or has lost focus. Obsolete since Gecko 1.9.2
historyID unsigned long long The ID of the docshell in the session history. Read only.
isActive boolean

Indicates whether or not the DocShell is currently active. An active DocShell is one that is currently visible, which means it's not a good candidate for optimizations such as image frame discarding. DocShells are active if this is true, which is the default state.

Note: Starting in Gecko 8.0, isActive is false for documents in minimized windows.

isAppTab boolean 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.
isExecutingOnLoadHandler boolean Returns true if the docshell is currently executing the onLoad Handler. Read only.
isInUnload boolean Find out whether the docshell is currently in the middle of a page transition (after the onunload event has fired, but before the new document has been set up) Read only.
isOffScreenBrowser boolean If true, this docshell is not visible in the traditional sense, but is being actively rendered to the screen (such as by being painted to a canvas), and should be treated accordingly.
layoutHistoryState nsILayoutHistoryState  
loadedTransIndex long 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. Read only.
loadType unsigned long Load type for the document. Valid states are defined in Constants. Note that nsIDocShell may use other states internally so you should check for the specific state bit.
marginHeight long The value of the marginheight attribute on the frame element, or negative if it was not set.
marginWidth long The value of the marginwidth attribute on the frame element, or negative if it was not set.
parentCharset nsIAtom

Indicates the DocShell's parent document's character set.

Note: Prior to Gecko 12.0, this attribute was part of a separate nsIDocCharsetInfo interface.

parentCharsetSource PRInt32

Indicates the source from which the character set being used was obtained. Higher numbers override lower ones. See Character set source constants for defined values.

Note: Prior to Gecko 12.0, this attribute was part of a separate nsIDocCharsetInfo interface.

parentURIContentListener nsIURIContentListener URI content listener parent. This is not refcounted and is assumed to be nulled out by the parent when the parent is going away. Obsolete since Gecko 1.8
presContext nsPresContext Presentation context for the currently loaded document. This may be null. Read only. Native code only!
presShell nsIPresShell Presentation shell for the currently loaded document. This may be null. Read only. Native code only!
previousTransIndex long 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. Read only.
printPreview nsIWebBrowserPrint If the current content viewer is not initialized for print preview, it is replaced with one which is and to which an about:blank document is loaded. Read only.
restoringDocument boolean Track whether we're currently restoring a document presentation. Read only.
securityUI nsISecureBrowserUI The SecureBrowserUI object for this docshell. This is set by browser or nsWebBrowser for their root docshell.
shouldSaveLayoutState boolean Indicates whether the current page can be cached. Read only.
useErrorPages boolean Attribute to access whether error pages are enabled.
zoom float 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.

Constants

Constant Value Description
INTERNAL_LOAD_FLAGS_NONE 0x0 Used as a placeholder when you don't want to explicitly specify flags.
INTERNAL_LOAD_FLAGS_INHERIT_OWNER 0x1 Used to indicate that it may be safe to inherit the owner of a javascript: or data: URL from the existing document.
INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER 0x2 Used to indicate that the load was caused by a meta refresh and the current document URI shouldn't be sent as the HTTP referrer.
INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP 0x4 Used to indicate that LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP was passed as one of the flags to loadURI().
INTERNAL_LOAD_FLAGS_FIRST_LOAD 0x8 This flag marks the first load in this object. See nsIWebNavigation.LOAD_FLAGS_FIRST_LOAD.
INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER 0x10 Used to indicate that LOAD_FLAGS_BYPASS_CLASSIFIER was passed as one of the flags to loadURI().
INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES 0x20 Used to indicate that LOAD_FLAGS_FORCE_ALLOW_COOKIES was passed as one of the flags to loadURI().
ENUMERATE_FORWARDS 0 Used by getDocShellEnumerator()to determine the direction of the enumeration.
ENUMERATE_BACKWARDS 1 Used by getDocShellEnumerator()to determine the direction of the enumeration.
APP_TYPE_UNKNOWN 0 This is the default value of the appType attribute.
APP_TYPE_MAIL 1 This is the value of the appType attribute used by Thunderbird and SeaMonkey to indicate that email messages are displayed in this window.
APP_TYPE_EDITOR 2 This is the value of the appType attribute used by Thunderbird and SeaMonkey to indicate that email messages or web pages are composed in this window.
BUSY_FLAGS_NONE 0 Returned by the busyFlags attribute when the nsIDocShell is not loading a document.
BUSY_FLAGS_BUSY 1 Returned by the busyFlags attribute when the nsIDocShell is loading a document from the network.
BUSY_FLAGS_BEFORE_PAGE_LOAD 2 Returned by the busyFlags attribute when the nsIDocShell has started loading a document from the network, but no data has been received yet.
BUSY_FLAGS_PAGE_LOADING 4 Returned by the busyFlags attribute when the nsIDocShell is receiving data from the network.
LOAD_CMD_NORMAL 0x1 Returned by the loadType attribute for normal loads.
LOAD_CMD_RELOAD 0x2 Returned by the loadType attribute for reloads.
LOAD_CMD_HISTORY 0x4 Returned by the loadType attribute for history navigation.
LOAD_CMD_PUSHSTATE 0x8 Returned by the loadType attribute when the page has used history.pushState()

Character set source constants

These constants are not exposed to script. They are used internally as values for the parentCharsetSource attribute.

Constant Value Description
kCharsetUninitialized 0 The character set has not yet been initialized.
kCharsetFromWeakDocTypeDefault 1  
kCharsetFromUserDefault 2 The user's default character set is being used.
kCharsetFromDocTypeDefault 3 The character set has been inferred from the doctype. All values from here upward are confident enough to be used for XMLHttpRequest.
kCharsetFromCache 4 The character set has been retrieved from the cache.
kCharsetFromParentFrame 5 The parent frame's character set is being used.
kCharsetFromAutoDetection 6 The character set was automatically detected.
kCharsetFromHintPrevDoc 7 The character set was hinted by the previous document.
kCharsetFromMetaPrescan 8 Values from this one downward are HTML5 tentative.
kCharsetFromMetaTag 9 Values from this one upward are HTML5 confident.
kCharsetFromIrreversibleAutoDetection 10  
kCharsetFromByteOrderMark 11 The character set was determined from a byte order mark in the content.
kCharsetFromChannel 12 The nsIChannel specified the character set.
kCharsetFromOtherComponent 13  
kCharsetFromParentForced 14 The parent's character set was forced onto this content; all descendents will have this character set forced onto it.
kCharsetFromUserForced 15 The user specified a character set to force onto this content; all descendents will have this character set forced onto it.
kCharsetFromPreviousLoading    

Methods

Requires Gecko 1.9 (Firefox 3)

addSessionStorage()

Add a WebApps session storage object to the docshell.

void addSessionStorage(
  in nsIPrincipal principal,
  in nsIDOMStorage storage
);
Parameters
principal
The principal to use for the new storage object.
storage
The storage object to add.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

addState()

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
);
Parameters
aData
The state object to pass to the popstate event. It must be possible to serialise this in less than 640k characters.
aTitle
Gecko currently ignores this parameter.
aURL
The URL associated with the new history entry. For instance, if the user tries to reload the page, then this is the URL that will be reloaded.
aReplace
Whether to modify the current history entry instead of creating a new one.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

beginRestore()

Begin firing WebProgressListener notifications for restoring a page presentation. 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
);
Parameters
viewer
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.

Requires Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2)

createAboutBlankContentViewer()

Create a new about:blank document and content viewer.

void createAboutBlankContentViewer(
  in nsIPrincipal aPrincipal
);
Parameters
aPrincipal
The principal to use for the new document.

createLoadInfo()

Creates a DocShellLoadInfo object that you can manipulate and then pass to loadURI().

void createLoadInfo(
  out nsIDocShellLoadInfo loadInfo
);
Parameters
loadInfo
The new nsIDocShellLoadInfo object.

Violates the XPCOM interface guidelines

DetachEditorFromWindow()

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.

void DetachEditorFromWindow();
Parameters

None.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

finishRestore()

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

void finishRestore();
Parameters

None.

Native code only!

firePageHideNotification

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.

void firePageHideNotification(
  in boolean isUnload
);
Parameters
isUnload
If true, fire the unload event in addition to the pagehide event.

Native code only!

fireUnloadNotification

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Notify the associated content viewer and all child docshells that they are about to be unloaded.

void fireUnloadNotification();
Parameters

None.

getDocShellEnumerator()

Get an enumerator over this docShell and its children.

nsISimpleEnumerator getDocShellEnumerator(
  in long aItemType,
  in long aDirection
);
Parameters
aItemType
Only include docShells of this type, or if typeAll, include all child shells. Uses types from nsIDocShellTreeItem.
aDirection
Whether to enumerate forwards or backwards.
Return value

An enumerator over this docShell and its children.

Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

getSessionStorageForPrincipal()

Retrieves the session storage object for the supplied principal.

nsIDOMStorage getSessionStorageForPrincipal(
  in nsIPrincipal principal,
  in DOMString documentURI,
  in boolean create
);
Parameters
principal
The principal of the storage object to retrieve.
documentURI
If a new storage object needs to be created, it will be created with a reference to this document.documentURI in its StorageEvent.
create
If this is true, a new session storage object will be created.
Return value

The new or existing session storage object, if any.

Requires Gecko 1.9 (Firefox 3)

getSessionStorageForURI()

Retrieves the session storage object for the supplied domain. If session storage object does not already exist, a new one will be created.

nsIDOMStorage getSessionStorageForURI(
  in nsIURI uri,
  in DOMString documentURI
);
Parameters
uri
The domain of the storage object to retrieve.
documentURI
If a new storage object needs to be created, it will be created with a reference to this document.documentURI in its StorageEvent.
Return value

The session storage object for the supplied domain.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

historyPurged()

Notification that entries have been removed from the beginning of a nsSHistory which has this as its rootDocShell.

void historyPurged(
  in long numEntries
);
Parameters
numEntries
The number of entries removed.

Native code only!

internalLoad

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.

void internalLoad(
  in nsIURI aURI,
  in nsIURI aReferrer,
  in nsISupports aOwner,
  in PRUint32 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
);
Parameters
aURI
The URI to load.
aReferrer
Referring URI.
aOwner
Owner (security principal)
aFlags
A combination of the internal load flags as detailed in the constants secion.
aWindowTarget
Window target for the load.
aTypeHint
A hint as to the content-type of the resulting data. May be null or empty if no hint.
aPostDataStream
Post data stream (if POSTing)
aHeadersStream
Stream containing "extra" request headers.
aLoadFlags
Flags to modify load behaviour. Flags are defined in nsIWebNavigation.
aSHEntry
Active Session History entry (if loading from SH)
firstParty
true if this is the master top-level document.
aDocShell
If the load was succesfully initiated, this receives the nsIDocShell that actually performed the load.
aRequest
The new channel created for the load.

isBeingDestroyed()

boolean isBeingDestroyed();
Parameters

None.

Return value

Returns true if the docshell is being destroyed, false otherwise.

Native code only!

loadStream

Loads a given stream. This will give priority to loading the requested stream in the object implementing this interface. If it can not be loaded here however, the URL dispatched will go through its normal process of content loading.

void loadStream(
  in nsIInputStream aStream,
  in nsIURI aURI,
  in ACString aContentType,
  in ACString aContentCharset,
  in nsIDocShellLoadInfo aLoadInfo
);
Parameters
aStream
The input stream that provides access to the data to be loaded. This must be a blocking, threadsafe stream implementation.
aURI
The URI representing the stream, or null.
aContentType
The type (MIME) of data being loaded (empty if unknown).
aContentCharset
The charset of the data being loaded (empty if unknown).
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.

Native code only!

loadURI

Loads a given URI. This will give priority to loading the requested URI in the object implementing this interface. If it can not be loaded here however, the URL dispatcher will go through its normal process of content loading.

void loadURI(
  in nsIURI uri,
  in nsIDocShellLoadInfo loadInfo,
  in unsigned long aLoadFlags,
  in boolean firstParty
);
Parameters
uri
The URI to load.
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.
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.
firstParty
true if this is the master top-level document.

prepareForNewContentModel()

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();
Parameters

None.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

resumeRefreshURIs()

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();
Parameters

None.

Native code only!

setChildOffset

Set the offset of this child in its container.

void setChildOffset(
  in unsigned long offset
);
Parameters
offset
The offset of this nsIDocShell within its parent. Used to restore session history for frames.

setCurrentURI()

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
);
Parameters
aURI
The URI to load.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

suspendRefreshURIs()

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();
Parameters

None.

tabToTreeOwner()

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
);
Parameters
forward
Whether to tab forwards or backwards.
tookFocus
Whether or not an element was successfully focused.

Document Tags and Contributors

Last updated by: Sheppy,