1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docshell/shistory/public/nsISHistory.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,162 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsISHEntry;
1.12 +interface nsISHistoryListener;
1.13 +interface nsISimpleEnumerator;
1.14 +/**
1.15 + * An interface to the primary properties of the Session History
1.16 + * component. In an embedded browser environment, the nsIWebBrowser
1.17 + * object creates an instance of session history for each open window.
1.18 + * A handle to the session history object can be obtained from
1.19 + * nsIWebNavigation. In a non-embedded situation, the owner of the
1.20 + * session history component must create a instance of it and set
1.21 + * it in the nsIWebNavigation object.
1.22 + * This interface is accessible from javascript.
1.23 + */
1.24 +
1.25 +
1.26 +%{C++
1.27 +#define NS_SHISTORY_CID \
1.28 +{0x7b807041, 0xe60a, 0x4384, {0x93, 0x5f, 0xaf, 0x30, 0x61, 0xd8, 0xb8, 0x15}}
1.29 +
1.30 +#define NS_SHISTORY_CONTRACTID "@mozilla.org/browser/shistory;1"
1.31 +%}
1.32 +
1.33 +[scriptable, uuid(7b807041-e60a-4384-935f-af3061d8b815)]
1.34 +interface nsISHistory: nsISupports
1.35 +{
1.36 + /**
1.37 + * A readonly property of the interface that returns
1.38 + * the number of toplevel documents currently available
1.39 + * in session history.
1.40 + */
1.41 + readonly attribute long count;
1.42 +
1.43 + /**
1.44 + * A readonly property of the interface that returns
1.45 + * the index of the current document in session history.
1.46 + */
1.47 + readonly attribute long index;
1.48 +
1.49 + /**
1.50 + * A readonly property of the interface that returns
1.51 + * the index of the last document that started to load and
1.52 + * didn't finished yet. When document finishes the loading
1.53 + * value -1 is returned.
1.54 + */
1.55 + readonly attribute long requestedIndex;
1.56 +
1.57 + /**
1.58 + * A read/write property of the interface, used to Get/Set
1.59 + * the maximum number of toplevel documents, session history
1.60 + * can hold for each instance.
1.61 + */
1.62 + attribute long maxLength;
1.63 +
1.64 + /**
1.65 + * Called to obtain handle to the history entry at a
1.66 + * given index.
1.67 + *
1.68 + * @param index The index value whose entry is requested.
1.69 + * The oldest entry is located at index == 0.
1.70 + * @param modifyIndex A boolean flag that indicates if the current
1.71 + * index of session history should be modified
1.72 + * to the parameter index.
1.73 + *
1.74 + * @return <code>NS_OK</code> history entry for
1.75 + * the index is obtained successfully.
1.76 + * <code>NS_ERROR_FAILURE</code> Error in obtaining
1.77 + * history entry for the given index.
1.78 + */
1.79 + nsISHEntry getEntryAtIndex(in long index, in boolean modifyIndex);
1.80 +
1.81 +
1.82 + /**
1.83 + * Called to purge older documents from history.
1.84 + * Documents can be removed from session history for various
1.85 + * reasons. For example to control memory usage of the browser, to
1.86 + * prevent users from loading documents from history, to erase evidence of
1.87 + * prior page loads etc...
1.88 + *
1.89 + * @param numEntries The number of toplevel documents to be
1.90 + * purged from history. During purge operation,
1.91 + * the latest documents are maintained and older
1.92 + * 'numEntries' documents are removed from history.
1.93 + * @throws <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code> Purge was vetod.
1.94 + * @throws <code>NS_ERROR_FAILURE</code> numEntries is
1.95 + * invalid or out of bounds with the size of history.
1.96 + *
1.97 + */
1.98 + void PurgeHistory(in long numEntries);
1.99 +
1.100 + /**
1.101 + * Called to register a listener for the session history component.
1.102 + * Listeners are notified when pages are loaded or purged from history.
1.103 + *
1.104 + * @param aListener Listener object to be notified for all
1.105 + * page loads that initiate in session history.
1.106 + *
1.107 + * @note A listener object must implement
1.108 + * nsISHistoryListener and nsSupportsWeakReference
1.109 + *
1.110 + * @see nsISHistoryListener
1.111 + * @see nsSupportsWeakReference
1.112 + */
1.113 + void addSHistoryListener(in nsISHistoryListener aListener);
1.114 +
1.115 + /**
1.116 + * Called to remove a listener for the session history component.
1.117 + * Listeners are notified when pages are loaded from history.
1.118 + *
1.119 + * @param aListener Listener object to be removed from
1.120 + * session history.
1.121 + *
1.122 + * @note A listener object must implement
1.123 + * nsISHistoryListener and nsSupportsWeakReference
1.124 + * @see nsISHistoryListener
1.125 + * @see nsSupportsWeakReference
1.126 + */
1.127 + void removeSHistoryListener(in nsISHistoryListener aListener);
1.128 +
1.129 + /**
1.130 + * Called to obtain a enumerator for all the documents stored in
1.131 + * session history. The enumerator object thus returned by this method
1.132 + * can be traversed using nsISimpleEnumerator.
1.133 + *
1.134 + * @note To access individual history entries of the enumerator, perform the
1.135 + * following steps:
1.136 + * 1) Call nsISHistory->GetSHistoryEnumerator() to obtain handle
1.137 + * the nsISimpleEnumerator object.
1.138 + * 2) Use nsISimpleEnumerator->GetNext() on the object returned
1.139 + * by step #1 to obtain handle to the next object in the list.
1.140 + * The object returned by this step is of type nsISupports.
1.141 + * 3) Perform a QueryInterface on the object returned by step #2
1.142 + * to nsISHEntry.
1.143 + * 4) Use nsISHEntry to access properties of each history entry.
1.144 + *
1.145 + * @see nsISimpleEnumerator
1.146 + * @see nsISHEntry
1.147 + * @see QueryInterface()
1.148 + * @see do_QueryInterface()
1.149 + */
1.150 + readonly attribute nsISimpleEnumerator SHistoryEnumerator;
1.151 +
1.152 + void reloadCurrentEntry();
1.153 +
1.154 + /**
1.155 + * Called to obtain the index to a given history entry.
1.156 + *
1.157 + * @param aEntry The entry to obtain the index of.
1.158 + *
1.159 + * @return <code>NS_OK</code> index for the history entry
1.160 + * is obtained successfully.
1.161 + * <code>NS_ERROR_FAILURE</code> Error in obtaining
1.162 + * index for the given history entry.
1.163 + */
1.164 + long getIndexOfEntry(in nsISHEntry aEntry);
1.165 +};
