Mozilla

• About
• Developers
• Store
• Support
• Products

nsISHistory

---

This interface provides access to the primary properties of the Session History component. In an embedded browser environment, the nsIWebBrowser object creates an instance of session history for each open window. A handle to the session history object can be obtained from nsIWebNavigation. In a non-embedded situation, the owner of the session history component must create a instance of it and set it in the nsIWebNavigation object. This interface is scriptable.

Methods

getEntryAtIndex

Obtains a handle to the history entry at a given index.

Syntax:

nsIHistoryEntry nsISHistory::getEntryAtIndex(
	in long index,in boolean modifyIndex) 

Parameters:

index: The index value whose entry is requested.

modifyIndex: A boolean flag that indicates if the current index of session history should be modified to the parameter index.

nsresult:

NS_OK if history entry for the given index is successfully obtained.

NS_ERROR_FAILURE if not successfully obtained.

PurgeHistory

Purges older documents from history. Documents can be removed from session history for various reasons. For example to control memory usage of the browser, to prevent users from loading documents from history, to erase evidence of prior page loads etc.

Syntax:

void nsISHistory::PurgeHistory(in long numEntries) 

Paramters:

numEntries: The number of toplevel documents to be purged from history. During purge operation, the latest documents are maintained and older numEntries documents are removed from history.

nsresult:

NS_OK: if purging was successful.

NS_ERROR_FAILURE: if numEntries is invalid or out of bounds with the size of history.

addSHistoryListener

Registers a listener for the session history component. Listeners are notified when pages are loaded or purged from history.

Syntax:

void nsISHistory::addSHistoryListener(
	in nsISHistoryListener aListener) 

Parameters:

aListener: Listener object to be notified for all page loads that initiate in session history.

Note: A listener object must implement nsISHistoryListener and nsISupportsWeakReference.

See also nsISHistoryListener and nsISupportsWeakReference.

nsresult:

NS_OK if listener added.

removeSHistoryListener

Removes a listener for the session history component. Listeners are notified when pages are loaded or purged from history.

Syntax:

void nsISHistory::removeSHistoryListener(
	in nsISHistoryListener aListener) 

Parameters:

aListener: Listener object to be removed.

Note:A listener object must implement nsISHistoryListener and nsISupportsWeakReference.

See also nsISHistoryListener and nsISupportsWeakReference.

nsresult:

NS_OK if listener removed.

Attributes

readonly attribute nsISimpleEnumerator nsISHistory::SHistoryEnumerator

Gets an enumerator for all the documents stored in session history. The enumerator object thus returned by this method can be traversed using nsISimpleEnumerator.

Note: To access individual history entries of the enumerator, perform the following steps:

1) Call nsISHistory->GetSHistoryEnumerator to obtain handle on the nsISimpleEnumerator object.

2) Use nsISimpleEnumerator->GetNext on the object returned by step #1 to obtain handle to the next object in the list. The object returned by this step is of type nsISupports.

3) QI on the object returned by step #2 to nsIHistoryEntry.

4) Use nsIHistoryEntry to access properties of each history entry.

See also: nsISimpleEnumerator,nsIHistoryEntry,QueryInterface, and do_QueryInterface.

readonly attribute long nsISHistory::count

Gets the number of toplevel documents currently available in session history.

readonly attribute long nsISHistory::index

Gets the index of the current document in session history.

attribute long nsISHistory::maxLength

Gets and sets the maximum number of toplevel documents session history can hold for each instance.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History