222 lines
8.2 KiB
Plaintext
222 lines
8.2 KiB
Plaintext
/* -*- 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);
|
|
};
|