diff options
Diffstat (limited to 'docshell/shistory/nsISHistory.idl')
| -rw-r--r-- | docshell/shistory/nsISHistory.idl | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/docshell/shistory/nsISHistory.idl b/docshell/shistory/nsISHistory.idl new file mode 100644 index 000000000..71da2e1ab --- /dev/null +++ b/docshell/shistory/nsISHistory.idl @@ -0,0 +1,221 @@ +/* -*- 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); +}; |