Public Member Functions | Public Attributes

nsIDocShell Interface Reference

import "nsIDocShell.idl";

Collaboration diagram for nsIDocShell:

List of all members.

Public Member Functions

void loadURI (in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags, in boolean firstParty)
 Loads a given URI.
void loadStream (in nsIInputStream aStream, in nsIURI aURI, in ACString aContentType, in ACString aContentCharset, in nsIDocShellLoadInfo aLoadInfo)
 Loads a given stream.
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)
 Loads the given URI.
void createLoadInfo (out nsIDocShellLoadInfo loadInfo)
 Creates a DocShellLoadInfo object that you can manipulate and then pass to loadURI.
void prepareForNewContentModel ()
 Reset state to a new content model within the current document and the document viewer.
void setCurrentURI (in nsIURI aURI)
 For editors and suchlike who wish to change the URI associated with the document.
void firePageHideNotification (in boolean isUnload)
 Notify the associated content viewer and all child docshells that they are about to be hidden.
nsISimpleEnumerator getDocShellEnumerator (in long aItemType, in long aDirection)
void tabToTreeOwner (in boolean forward, out boolean tookFocus)
boolean isBeingDestroyed ()
void suspendRefreshURIs ()
 Cancel the XPCOM timers for each meta-refresh URI in this docshell, and this docshell's children, recursively.
void resumeRefreshURIs ()
 Restart the XPCOM timers for each meta-refresh URI in this docshell, and this docshell's children, recursively.
void beginRestore (in nsIContentViewer viewer, in boolean top)
 Begin firing WebProgressListener notifications for restoring a page presentation.
void finishRestore ()
 Finish firing WebProgressListener notifications and DOM events for restoring a page presentation.
void historyPurged (in long numEntries)
 Notification that entries have been removed from the beginning of a nsSHistory which has this as its rootDocShell.
nsIDOMStorage getSessionStorageForURI (in nsIURI uri)
nsIDOMStorage getSessionStorageForPrincipal (in nsIPrincipal principal, in boolean create)
void addSessionStorage (in nsIPrincipal principal, in nsIDOMStorage storage)
void setChildOffset (in unsigned long offset)
 Set the offset of this child in its container.
void DetachEditorFromWindow ()
 Disconnects this docshell's editor from its window, and stores the editor data in the open document's session history entry.

Public Attributes

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
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
readonly attribute nsPresContext presContext
 Presentation context for the currently loaded document.
readonly attribute nsIPresShell presShell
 Presentation shell for the currently loaded document.
readonly attribute nsIPresShell eldestPresShell
 Presentation shell for the oldest document, if this docshell is currently transitioning between documents.
readonly attribute nsIContentViewer contentViewer
 Content Viewer that is currently loaded for this DocShell.
attribute nsIDOMEventTarget chromeEventHandler
 This attribute allows chrome to tie in to handle DOM events that may be of interest to chrome.
attribute nsIDocumentCharsetInfo documentCharsetInfo
 The document charset info.
attribute boolean allowPlugins
 Whether to allow plugin execution.
attribute boolean allowJavascript
 Whether to allow Javascript execution.
attribute boolean allowMetaRedirects
 Attribute stating if refresh based redirects can be allowed.
attribute boolean allowSubframes
 Attribute stating if it should allow subframes (framesets/iframes) or not.
attribute boolean allowImages
 Attribute stating whether or not images should be loaded.
attribute boolean allowDNSPrefetch
 Attribute that determines whether DNS prefetch is allowed for this subtree of the docshell tree.
const long ENUMERATE_FORWARDS = 0
 Get an enumerator over this docShell and its children.
const long ENUMERATE_BACKWARDS = 1
const unsigned long APP_TYPE_UNKNOWN = 0
 The type of application that created this window.
const unsigned long APP_TYPE_MAIL = 1
const unsigned long APP_TYPE_EDITOR = 2
attribute unsigned long appType
attribute boolean allowAuth
 certain dochshells (like the message pane) should not throw up auth dialogs because it can act as a password trojan
attribute float zoom
 Set/Get the document scale factor.
attribute long marginWidth
attribute long marginHeight
const unsigned long BUSY_FLAGS_NONE = 0
 Current busy state for DocShell.
const unsigned long BUSY_FLAGS_BUSY = 1
const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD = 2
const unsigned long BUSY_FLAGS_PAGE_LOADING = 4
const unsigned long LOAD_CMD_NORMAL = 0x1
 Load commands for the document.
const unsigned long LOAD_CMD_RELOAD = 0x2
const unsigned long LOAD_CMD_HISTORY = 0x4
readonly attribute unsigned long busyFlags
attribute unsigned long loadType
readonly attribute boolean isExecutingOnLoadHandler
attribute nsILayoutHistoryState layoutHistoryState
readonly attribute boolean shouldSaveLayoutState
attribute nsISecureBrowserUI securityUI
 The SecureBrowserUI object for this docshell.
readonly attribute boolean restoringDocument
attribute boolean useErrorPages
readonly attribute long previousTransIndex
 Keeps track of the previous SHTransaction index and the current SHTransaction index at the time that the doc shell begins to load.
readonly attribute long loadedTransIndex
readonly attribute nsIChannel currentDocumentChannel
 Gets the channel for the currently loaded document, if any.
readonly attribute boolean isInUnload
 Find out whether the docshell is currently in the middle of a page transition.
readonly attribute boolean channelIsUnsafe
 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).
attribute boolean isOffScreenBrowser
 If true, this browser is not visible in the traditional sense, but is actively being rendered to the screen (ex.
readonly attribute
nsIWebBrowserPrint 
printPreview
 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.

Member Function Documentation

void nsIDocShell::addSessionStorage ( in nsIPrincipal  principal,
in nsIDOMStorage  storage 
)
void nsIDocShell::beginRestore ( in nsIContentViewer  viewer,
in boolean  top 
)

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 nsIDocShell::createLoadInfo ( out nsIDocShellLoadInfo  loadInfo  ) 

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

void nsIDocShell::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 nsIDocShell::finishRestore (  ) 

Finish firing WebProgressListener notifications and DOM events for restoring a page presentation.

This should only be called via beginRestore().

void nsIDocShell::firePageHideNotification ( in boolean  isUnload  ) 

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.

Parameters:
isUnload if true, fire the unload event in addition to the pagehide event.
nsISimpleEnumerator nsIDocShell::getDocShellEnumerator ( in long  aItemType,
in long  aDirection 
)
nsIDOMStorage nsIDocShell::getSessionStorageForPrincipal ( in nsIPrincipal  principal,
in boolean  create 
)
nsIDOMStorage nsIDocShell::getSessionStorageForURI ( in nsIURI  uri  ) 
void nsIDocShell::historyPurged ( in long  numEntries  ) 

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

Parameters:
numEntries - The number of entries removed
void nsIDocShell::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 
)

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

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)
boolean nsIDocShell::isBeingDestroyed (  ) 
void nsIDocShell::loadStream ( in nsIInputStream  aStream,
in nsIURI  aURI,
in ACString  aContentType,
in ACString  aContentCharset,
in nsIDocShellLoadInfo  aLoadInfo 
)

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.

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.
void nsIDocShell::loadURI ( in nsIURI  uri,
in nsIDocShellLoadInfo  loadInfo,
in unsigned long  aLoadFlags,
in boolean  firstParty 
)

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.

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.
void nsIDocShell::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 nsIDocShell::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 nsIDocShell::setChildOffset ( in unsigned long  offset  ) 

Set the offset of this child in its container.

void nsIDocShell::setCurrentURI ( in nsIURI  aURI  ) 

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 nsIDocShell::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 nsIDocShell::tabToTreeOwner ( in boolean  forward,
out boolean  tookFocus 
)

Member Data Documentation

certain dochshells (like the message pane) should not throw up auth dialogs because it can act as a password trojan

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 stating whether or not images should be loaded.

Whether to allow Javascript execution.

Attribute stating if refresh based redirects can be allowed.

Whether to allow plugin execution.

Attribute stating if it should allow subframes (framesets/iframes) or not.

const unsigned long nsIDocShell::APP_TYPE_EDITOR = 2
const unsigned long nsIDocShell::APP_TYPE_MAIL = 1
const unsigned long nsIDocShell::APP_TYPE_UNKNOWN = 0

The type of application that created this window.

attribute unsigned long nsIDocShell::appType
const unsigned long nsIDocShell::BUSY_FLAGS_BUSY = 1
const unsigned long nsIDocShell::BUSY_FLAGS_NONE = 0

Current busy state for DocShell.

const unsigned long nsIDocShell::BUSY_FLAGS_PAGE_LOADING = 4
readonly attribute unsigned long nsIDocShell::busyFlags

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).

This attribute allows chrome to tie in to handle DOM events that may be of interest to chrome.

Content Viewer that is currently loaded for this DocShell.

This may change as the underlying content changes.

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.

The document charset info.

This is used by a load to determine priorities for charset detection etc.

readonly attribute nsIPresShell nsIDocShell::eldestPresShell

Presentation shell for the oldest document, if this docshell is currently transitioning between documents.

Get an enumerator over this docShell and its children.

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.
readonly attribute boolean nsIDocShell::isInUnload

Find out whether the docshell is currently in the middle of a page transition.

This is set just before the pagehide/unload events fire.

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 nsILayoutHistoryState nsIDocShell::layoutHistoryState
const unsigned long nsIDocShell::LOAD_CMD_HISTORY = 0x4
const unsigned long nsIDocShell::LOAD_CMD_NORMAL = 0x1

Load commands for the document.

const unsigned long nsIDocShell::LOAD_CMD_RELOAD = 0x2
readonly attribute long nsIDocShell::loadedTransIndex
attribute unsigned long nsIDocShell::loadType
attribute long nsIDocShell::marginHeight
attribute long nsIDocShell::marginWidth

Presentation context for the currently loaded document.

This may be null.

readonly attribute nsIPresShell nsIDocShell::presShell

Presentation shell for the currently loaded document.

This may be null.

readonly attribute long nsIDocShell::previousTransIndex

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.

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.

The SecureBrowserUI object for this docshell.

This is set by XUL <browser> or nsWebBrowser for their root docshell.

attribute float nsIDocShell::zoom

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.


The documentation for this interface was generated from the following file: