nsIDocShell

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

Attributes

Constants

Character set source constants

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

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.

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.

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.

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.

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.

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.

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.

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.