docshell/shistory/public/nsISHistory.idl@6474c204b198
docshell/shistory/public/nsISHistory.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsISHEntry;
9 interface nsISHistoryListener;
10 interface nsISimpleEnumerator;
11 /**
12 * An interface to the primary properties of the Session History
13 * component. In an embedded browser environment, the nsIWebBrowser
14 * object creates an instance of session history for each open window.
15 * A handle to the session history object can be obtained from
16 * nsIWebNavigation. In a non-embedded situation, the owner of the
17 * session history component must create a instance of it and set
18 * it in the nsIWebNavigation object.
19 * This interface is accessible from javascript.
20 */
23 %{C++
24 #define NS_SHISTORY_CID \
25 {0x7b807041, 0xe60a, 0x4384, {0x93, 0x5f, 0xaf, 0x30, 0x61, 0xd8, 0xb8, 0x15}}
27 #define NS_SHISTORY_CONTRACTID "@mozilla.org/browser/shistory;1"
28 %}
30 [scriptable, uuid(7b807041-e60a-4384-935f-af3061d8b815)]
31 interface nsISHistory: nsISupports
32 {
33 /**
34 * A readonly property of the interface that returns
35 * the number of toplevel documents currently available
36 * in session history.
37 */
38 readonly attribute long count;
40 /**
41 * A readonly property of the interface that returns
42 * the index of the current document in session history.
43 */
44 readonly attribute long index;
46 /**
47 * A readonly property of the interface that returns
48 * the index of the last document that started to load and
49 * didn't finished yet. When document finishes the loading
50 * value -1 is returned.
51 */
52 readonly attribute long requestedIndex;
54 /**
55 * A read/write property of the interface, used to Get/Set
56 * the maximum number of toplevel documents, session history
57 * can hold for each instance.
58 */
59 attribute long maxLength;
61 /**
62 * Called to obtain handle to the history entry at a
63 * given index.
64 *
65 * @param index The index value whose entry is requested.
66 * The oldest entry is located at index == 0.
67 * @param modifyIndex A boolean flag that indicates if the current
68 * index of session history should be modified
69 * to the parameter index.
70 *
71 * @return <code>NS_OK</code> history entry for
72 * the index is obtained successfully.
73 * <code>NS_ERROR_FAILURE</code> Error in obtaining
74 * history entry for the given index.
75 */
76 nsISHEntry getEntryAtIndex(in long index, in boolean modifyIndex);
79 /**
80 * Called to purge older documents from history.
81 * Documents can be removed from session history for various
82 * reasons. For example to control memory usage of the browser, to
83 * prevent users from loading documents from history, to erase evidence of
84 * prior page loads etc...
85 *
86 * @param numEntries The number of toplevel documents to be
87 * purged from history. During purge operation,
88 * the latest documents are maintained and older
89 * 'numEntries' documents are removed from history.
90 * @throws <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code> Purge was vetod.
91 * @throws <code>NS_ERROR_FAILURE</code> numEntries is
92 * invalid or out of bounds with the size of history.
93 *
94 */
95 void PurgeHistory(in long numEntries);
97 /**
98 * Called to register a listener for the session history component.
99 * Listeners are notified when pages are loaded or purged from history.
100 *
101 * @param aListener Listener object to be notified for all
102 * page loads that initiate in session history.
103 *
104 * @note A listener object must implement
105 * nsISHistoryListener and nsSupportsWeakReference
106 *
107 * @see nsISHistoryListener
108 * @see nsSupportsWeakReference
109 */
110 void addSHistoryListener(in nsISHistoryListener aListener);
112 /**
113 * Called to remove a listener for the session history component.
114 * Listeners are notified when pages are loaded from history.
115 *
116 * @param aListener Listener object to be removed from
117 * session history.
118 *
119 * @note A listener object must implement
120 * nsISHistoryListener and nsSupportsWeakReference
121 * @see nsISHistoryListener
122 * @see nsSupportsWeakReference
123 */
124 void removeSHistoryListener(in nsISHistoryListener aListener);
126 /**
127 * Called to obtain a enumerator for all the documents stored in
128 * session history. The enumerator object thus returned by this method
129 * can be traversed using nsISimpleEnumerator.
130 *
131 * @note To access individual history entries of the enumerator, perform the
132 * following steps:
133 * 1) Call nsISHistory->GetSHistoryEnumerator() to obtain handle
134 * the nsISimpleEnumerator object.
135 * 2) Use nsISimpleEnumerator->GetNext() on the object returned
136 * by step #1 to obtain handle to the next object in the list.
137 * The object returned by this step is of type nsISupports.
138 * 3) Perform a QueryInterface on the object returned by step #2
139 * to nsISHEntry.
140 * 4) Use nsISHEntry to access properties of each history entry.
141 *
142 * @see nsISimpleEnumerator
143 * @see nsISHEntry
144 * @see QueryInterface()
145 * @see do_QueryInterface()
146 */
147 readonly attribute nsISimpleEnumerator SHistoryEnumerator;
149 void reloadCurrentEntry();
151 /**
152 * Called to obtain the index to a given history entry.
153 *
154 * @param aEntry The entry to obtain the index of.
155 *
156 * @return <code>NS_OK</code> index for the history entry
157 * is obtained successfully.
158 * <code>NS_ERROR_FAILURE</code> Error in obtaining
159 * index for the given history entry.
160 */
161 long getIndexOfEntry(in nsISHEntry aEntry);
162 };
