/* -*- 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 <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); /** * 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); /** * 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 <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); /** * 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); };