• file
• revisions
• annotate
• diff
• comparison
• raw

docshell/shistory/public/nsISHistory.idl@6474c204b198 (annotated)

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.

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