/* -*- 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;
interface nsIPartialSHistoryListener;
/**
* 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
{
/**
* An attribute denoting whether the nsISHistory is associated to a grouped
* session history.
*
* The abstraction of grouped session history is implemented at
* nsIWebNavigation level, so those canGoBack / canGoForward / gotoIndex
* functions work transparently;
*
* On the other hand, nsISHistory works on partial session history directly.
* Unless otherwise specified, count / index attributes and parameters all
* indicate local count / index, so we won't mess up docshell.
*/
readonly attribute bool isPartial;
/**
* A readonly property of the interface that returns
* the number of toplevel documents currently available
* in session history.
*/
readonly attribute long count;
/**
* If isPartial, globalCount denotes the total number of entries in the
* grouped session history; Otherwise it has the same value as count.
*/
readonly attribute long globalCount;
/**
* A readonly property which represents the difference between global indices
* of grouped session history and local indices of this particular session
* history object.
*/
readonly attribute long globalIndexOffset;
/**
* 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 NS_OK history entry for
* the index is obtained successfully.
* NS_ERROR_FAILURE Error in obtaining
* history entry for the given index.
*/
nsISHEntry getEntryAtIndex(in long index, in boolean modifyIndex);
/**
* 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 NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA Purge was vetod.
* @throws NS_ERROR_FAILURE 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);
/**
* Set the listener to handle cross nsISHistory navigation when it works
* in "partial" mode.
*/
void setPartialSHistoryListener(in nsIPartialSHistoryListener 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 NS_OK index for the history entry
* is obtained successfully.
* NS_ERROR_FAILURE Error in obtaining
* index for the given history entry.
*/
long getIndexOfEntry(in nsISHEntry aEntry);
/**
* Called when this nsISHistory has became the active history of a grouped
* session history.
*
* @param globalLength The up to date number of entries in the grouped
* session history.
* @param targetIndex The local index to navigate to.
*/
void onPartialSessionHistoryActive(in long globalLength, in long targetIndex);
/**
* Called when this nsISHistory has became inactive history of a grouped
* session history.
*/
void onPartialSessionHistoryDeactive();
/**
* Called when it's attached to a nsIGroupedSHistory instance.
*
* @param offset The number of entries in the grouped session
* history before this session history object.
*/
void onAttachGroupedSessionHistory(in long offset);
};