browser/components/sessionstore/nsISessionStore.idlScriptable
Provides a means for extensions and other code to store data in association with browser sessions, tabs, and windows. The API operates on top-level browser.xul and navigator.xul windows; see Note on windows for details.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

In versions of Firefox prior to 3.5, the user preference browser.sessionstore.enabled must be true for these calls to be successful. Starting in Firefox 3.5, this preference is no longer used.

Method overview

void deleteTabValue(in nsIDOMNode aTab, in AString aKey);
void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey);
nsIDOMNode duplicateTab(in nsIDOMWindow aWindow, in nsIDOMNode aTab);
nsIDOMNode forgetClosedTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
nsIDOMNode forgetClosedWindow(in unsigned long aIndex);
AString getBrowserState();
unsigned long getClosedTabCount(in nsIDOMWindow aWindow);
AString getClosedTabData(in nsIDOMWindow aWindow);
unsigned long getClosedWindowCount();
AString getClosedWindowData();
AString getTabState(in nsIDOMNode aTab);
AString getTabValue(in nsIDOMNode aTab, in AString aKey);
AString getWindowState(in nsIDOMWindow aWindow);
AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey);
void init(in nsIDOMWindow aWindow);
void persistTabAttribute(in AString aName);
void restoreLastSession();
void setBrowserState(in AString aState);
void setTabState(in nsIDOMNode aTab, in AString aState);
void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue);
void setWindowState(in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite);
void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue);
nsIDOMNode undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
nsIDOMWindow undoCloseWindow(in unsigned long aIndex);

Attributes

Attribute Type Description
canRestoreLastSession boolean Is it possible to restore the previous session. Will always be false when in Private Browsing mode.

Methods

deleteTabValue()

Deletes a value from a specified tab.

void deleteTabValue(
  in nsIDOMNode aTab,
  in AString aKey
);
Parameters
aTab
The tab for which to delete the value.
aKey
The key whose value is to be deleted.
Exceptions thrown

This method throws a NS_ERROR_ILLEGAL_VALUE exception if the key doesn't exist.

deleteWindowValue()

Deletes a value from a specified window.

void deleteWindowValue(
  in nsIDOMWindow aWindow,
  in AString aKey
);
Parameters
aWindow
The window in which to delete the value.
aKey
The key whose value is to be deleted.

duplicateTab()

Duplicates a specified tab as thoroughly as possible.

nsIDOMNode duplicateTab(
  in nsIDOMWindow aWindow,
  in nsIDOMNode aTab
);
Parameters
aWindow
The window in which the duplicated tab will be created.
aTab
The tab to duplicate (can come from a different window).
Return value

An nsIDOMNode representing the new tab, the content of which is a duplicate of aTab.

forgetClosedTab()

nsIDOMNode forgetClosedTab(
  in nsIDOMWindow aWindow,
  in unsigned long aIndex
);
Parameters
aWindow
Is the browser window associated with the closed tab.
aIndex
Is the index of the closed tab to be removed (FIFO ordered).
Return value

 

forgetClosedWindow()

nsIDOMNode forgetClosedWindow(
  in unsigned long aIndex
);
Parameters
aIndex
Is the index of the closed window to be removed (FIFO ordered).
Return value

 

Exceptions thrown
NS_ERROR_INVALID_ARG
When aIndex does not map to a closed window.

getBrowserState()

Returns the current state of all of windows and all of their tabs.

AString getBrowserState();
Parameters

None.

Return value

A JSON string representing the current state of all windows in the web browser.

getClosedTabCount()

Returns the number of restorable tabs for a given window.

unsigned long getClosedTabCount(
  in nsIDOMWindow aWindow
);
Parameters
aWindow
The window whose restorable tab count should be returned.
Return value

The number of restorable tabs in the window.

getClosedTabData()

Returns a list of closed tabs for a specified window.

AString getClosedTabData(
  in nsIDOMWindow aWindow
);
Parameters
aWindow
The browser window whose closed tab list is to be retrieved.
Return value

A JSON string representing the list of closed tabs for the window specified by aWindow. The list is in last in/first out (LIFO) order, so that the first item in the list is the last tab that was closed.

getClosedWindowCount()

Returns the number of restorable windows.

unsigned long getClosedWindowCount();
Parameters

None.

Return value

The number of restorable windows.

getClosedWindowData()

Returns a list of closed windows.

AString getClosedWindowData();
Parameters

None.

Return value

A JSON string representing the list of closed windows. The list is in last in/first out (LIFO) order, so that the first item in the list is the last window that was closed.

getTabState()

Returns the state of the specified tab.

AString getTabState(
  in nsIDOMNode aTab
);
Parameters
aTab
The tab whose state is to be returned.
Return value

A JSON string representing the state of the specified tab.

Note: The returned string does not include cookies. If you need to retrieve cookies as well, you should use getWindowState() instead.

getTabValue()

Returns the value corresponding to a key on a given window.

AString getTabValue(
  in nsIDOMNode aTab,
  in AString aKey
);
Parameters
aTab
The tab on which to get the value.
aKey
The key whose corresponding value is to be returned.
Return value

The string value that was previously assigned to aKey using nsISessionStore.setTabValue(), or an empty string if no value is set for that key.

If the previously saved value was originally a complex data (ie a JavaScript object) it can then be deserialized using JSON.parse cf. nsISessionStore.setTabValue().

getWindowState()

Returns the current state of one specified window in the web browser.

AString getWindowState(
  in nsIDOMWindow aWindow
);
Parameters
aWindow
The browser window whose state is to be returned. See #Note on windows.
Return value

A JSON string representing a session state that contains only the window specified by aWindow.

If the preference browser.sessionstate.enabled is false when this method is called, then you will get an exception about "aWindows[i] has no properties".

getWindowValue()

Returns the string value associated with a given key for a window.

AString getWindowValue(
  in nsIDOMWindow aWindow,
  in AString aKey
);
Parameters
aWindow
The window from which the value is to be retrieved.
aKey
The key whose corresponding value is to be retrieved.
Return value

The string value that was previously assigned to aKey using nsISessionStore.setWindowValue(), or an empty string if no value is set for that key.

If the previously saved value was originally a complex data (ie a JavaScript object) it can then be deserialized using JSON.parse cf. nsISessionStore.setWindowValue().

init()

Initializes the session store service.

Note: This function is intended for use only by the browser; extensions shouldn't call it.

void init(
  in nsIDOMWindow aWindow
);
Parameters
aWindow
The window for which to initialize the service.

persistTabAttribute()

Sets the name of a tab attribute to be saved and restored for all XUL tabs.

Note: At present, there's no way to pick and choose tabs to set persistent attributes for. This method affects all tabs indiscriminately.

void persistTabAttribute(
  in AString aName
);
Parameters
aName
The name of the attribute to be saved and restored for all tabs.

restoreLastSession()

Restore the previous session if possible. This will not overwrite the current session. Instead the previous session will be merged into the current session. Current windows will be reused if they were windows that pinned tabs were previously restored into. New windows will be opened as needed.

Note: This will throw if there is no previous state to restore. Check with canRestoreLastSession first to avoid thrown errors.

void restoreLastSession();
Parameters

None.

setBrowserState()

Sets the current browsing state.

Note: Calling setBrowserState immediately replaces the current session, restoring the state of the entire application to the state passed in the aState parameter.

void setBrowserState(
  in AString aState
);
Parameters
aState
A JSON string representing the session state to use.

setTabState()

Sets the state of the specified tab.

void setTabState(
  in nsIDOMNode aTab,
  in AString aState
);
Parameters
aTab
The tab whose state is to be set.
aState
The JSON string representing the tab state to set on the tab, such as one returned by getTabState().

setTabValue()

Sets the value of a specified key on a tab.

void setTabValue(
  in nsIDOMNode aTab,
  in AString aKey,
  in AString aStringValue
);
Parameters
aTab
The tab for which the value is to be set.
aKey
The key whose value is to be set.
aStringValue
A string to set as the value for the key aKey.To assign more complex data (ie JavaScript objects) serialize them using JSON.stringify.

setWindowState()

Sets the state of a single window to a given stored state.

void setWindowState(
  in nsIDOMWindow aWindow,
  in AString aState,
  in boolean aOverwrite
);
Parameters
aWindow
The nsIDOMWindow whose state is to be set to the state indicated by aState.
aState
The saved state to apply to the specified window.
aOverwrite
If this parameter is true, all existing tabs are removed and replaced with the tabs in the state aState. If it's false, the tabs in aState are added to the tabs already in the window.

setWindowValue()

Sets the value corresponding to a given key for a specified window.

void setWindowValue(
  in nsIDOMWindow aWindow,
  in AString aKey,
  in AString aStringValue
);
Parameters
aWindow
The browser window for which the value is to be set.
aKey
The key whose value is to be set.
aStringValue
A string to set as the value for the key aKey. To assign more complex data (ie JavaScript objects) serialize them using JSON.stringify.

undoCloseTab()

Reopens a closed tab in a specified window.

nsIDOMNode undoCloseTab(
  in nsIDOMWindow aWindow,
  in unsigned long aIndex
);
Parameters
aWindow
The browser window in which to reopen a closed tab.
aIndex
The index number of the closed tab to restore. This should be a value from 0 to one less than the value returned by getClosedTabCount(). The list of closed tabs is stored in last in/first out (LIFO) order, so the tab at index 0 is the last one that was closed.
Return value

Prior to Gecko 1.9.1, this method did not return anything. Starting with Gecko 1.9.1, it returns a reference to the reopened tab as an nsIDOMNode object.

undoCloseWindow()

Reopens a closed window.

nsIDOMWindow undoCloseWindow(
  in unsigned long aIndex
);
Parameters
aIndex
The index of the window to be restored. This should be a value from 0 to one less than that returned by getClosedWindowCount(). The list of closed windows is stored in last in/first out (LIFO) order, so the window at index 0 is the last one that was closed.
Return value

Returns a reference to the reopened window as an nsIDOMWindow object.

Note on windows

The nsISessionStore API stores state information for certain windows inside the web brower. These windows are nsIDOMWindow objects that contain the tabbrowser that users see as tabs; the document in these windows is browser.xul.

For many extensions, those that overlay browser.xul, the appropriate window object for nsISessionStore is the global object 'window'.

For JavaScript running in windows other than the one you want to use in nsISessionStore, you need a nsIDOMWindow object containing browser.xul. This will be the outermost or root nsIDOMWindow in a nsIXULWindow (the window seen by users as a moveable frame on the display). This kind of DOMWindow object can be obtained from other nsIDOMWindow objects (like the sidebar window object) by applying the 'mainWindow' statement from Working_with_windows_in_chrome_code. This outermost or root window can also be obtained from the list returned by nsIWindowMediator; see example #3 in Working_with_windows_in_chrome_code. It can also be obtained from an nsIXULWindow using

if (xul_win.docShell instanceof nsIInterfaceRequestor)  {
   var win = xul_win.docShell.getInterface(nsIDOMWindow);
   ...

Note on tabs

The nsISessionStore APIs referencing nsIDOMNode aTab require you to get hold of the tab node storing the data. If you you are working in a browser.xul overlay and want the currently selected tab, it's as simple as gBrowser.selectedTab. If you just hold a reference to some content document in the overlay's chrome window, here is how you find its corresponding tab:

function tabFromDoc(doc) {
  var no = gBrowser.getBrowserIndexForDocument(doc);
  return gBrowser.tabContainer.childNodes[no];
}

// example use:
Cc['@mozilla.org/browser/sessionstore;1']
  .getService(Ci.nsISessionStore)
  .setTabValue(tabFromDoc(myContentDoc), 'myKey', 'myValue');

See also