nsIDocShell 编辑

docshell/base/nsIDocShell.idlScriptable ??? 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.
allowMedia	boolean	Attribute stating whether or not media (audio/video) should be loaded.
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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.