docshell/shistory/public/nsISHistory.idlScriptable
An interface to the primary properties of the Session History component.
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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.

Implemented by: @mozilla.org/browser/shistory;1. To create an instance, use:

var sHistory = Components.classes["@mozilla.org/browser/shistory;1"]
               .createInstance(Components.interfaces.nsISHistory);

Method overview

void addSHistoryListener(in nsISHistoryListener aListener);
nsISHEntry getEntryAtIndex(in long index, in boolean modifyIndex);
void PurgeHistory(in long numEntries);
void reloadCurrentEntry();
void removeSHistoryListener(in nsISHistoryListener aListener);

Attributes

Attribute Type Description
count long The number of toplevel documents currently available in session history. Read only.
index long The index of the current document in session history. Read only.
maxLength long Used to Get/Set the maximum number of toplevel documents, session history can hold for each instance.
requestedIndex long The index of the last document that started to load that is not yet finished loading. When the document finishes loading the value -1 is returned. Read only.
SHistoryEnumerator nsISimpleEnumerator

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.

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

  1. Call GetSHistoryEnumerator() to obtain handle 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. Perform a QueryInterface on the object returned by step #2 to nsISHEntry.
  4. Use nsISHEntry to access properties of each history entry.
Read only.

Methods

addSHistoryListener()

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

Note: A listener object must implement nsISHistoryListener and nsSupportsWeakReference.

void addSHistoryListener(
  in nsISHistoryListener aListener
);
Parameters
aListener
Listener object to be notified for all page loads that initiate in session history.

getEntryAtIndex()

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

nsISHEntry 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.
Exceptions thrown

NS_OK history entry for the index is obtained successfully. NS_ERROR_FAILURE Error in obtaining history entry for the given index.

PurgeHistory()

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 and so on.

void PurgeHistory(
  in long numEntries
);
Parameters
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.
Exceptions thrown
NS_ERROR_FAILURE
numEntries is invalid or out of bounds with the size of history.
NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA
Purge was vetoed.

reloadCurrentEntry()

void reloadCurrentEntry();
Parameters

None.

removeSHistoryListener()

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

Note: A listener object must implement nsISHistoryListener and nsSupportsWeakReference.

void removeSHistoryListener(
  in nsISHistoryListener aListener
);
Parameters
aListener
Listener object to be removed from session history.