docshell/shistory/public/nsISHEntry.idlScriptable
Each document or subframe in Session History will have a nsISHEntry associated with it which will hold all information required to recreate the document from history.
Inherits from: nsIHistoryEntry Last changed in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

Implemented by: @mozilla.org/browser/session-history-entry;1. To create an instance, use:

var shentry = Components.classes["@mozilla.org/browser/session-history-entry;1"]
                        .createInstance(Components.interfaces.nsISHEntry);

Method overview

void addChildShell(in nsIDocShellTreeItem shell);
nsIDocShellTreeItem childShellAt(in long index);
void clearChildShells();
nsISHEntry clone();
void create(in nsIURI URI, in AString title, in nsIInputStream inputStream, in nsILayoutHistoryState layoutHistoryState, in nsISupports cacheKey, in ACString contentType, in nsISupports owner, in unsigned long long docshellID, in boolean dynamicCreation); Native code only!
nsDocShellEditorDataPtr forgetEditorData(); Violates the XPCOM interface guidelines
nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);
void getScrollPosition(out long x, out long y);
void getViewerBounds(in nsIntRect bounds); Native code only!
boolean hasDetachedEditor(); Violates the XPCOM interface guidelines
boolean hasDynamicallyAddedChild();
boolean isDynamicallyAdded();
void setEditorData(in nsDocShellEditorDataPtr aData); Violates the XPCOM interface guidelines
void setIsSubFrame(in boolean aFlag);
void setScrollPosition(in long x, in long y);
void setTitle(in AString aTitle);
void setUniqueDocIdentifier();
void setURI(in nsIURI aURI);
void setViewerBounds(in nsIntRect bounds); Native code only!
void syncPresentationState();

Attributes

Attribute Type Description
cacheKey nsISupports Set and get the cache key for the entry.
contentType ACString Indicates the content-type of the document that this is a session history entry for.
contentViewer nsIContentViewer Content viewer, for fast restoration of presentation.
docIdentifier unsigned long long An integer that should be the same for two entries attached to the same docshell if and only if the two entries are entries for the same document. In practice, two entries A and B will have the same docIdentifier if we arrived at B by clicking an anchor link in A or if B was created by A's calling history.pushState().
docshellID unsigned long long The history ID of the docshell.
document nsIDOMDocument DOM Document. Obsolete since Gecko 1.8
expirationStatus boolean Indicates whether the page is already expired in cache.
ID unsigned long An ID to help identify this entry from others during subframe navigation.
layoutHistoryState nsILayoutHistoryState LayoutHistoryState for scroll position and form values.
loadType unsigned long The loadType for this entry. This is typically loadHistory except when reload is pressed, it has the appropriate reload flag.
owner nsISupports Get the owner, if any, that was associated with the channel that the document that was loaded to create this history entry came from.
pageIdentifier unsigned long An integer that should be the same for two entries attached to the same docshell only if the two entries are entries for the same page in the sense that one could go from the state represented by one to the state represented by the other simply by scrolling (so the entries are separated by an anchor traversal or a subframe navigation in some other frame). Obsolete since Gecko 6.0
parent nsISHEntry Parent of this entry.
postData nsIInputStream Post Data for the document.
referrerURI nsIURI Referrer URI.
refreshURIList nsISupportsArray Saved refresh URI list for the content viewer.
saveLayoutStateFlag boolean Indicate whether layoutHistoryState should be saved.
stateData nsIStructuredCloneContainer Get/set data associated with this history state via a pushState() call, serialized using structured clone. (Prior to Gecko 6.0 returned a JSON encoded string.)
sticky boolean Whether the content viewer is marked "sticky"
windowState nsISupports Saved state of the global window object.

Methods

addChildShell()

Saved child docshells corresponding to contentViewer. The child shells are restored as children of the parent docshell, in this order, when the parent docshell restores a saved presentation.

Append a child shell to the end of our list.

void addChildShell(
  in nsIDocShellTreeItem shell
);
Parameters
shell

childShellAt()

nsIDocShellTreeItem childShellAt(
  in long index
);
Parameters
index
The child shell at index; null if index is out of bounds.
Return value

 

clearChildShells()

Clear the child shell list.

void clearChildShells();
Parameters

None.

clone()

nsISHEntry clone();
Parameters

None.

Return value

 

Native code only!

create

Additional ways to create an entry.

void create(
  in nsIURI URI,
  in AString title,
  in nsIInputStream inputStream,
  in nsILayoutHistoryState layoutHistoryState,
  in nsISupports cacheKey,
  in ACString contentType,
  in nsISupports owner,
  in unsigned long long docshellID,
  in boolean dynamicCreation
);
Parameters
URI
title
inputStream
layoutHistoryState
cacheKey
contentType
owner
docshellID
dynamicCreation

Violates the XPCOM interface guidelines

forgetEditorData()

Gets the owning pointer to the editor data assosicated with this shistory entry. This forgets its pointer, so free it when you're done.

nsDocShellEditorDataPtr forgetEditorData();
Parameters

None.

Return value

 

getAnyContentViewer()

Return any content viewer present in or below this node in the nsSHEntry tree. This will differ from contentViewer in the case where a child nsSHEntry has the content viewer for this tree.

nsIContentViewer getAnyContentViewer(
  out nsISHEntry ownerEntry
);
Parameters
ownerEntry
Return value

 

getScrollPosition()

void getScrollPosition(
  out long x,
  out long y
);
Parameters
x
y

Native code only!

getViewerBounds

Saved position and dimensions of the content viewer; we must adjust the root view's widget accordingly if this has changed when the presentation is restored.

void getViewerBounds(
  in nsIntRect bounds
);
Parameters
bounds

Violates the XPCOM interface guidelines

hasDetachedEditor()

boolean hasDetachedEditor();
Parameters

None.

Return value

true if this shistory entry is storing a detached editor.

hasDynamicallyAddedChild()

boolean hasDynamicallyAddedChild();
Parameters

None.

Return value

true if any of the child entries returns true when isDynamicallyAdded() is called on it.

isDynamicallyAdded()

Returns true if the related docshell was added because of dynamic addition of an iframe/frame.

boolean isDynamicallyAdded();
Parameters

None.

Return value

 

Violates the XPCOM interface guidelines

setEditorData()

Sets the owning pointer to the editor data assosicated with this shistory entry. Unless forgetEditorData() is called, this shentry will destroy the editor data when it is destroyed.

void setEditorData(
  in nsDocShellEditorDataPtr aData
);
Parameters
aData

setIsSubFrame()

Attribute that indicates if this entry is for a subframe navigation.

void setIsSubFrame(
  in boolean aFlag
);
Parameters
aFlag

setScrollPosition()

Set/Get scrollers' positon in anchored pages.

void setScrollPosition(
  in long x,
  in long y
);
Parameters
x
y

setTitle()

Title for the document.

void setTitle(
  in AString aTitle
);
Parameters
aTitle

setUniqueDocIdentifier()

Changes this entry's doc identifier to a new value which is unique among those of all other entries.

void setUniqueDocIdentifier();
Parameters

None.

setURI()

URI for the document.

void setURI(
  in nsIURI aURI
);
Parameters
aURI

Native code only!

setViewerBounds

void setViewerBounds(
  in nsIntRect bounds
);
Parameters
bounds

syncPresentationState()

Ensure that the cached presentation members are self-consistent. If either contentViewer or windowState are null, then all of the following members are cleared/reset: contentViewer, sticky, windowState, viewerBounds, childShells, refreshURIList.

void syncPresentationState();
Parameters

None.

Example

see nsSessionStore.js for a real example.