summaryrefslogtreecommitdiffstats
path: root/docshell/shistory/nsISHistory.idl
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /docshell/shistory/nsISHistory.idl
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'docshell/shistory/nsISHistory.idl')
-rw-r--r--docshell/shistory/nsISHistory.idl221
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);
+};