nsISHistory

IID:7294FE9B-14D8-11D5-9882-00C04FA02F40
Inherits From:nsISupports
Status:FROZEN

An interface 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 accessible from javascript.

This interface is implemented by the following components:


Properties

readonly PRInt32 count

A readonly property of the interface that returns the number of toplevel documents currently available in session history.

readonly PRInt32 index

A readonly property of the interface that returns the index of the current document in session history.

PRInt32 maxLength

A read/write property of the interface, used to Get/Set the maximum number of toplevel documents, session history can hold for each instance.

readonly nsISimpleEnumerator SHistoryEnumerator

Called to obtain a enumerator for all the documents stored in session history. The enumerator object thus returned by this method can be traversed using nsISimpleEnumerator.


Methods

void addSHistoryListener ( nsISHistoryListener listener ) nsIHistoryEntry getEntryAtIndex ( PRInt32 index , PRBool modifyIndex ) void PurgeHistory ( PRInt32 numEntries ) void removeSHistoryListener ( nsISHistoryListener listener )

void addSHistoryListener ( nsISHistoryListener listener )

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

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

nsIHistoryEntry getEntryAtIndex ( PRInt32 index , PRBool modifyIndex )

Called to obtain handle to the history entry at a given index.

Arguments:
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.
Returns:
NS_OK history entry for the index is obtained successfully. NS_ERROR_FAILURE Error in obtaining history entry for the given index.

void PurgeHistory ( PRInt32 numEntries )

Called to purge 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...

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

void removeSHistoryListener ( nsISHistoryListener listener )

Called to remove a listener for the session history component. Listeners are notified when pages are loaded from history.

Arguments:
listener: Listener object to be removed from session history.

References

This interface is the type of the following properties:

nsIWebNavigation.sessionHistory

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
June 18, 2005, 2:17 am example at example dot com
To be able to use addHistoryListener:
A listener object must implement nsISHistoryListener and nsISupportsWeakReference.

(from http://www.mozilla.org/projects/embedding/embedapiref/embedapi70.html )

Copyright © 1999 - 2005 XULPlanet.com