docshell/shistory/public/nsISHistory.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1999
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Radha Kulkarni (radha@netscape.com)
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 interface nsIHistoryEntry;
  42 interface nsISHistoryListener;
  43 interface nsISimpleEnumerator;
  44 /**
  45  * An interface to the primary properties of the Session History
  46  * component. In an embedded browser environment, the nsIWebBrowser
  47  * object creates an instance of session history for each open window.
  48  * A handle to the session history object can be obtained from
  49  * nsIWebNavigation. In a non-embedded situation, the  owner of the
  50  * session history component must create a instance of it and set
  51  * it in the nsIWebNavigation object.
  52  * This interface is accessible from javascript.
  53  */
  54
  55
  56 %{C++
  57 #define NS_SHISTORY_CID \
  58 {0x7294fe9c, 0x14d8, 0x11d5, {0x98, 0x82, 0x00, 0xC0, 0x4f, 0xa0, 0x2f, 0x40}}
  59
  60 #define NS_SHISTORY_CONTRACTID "@mozilla.org/browser/shistory;1"
  61 %}
  62
  63 [scriptable, uuid(9883609F-CDD8-4d83-9B55-868FF08AD433)]
  64 interface nsISHistory: nsISupports
  65 {
  66   /**
  67    * A readonly property of the interface that returns
  68    * the number of toplevel documents currently available
  69    * in session history.
  70    */
  71    readonly attribute long count;
  72
  73   /**
  74    * A readonly property of the interface that returns
  75    * the index of the current document in session history.
  76    */
  77    readonly attribute long index;
  78
  79   /**
  80    * A readonly property of the interface that returns
  81    * the index of the last document that started to load and
  82    * didn't finished yet. When document finishes the loading
  83    * value -1 is returned.
  84    */
  85    readonly attribute long requestedIndex;
  86
  87   /**
  88    * A read/write property of the interface, used to Get/Set
  89    * the maximum number of toplevel documents, session history
  90    * can hold for each instance.
  91    */
  92    attribute long maxLength;
  93
  94   /**
  95    * Called to obtain handle to the history entry at a
  96    * given index.
  97    *
  98    * @param index             The index value whose entry is requested.
  99    * @param modifyIndex       A boolean flag that indicates if the current
 100    *                          index of session history should be modified
 101    *                          to the parameter index.
 102    *
 103    * @return                  <code>NS_OK</code> history entry for
 104    *                          the index is obtained successfully.
 105    *                          <code>NS_ERROR_FAILURE</code> Error in obtaining
 106    *                          history entry for the given index.
 107    */
 108    nsIHistoryEntry getEntryAtIndex(in long index, in boolean modifyIndex);
 109
 110
 111   /**
 112    * Called to purge older documents from history.
 113    * Documents can be removed from session history for various
 114    * reasons. For example to  control memory usage of the browser, to
 115    * prevent users from loading documents from history, to erase evidence of
 116    * prior page loads etc...
 117    *
 118    * @param numEntries        The number of toplevel documents to be
 119    *                          purged from history. During purge operation,
 120    *                          the latest documents are maintained and older
 121    *                          'numEntries' documents are removed from history.
 122    * @throws                  <code>NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA</code> Purge was vetod.
 123    * @throws                  <code>NS_ERROR_FAILURE</code> numEntries is
 124    *                          invalid or out of bounds with the size of history.
 125    *
 126    */
 127    void PurgeHistory(in long numEntries);
 128
 129   /**
 130    * Called to register a listener for the session history component.
 131    * Listeners are notified when pages are loaded or purged from history.
 132    *
 133    * @param aListener         Listener object to be notified for all
 134    *                          page loads that initiate in session history.
 135    *
 136    * @note                    A listener object must implement
 137    *                          nsISHistoryListener and nsSupportsWeakReference
 138    *
 139    * @see nsISHistoryListener
 140    * @see nsSupportsWeakReference
 141    */
 142    void addSHistoryListener(in nsISHistoryListener aListener);
 143
 144   /**
 145    * Called to remove a listener for the session history component.
 146    * Listeners are notified when pages are loaded from history.
 147    *
 148    * @param aListener         Listener object to be removed from
 149    *                          session history.
 150    *
 151    * @note                    A listener object must implement
 152    *                          nsISHistoryListener and nsSupportsWeakReference
 153    * @see nsISHistoryListener
 154    * @see nsSupportsWeakReference
 155    */
 156    void removeSHistoryListener(in nsISHistoryListener aListener);
 157
 158   /**
 159    * Called to obtain a enumerator for all the  documents stored in
 160    * session history. The enumerator object thus returned by this method
 161    * can be traversed using nsISimpleEnumerator.
 162    *
 163    * @note  To access individual history entries of the enumerator, perform the
 164    *        following steps:
 165    *        1) Call nsISHistory->GetSHistoryEnumerator() to obtain handle
 166    *           the nsISimpleEnumerator object.
 167    *        2) Use nsISimpleEnumerator->GetNext() on the object returned
 168    *           by step #1 to obtain handle to the next object in the list.
 169    *           The object returned by this step is of type nsISupports.
 170    *        3) Perform a QueryInterface on the object returned by step #2
 171    *           to nsIHistoryEntry.
 172    *        4) Use nsIHistoryEntry to access properties of each history entry.
 173    *
 174    * @see nsISimpleEnumerator
 175    * @see nsIHistoryEntry
 176    * @see QueryInterface()
 177    * @see do_QueryInterface()
 178    */
 179    readonly attribute nsISimpleEnumerator SHistoryEnumerator;
 180 };
 181
 182 [scriptable, uuid(ac8b3eb3-2051-4cce-8303-d6e7938501dd)]
 183 interface nsISHistory_2_0_BRANCH: nsISHistory
 184 {
 185   void reloadCurrentEntry();
 186 };