diff -r 000000000000 -r 6474c204b198 docshell/shistory/public/nsISHistory.idl
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docshell/shistory/public/nsISHistory.idl Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,162 @@
+/* -*- 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;
+/**
+ * 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
+{
+ /**
+ * A readonly property of the interface that returns
+ * the number of toplevel documents currently available
+ * in session history.
+ */
+ readonly attribute long count;
+
+ /**
+ * 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);
+
+ /**
+ * 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);
+};