browser/components/sessionstore/nsISessionStore.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Session Restore component.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Simon Bünzli <zeniko@gmail.com>
  18  * Portions created by the Initial Developer are Copyright (C) 2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Dietrich Ayala <dietrich@mozilla.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 interface nsIDOMWindow;
  41 interface nsIDOMNode;
  42
  43 /**
  44  * nsISessionStore keeps track of the current browsing state - i.e.
  45  * tab history, cookies, scroll state, form data, POSTDATA and window features
  46  * - and allows to restore everything into one browser window.
  47  *
  48  * The nsISessionStore API operates mostly on browser windows and the tabbrowser
  49  * tabs contained in them:
  50  *
  51  * * "Browser windows" are those DOM windows having loaded
  52  * chrome://browser/content/browser.xul . From overlays you can just pass the
  53  * global |window| object to the API, though (or |top| from a sidebar).
  54  * From elsewhere you can get browser windows through the nsIWindowMediator
  55  * by looking for "navigator:browser" windows.
  56  *
  57  * * "Tabbrowser tabs" are all the child nodes of a browser window's
  58  * |getBrowser().tabContainer| such as e.g. |getBrowser().selectedTab|.
  59  */
  60
  61 [scriptable, uuid(58d17e12-a80f-11dc-8314-0800200c9a66)]
  62 interface nsISessionStore : nsISupports
  63 {
  64   /**
  65    * Initialize the service
  66    */
  67   void init(in nsIDOMWindow aWindow);
  68
  69   /**
  70    * Get the current browsing state.
  71    * @returns a JSON string representing the session state.
  72    */
  73   AString getBrowserState();
  74
  75   /**
  76    * Set the browsing state.
  77    * This will immediately restore the state of the whole application to the state
  78    * passed in, *replacing* the current session.
  79    *
  80    * @param aState is a JSON string representing the session state.
  81    */
  82   void setBrowserState(in AString aState);
  83
  84   /**
  85    * @param aWindow is the browser window whose state is to be returned.
  86    *
  87    * @returns a JSON string representing a session state with only one window.
  88    */
  89   AString getWindowState(in nsIDOMWindow aWindow);
  90
  91   /**
  92    * @param aWindow    is the browser window whose state is to be set.
  93    * @param aState     is a JSON string representing a session state.
  94    * @param aOverwrite boolean overwrite existing tabs
  95    */
  96   void setWindowState(in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite);
  97
  98   /**
  99    * @param aTab is the tabbrowser tab whose state is to be returned.
 100    *
 101    * @returns a JSON string representing the state of the tab
 102    *         (note: doesn't contain cookies - if you need them, use getWindowState instead).
 103    */
 104   AString getTabState(in nsIDOMNode aTab);
 105
 106   /**
 107    * @param aTab   is the tabbrowser tab whose state is to be set.
 108    * @param aState is a JSON string representing a session state.
 109    */
 110   void setTabState(in nsIDOMNode aTab, in AString aState);
 111
 112   /**
 113    * Duplicates a given tab as thoroughly as possible.
 114    *
 115    * @param aWindow is the browser window into which the tab will be duplicated.
 116    * @param aTab    is the tabbrowser tab to duplicate (can be from a different window).
 117    * @returns a reference to the newly created tab.
 118    */
 119   nsIDOMNode duplicateTab(in nsIDOMWindow aWindow, in nsIDOMNode aTab);
 120
 121   /**
 122    * Get the number of restore-able tabs for a browser window
 123    */
 124   unsigned long getClosedTabCount(in nsIDOMWindow aWindow);
 125
 126   /**
 127    * Get closed tab data
 128    *
 129    * @param aWindow is the browser window for which to get closed tab data
 130    * @returns a JSON string representing the list of closed tabs.
 131    */
 132   AString getClosedTabData(in nsIDOMWindow aWindow);
 133
 134   /**
 135    * @param aWindow is the browser window to reopen a closed tab in.
 136    * @param aIndex  is the index of the tab to be restored (FIFO ordered).
 137    */
 138   void undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
 139
 140   /**
 141    * @param aWindow is the window to get the value for.
 142    * @param aKey    is the value's name.
 143    *
 144    * @returns A string value or an empty string if none is set.
 145    */
 146   AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey);
 147
 148   /**
 149    * @param aWindow      is the browser window to set the value for.
 150    * @param aKey         is the value's name.
 151    * @param aStringValue is the value itself (use toSource/eval before setting JS objects).
 152    */
 153   void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue);
 154
 155   /**
 156    * @param aWindow is the browser window to get the value for.
 157    * @param aKey    is the value's name.
 158    */
 159   void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey);
 160
 161   /**
 162    * @param aTab is the tabbrowser tab to get the value for.
 163    * @param aKey is the value's name.
 164    *
 165    * @returns A string value or an empty string if none is set.
 166    */
 167   AString getTabValue(in nsIDOMNode aTab, in AString aKey);
 168
 169   /**
 170    * @param aTab         is the tabbrowser tab to set the value for.
 171    * @param aKey         is the value's name.
 172    * @param aStringValue is the value itself (use toSource/eval before setting JS objects).
 173    */
 174   void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue);
 175
 176   /**
 177    * @param aTab is the tabbrowser tab to get the value for.
 178    * @param aKey is the value's name.
 179    */
 180   void deleteTabValue(in nsIDOMNode aTab, in AString aKey);
 181
 182   /**
 183    * @param aName is the name of the attribute to save/restore for all tabbrowser tabs.
 184    */
 185   void persistTabAttribute(in AString aName);
 186 };