You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.


TOC PREV NEXT INDEX

Embedding Gecko API


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.


Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX