1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/browser/components/sessionstore/nsISessionStore.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,220 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIDOMWindow;
1.11 +interface nsIDOMNode;
1.12 +
1.13 +/**
1.14 + * nsISessionStore keeps track of the current browsing state - i.e.
1.15 + * tab history, cookies, scroll state, form data, and window features
1.16 + * - and allows to restore everything into one browser window.
1.17 + *
1.18 + * The nsISessionStore API operates mostly on browser windows and the tabbrowser
1.19 + * tabs contained in them:
1.20 + *
1.21 + * * "Browser windows" are those DOM windows having loaded
1.22 + * chrome://browser/content/browser.xul . From overlays you can just pass the
1.23 + * global |window| object to the API, though (or |top| from a sidebar).
1.24 + * From elsewhere you can get browser windows through the nsIWindowMediator
1.25 + * by looking for "navigator:browser" windows.
1.26 + *
1.27 + * * "Tabbrowser tabs" are all the child nodes of a browser window's
1.28 + * |gBrowser.tabContainer| such as e.g. |gBrowser.selectedTab|.
1.29 + */
1.30 +
1.31 +[scriptable, uuid(0c99811f-6c5f-4a78-9c31-2d266d714175)]
1.32 +interface nsISessionStore : nsISupports
1.33 +{
1.34 + /**
1.35 + * Is it possible to restore the previous session. Will always be false when
1.36 + * in Private Browsing mode.
1.37 + */
1.38 + attribute boolean canRestoreLastSession;
1.39 +
1.40 + /**
1.41 + * Restore the previous session if possible. This will not overwrite the
1.42 + * current session. Instead the previous session will be merged into the
1.43 + * current session. Current windows will be reused if they were windows that
1.44 + * pinned tabs were previously restored into. New windows will be opened as
1.45 + * needed.
1.46 + *
1.47 + * Note: This will throw if there is no previous state to restore. Check with
1.48 + * canRestoreLastSession first to avoid thrown errors.
1.49 + */
1.50 + void restoreLastSession();
1.51 +
1.52 + /**
1.53 + * Get the current browsing state.
1.54 + * @returns a JSON string representing the session state.
1.55 + */
1.56 + AString getBrowserState();
1.57 +
1.58 + /**
1.59 + * Set the browsing state.
1.60 + * This will immediately restore the state of the whole application to the state
1.61 + * passed in, *replacing* the current session.
1.62 + *
1.63 + * @param aState is a JSON string representing the session state.
1.64 + */
1.65 + void setBrowserState(in AString aState);
1.66 +
1.67 + /**
1.68 + * @param aWindow is the browser window whose state is to be returned.
1.69 + *
1.70 + * @returns a JSON string representing a session state with only one window.
1.71 + */
1.72 + AString getWindowState(in nsIDOMWindow aWindow);
1.73 +
1.74 + /**
1.75 + * @param aWindow is the browser window whose state is to be set.
1.76 + * @param aState is a JSON string representing a session state.
1.77 + * @param aOverwrite boolean overwrite existing tabs
1.78 + */
1.79 + void setWindowState(in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite);
1.80 +
1.81 + /**
1.82 + * @param aTab is the tabbrowser tab whose state is to be returned.
1.83 + *
1.84 + * @returns a JSON string representing the state of the tab
1.85 + * (note: doesn't contain cookies - if you need them, use getWindowState instead).
1.86 + */
1.87 + AString getTabState(in nsIDOMNode aTab);
1.88 +
1.89 + /**
1.90 + * @param aTab is the tabbrowser tab whose state is to be set.
1.91 + * @param aState is a JSON string representing a session state.
1.92 + */
1.93 + void setTabState(in nsIDOMNode aTab, in AString aState);
1.94 +
1.95 + /**
1.96 + * Duplicates a given tab as thoroughly as possible.
1.97 + *
1.98 + * @param aWindow is the browser window into which the tab will be duplicated.
1.99 + * @param aTab is the tabbrowser tab to duplicate (can be from a different window).
1.100 + * @param aDelta is the offset to the history entry to load in the duplicated tab.
1.101 + * @returns a reference to the newly created tab.
1.102 + */
1.103 + nsIDOMNode duplicateTab(in nsIDOMWindow aWindow, in nsIDOMNode aTab,
1.104 + [optional] in long aDelta);
1.105 +
1.106 + /**
1.107 + * Get the number of restore-able tabs for a browser window
1.108 + */
1.109 + unsigned long getClosedTabCount(in nsIDOMWindow aWindow);
1.110 +
1.111 + /**
1.112 + * Get closed tab data
1.113 + *
1.114 + * @param aWindow is the browser window for which to get closed tab data
1.115 + * @returns a JSON string representing the list of closed tabs.
1.116 + */
1.117 + AString getClosedTabData(in nsIDOMWindow aWindow);
1.118 +
1.119 + /**
1.120 + * @param aWindow is the browser window to reopen a closed tab in.
1.121 + * @param aIndex is the index of the tab to be restored (FIFO ordered).
1.122 + * @returns a reference to the reopened tab.
1.123 + */
1.124 + nsIDOMNode undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
1.125 +
1.126 + /**
1.127 + * @param aWindow is the browser window associated with the closed tab.
1.128 + * @param aIndex is the index of the closed tab to be removed (FIFO ordered).
1.129 + */
1.130 + nsIDOMNode forgetClosedTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
1.131 +
1.132 + /**
1.133 + * Get the number of restore-able windows
1.134 + */
1.135 + unsigned long getClosedWindowCount();
1.136 +
1.137 + /**
1.138 + * Get closed windows data
1.139 + *
1.140 + * @returns a JSON string representing the list of closed windows.
1.141 + */
1.142 + AString getClosedWindowData();
1.143 +
1.144 + /**
1.145 + * @param aIndex is the index of the windows to be restored (FIFO ordered).
1.146 + * @returns the nsIDOMWindow object of the reopened window
1.147 + */
1.148 + nsIDOMWindow undoCloseWindow(in unsigned long aIndex);
1.149 +
1.150 + /**
1.151 + * @param aIndex is the index of the closed window to be removed (FIFO ordered).
1.152 + *
1.153 + * @throws NS_ERROR_INVALID_ARG
1.154 + * when aIndex does not map to a closed window
1.155 + */
1.156 + nsIDOMNode forgetClosedWindow(in unsigned long aIndex);
1.157 +
1.158 + /**
1.159 + * @param aWindow is the window to get the value for.
1.160 + * @param aKey is the value's name.
1.161 + *
1.162 + * @returns A string value or an empty string if none is set.
1.163 + */
1.164 + AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey);
1.165 +
1.166 + /**
1.167 + * @param aWindow is the browser window to set the value for.
1.168 + * @param aKey is the value's name.
1.169 + * @param aStringValue is the value itself (use JSON.stringify/parse before setting JS objects).
1.170 + */
1.171 + void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue);
1.172 +
1.173 + /**
1.174 + * @param aWindow is the browser window to get the value for.
1.175 + * @param aKey is the value's name.
1.176 + */
1.177 + void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey);
1.178 +
1.179 + /**
1.180 + * @param aTab is the tabbrowser tab to get the value for.
1.181 + * @param aKey is the value's name.
1.182 + *
1.183 + * @returns A string value or an empty string if none is set.
1.184 + */
1.185 + AString getTabValue(in nsIDOMNode aTab, in AString aKey);
1.186 +
1.187 + /**
1.188 + * @param aTab is the tabbrowser tab to set the value for.
1.189 + * @param aKey is the value's name.
1.190 + * @param aStringValue is the value itself (use JSON.stringify/parse before setting JS objects).
1.191 + */
1.192 + void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue);
1.193 +
1.194 + /**
1.195 + * @param aTab is the tabbrowser tab to get the value for.
1.196 + * @param aKey is the value's name.
1.197 + */
1.198 + void deleteTabValue(in nsIDOMNode aTab, in AString aKey);
1.199 +
1.200 + /**
1.201 + * @param aKey is the value's name.
1.202 + *
1.203 + * @returns A string value or an empty string if none is set.
1.204 + */
1.205 + AString getGlobalValue(in AString aKey);
1.206 +
1.207 + /**
1.208 + * @param aKey is the value's name.
1.209 + * @param aStringValue is the value itself (use JSON.stringify/parse before setting JS objects).
1.210 + */
1.211 + void setGlobalValue(in AString aKey, in AString aStringValue);
1.212 +
1.213 + /**
1.214 + * @param aTab is the browser tab to get the value for.
1.215 + * @param aKey is the value's name.
1.216 + */
1.217 + void deleteGlobalValue(in AString aKey);
1.218 +
1.219 + /**
1.220 + * @param aName is the name of the attribute to save/restore for all tabbrowser tabs.
1.221 + */
1.222 + void persistTabAttribute(in AString aName);
1.223 +};
