/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsISHEntry;
interface nsISHistoryListener;
interface nsISimpleEnumerator;
/**
* 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.
*/
%{C++
#define NS_SHISTORY_CID \
{0x7b807041, 0xe60a, 0x4384, {0x93, 0x5f, 0xaf, 0x30, 0x61, 0xd8, 0xb8, 0x15}}
#define NS_SHISTORY_CONTRACTID "@mozilla.org/browser/shistory;1"
%}
[scriptable, uuid(7b807041-e60a-4384-935f-af3061d8b815)]
interface nsISHistory: nsISupports
{
/**
* The size of the window of SHEntries which can have alive viewers in the
* bfcache around the currently active SHEntry.
*
* We try to keep viewers for SHEntries between index - VIEWER_WINDOW and
* index + VIEWER_WINDOW alive.
*/
const long VIEWER_WINDOW = 3;
/**
* A readonly property of the interface that returns
* the number of toplevel documents currently available
* in session history.
*/
readonly attribute long count;
/**
* A readonly property of the interface that returns
* the index of the current document in session history.
*/
readonly attribute long index;
/**
* A readonly property of the interface that returns
* the index of the last document that started to load and
* didn't finished yet. When document finishes the loading
* value -1 is returned.
*/
readonly attribute long requestedIndex;
/**
* A read/write property of the interface, used to Get/Set
* the maximum number of toplevel documents, session history
* can hold for each instance.
*/
attribute long maxLength;
/**
* Called to obtain handle to the history entry at a
* given index.
*
* @param index The index value whose entry is requested.
* The oldest entry is located at index == 0.
* @param modifyIndex A boolean flag that indicates if the current
* index of session history should be modified
* to the parameter index.
*
* @return <code>NS_OK</code> history entry for
* the index is obtained successfully.
* <code>NS_ERROR_FAILURE</code> Error in obtaining
* history entry for the given index.
*/
nsISHEntry getEntryAtIndex(in long index, in boolean modifyIndex);
/**
* Load the entry at given index to root docshell directly in order to
* restore to an entry in grouped session history navigation or session
* restore case. This function will not notify nsISHistoryListener, as it's
* not considered a normal history navigation.
*/
void restoreToEntryAtIndex(in long index);
/**
* 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...
*
* @param 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.
* @throws <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code> Purge was vetod.
* @throws <code>NS_ERROR_FAILURE</code> numEntries is
* invalid or out of bounds with the size of history.
*
*/
void PurgeHistory(in long numEntries);
/**
* Called to register a listener for the session history component.
* Listeners are notified when pages are loaded or purged from history.
*
* @param aListener Listener object to be notified for all
* page loads that initiate in session history.
*
* @note A listener object must implement
* nsISHistoryListener and nsSupportsWeakReference
*
* @see nsISHistoryListener
* @see nsSupportsWeakReference
*/
void addSHistoryListener(in nsISHistoryListener aListener);
/**
* Called to remove a listener for the session history component.
* Listeners are notified when pages are loaded from history.
*
* @param aListener Listener object to be removed from
* session history.
*
* @note A listener object must implement
* nsISHistoryListener and nsSupportsWeakReference
* @see nsISHistoryListener
* @see nsSupportsWeakReference
*/
void removeSHistoryListener(in nsISHistoryListener aListener);
/**
* 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.
*
* @note To access individual history entries of the enumerator, perform the
* following steps:
* 1) Call nsISHistory->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.
*
* @see nsISimpleEnumerator
* @see nsISHEntry
* @see QueryInterface()
* @see do_QueryInterface()
*/
readonly attribute nsISimpleEnumerator SHistoryEnumerator;
void reloadCurrentEntry();
/**
* Called to obtain the index to a given history entry.
*
* @param aEntry The entry to obtain the index of.
*
* @return <code>NS_OK</code> index for the history entry
* is obtained successfully.
* <code>NS_ERROR_FAILURE</code> Error in obtaining
* index for the given history entry.
*/
long getIndexOfEntry(in nsISHEntry aEntry);
};