Skip to main content

Visit Mozilla.org

nsIDocShell

From MDC

The nsIDocShell interface

Contents

nsIDocShell is defined in docshell/base/nsIDocShell.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

[edit] Method overview

[noscript]void loadURI(in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags, in boolean firstParty);
[noscript]void loadStream(in nsIInputStream aStream,in nsIURI aURI,in ACString aContentType,in ACString aContentCharset,in nsIDocShellLoadInfo aLoadInfo);
[noscript]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);
void createLoadInfo(out nsIDocShellLoadInfo loadInfo);
void prepareForNewContentModel();
void setCurrentURI(in nsIURI aURI);
[noscript] void firePageHideNotification(in boolean isUnload);
nsISimpleEnumerator getDocShellEnumerator(in long aItemType,in long aDirection);
void tabToTreeOwner(in boolean forward, out boolean tookFocus);
boolean isBeingDestroyed();
void suspendRefreshURIs();
void resumeRefreshURIs();
void beginRestore(in nsIContentViewer viewer, in boolean top);
void finishRestore();
void historyPurged(in long numEntries);
nsIDOMStorage getSessionStorageForURI(in nsIURI uri);
void addSessionStorage(in ACString aDomain, in nsIDOMStorage storage);
[noscript] void setChildOffset(in unsigned long offset);
[noscript, notxpcom] void DetachEditorFromWindow();

[edit] Attributes

Attribute Type Description
presContext nsPresContext Presentation context for the currently loaded document. This may be null.
presShell nsIPresShell Presentation shell for the currently loaded document. This may be null.
eldestPresShell nsIPresShell Presentation shell for the oldest document, if this docshell is currently transitioning between documents.
contentViewer nsIContentViewer Content Viewer that is currently loaded for this DocShell. This may change as the underlying content changes.
chromeEventHandler nsIDOMEventTarget This attribute allows chrome to tie in to handle DOM events that may be of interest to chrome.
documentCharsetInfo nsIDocumentCharsetInfo The document charset info. This is used by a load to determine priorities for charset detection etc.
allowPlugins boolean Whether to allow plugin execution.
allowJavascript boolean Whether to allow Javascript execution.
allowMetaRedirects boolean Attribute stating if refresh based redirects can be allowed.
allowSubframes boolean Attribute stating if it should allow subframes (framesets/iframes) or not.
allowImages boolean Attribute stating whether or not images should be loaded.
appType unsigned long The type of application that created this window. Types are defined in nsIDocShell.
allowAuth boolean Certain dochshells (like the message pane) should not throw up auth dialogs because it can act as a password trojan.
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.
marginWidth long
marginHeight long
hasFocus boolean Tells the DocShell that it now has focus or has lost focus.
canvasHasFocus boolean Tells the docshell whether the canvas should have focus.
busyFlags unsigned long Readonly: Current busy state for DocShell. Valid states are defined in nsIDocShell.
loadType unsigned long Load type for the document. Valid states are defined in nsIDocShell.
isExecutingOnLoadHandler boolean Readonly: Returns true if the docshell is currently executing the onLoad Handler
layoutHistoryState nsILayoutHistoryState
shouldSaveLayoutState boolean Readonly:
securityUI nsISecureBrowserUI The SecureBrowserUI object for this docshell. This is set by XUL browser or nsWebBrowser for their root docshell.
restoringDocument boolean Readonly: Track whether we're currently restoring a document presentation.
useErrorPages boolean Attribute to access whether error pages are enabled.
previousTransIndex long Readonly: 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.
loadedTransIndex long Readonly: 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.
currentDocumentChannel nsIChannel Readonly: 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.
isInUnload boolean Readonly: 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)
channelIsUnsafe boolean Readonly: 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).

[edit] Constants

Constant Value Description
INTERNAL_LOAD_FLAGS_NONE 0x0
INTERNAL_LOAD_FLAGS_INHERIT_OWNER 0x1
INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER 0x2
INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP 0x4
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
ENUMERATE_FORWARDS 0 Used by the getDocShellEnumerator function to determine the direction of the enumeration.
ENUMERATE_BACKWARDS 1 Used by the getDocShellEnumerator function to determine the direction of the enumeration.
APP_TYPE_UNKNOWN 0 Returned by the appType attribute.
APP_TYPE_MAIL 1 Returned by the appType attribute.
APP_TYPE_EDITOR 2 Returned by the appType attribute.
BUSY_FLAGS_NONE 0 Returned by the busyFlags attribute.
BUSY_FLAGS_BUSY 1 Returned by the busyFlags attribute.
BUSY_FLAGS_BEFORE_PAGE_LOAD 2 Returned by the busyFlags attribute.
BUSY_FLAGS_PAGE_LOADING 4 Returned by the busyFlags attribute.
LOAD_CMD_NORMAL 0x1 Returned by the loadType attribute.
LOAD_CMD_RELOAD 0x2 Returned by the loadType attribute.
LOAD_CMD_HISTORY 0x4 Returned by the loadType attribute.

[edit] Methods

[edit] loadURI()

Not scriptable. 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. 

 void loadURI(nsIURI uri,
              nsIDocShellLoadInfo loadInfo,
              unsigned long aLoadFlags,
              boolean firstParty);


[edit] 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.

[edit] loadStream()

Not scriptable. 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. 

 void loadStream(nsIInputStream aStream,
                 nsIURI aURI,
                 ACString aContentType,
                 ACString aContentCharset,
                 nsIDocShellLoadInfo aLoadInfo);
[edit] 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 loadURI.

[edit] internalLoad()

Not scriptable. 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(nsIURI aURI,
                   nsIURI aReferrer,
                   nsISupports aOwner,
                   PRUint32 aFlags,
                   wstring aWindowTarget,
                   string aTypeHint,
                   nsIInputStream aPostDataStream,
                   nsIInputStream aHeadersStream,
                   unsigned long aLoadFlags,
                   nsISHEntry aSHEntry,
                   boolean firstParty,
                   nsIDocShell aDocShell,
                   nsIRequest aRequest);
[edit] Parameters
aURI
The URI to load.
aReferrer
Referring URI
aOwner
Owner (security principal)
aInheritOwner
Flag indicating whether the owner of the current document should be inherited if aOwner is null.
aStopActiveDoc
Flag indicating whether loading the current document should be stopped.
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)

[edit] createLoadInfo()

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

 void createLoadInfo(nsIDocShellLoadInfo loadInfo);

[edit] 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();

[edit] 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(nsIURI aURI);
[edit] Parameters
aURI
The URI to load.

[edit] firePageHideNotification()

Not scriptable. 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(boolean isUnload);
[edit] Parameters
isUnload
If true, fire the unload event in addition to the pagehide event.

[edit] getDocShellEnumerator()

Get an enumerator over this docShell and its children. 

 nsISimpleEnumerator getDocShellEnumerator(long aItemType,
                                           long aDirection);
[edit] 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.

[edit] tabToTreeOwner()

Tells the docshell to offer focus to its tree owner. This is currently only necessary for embedding chrome. 

 void tabToTreeOwner]](boolean forward,
                       boolean tookFocus);

[edit] isBeingDestroyed()

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

 boolean isBeingDestroyed();

[edit] 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();

[edit] 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();

[edit] 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(nsIContentViewer viewer,
                   boolean top);
[edit] 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.

[edit] finishRestore()

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

 void finishRestore();

[edit] historyPurged()

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

 void historyPurged(long numEntries);
[edit] Parameters
numEntries
The number of entries removed.

[edit] getSessionStorageForURI()

Retrieves the WebApps session storage object for the supplied domain. If it doesn't already exist, a new one will be created. 

 nsIDOMStorage getSessionStorageForURI(nsIURI uri);
[edit] Parameters
uri
The domain of the storage object to retrieve.

[edit] addSessionStorage()

Add a WebApps session storage object to the docshell. 

 void addSessionStorage(ACString aDomain, nsIDOMStorage storage);
[edit] Parameters
aDomain
The domain the storage object is associated with.
storage
The storage object to add.

[edit] setChildOffset()

Not scriptable. Set the offset of this child in its container. 

 void setChildOffset(unsigned long offset);

[edit] DetachEditorFromWindow()

Not scriptable. Not XPCOM. Disconnects this docshell's editor from its window, and stores the editor data in the open document's session history entry. 

 void DetachEditorFromWindow();</code>

[edit] See also

Retrieved from "http://developer.mozilla.org/en/docs/nsIDocShell"