nsISessionStore

From MDC

The nsISessionStore interface provides a means for extensions and other code to store data in association with browser sessions, tabs, and windows. See also the Session store API article. The API operates on top-level browser.xul windows; see #Note on windows for details.

The user preference browser.sessionstore.enabled must be true for these calls to be successful. See [1]

Contents 1 Method overview 2 Methods 2.1 deleteTabValue() 2.1.1 Parameters 2.2 deleteWindowValue() 2.2.1 Parameters 2.3 duplicateTab() 2.3.1 Parameters 2.3.2 Return value 2.4 getBrowserState() 2.4.1 Return value 2.5 getClosedTabCount() 2.5.1 Parameters 2.5.2 Return values 2.6 getClosedTabData() 2.6.1 Parameters 2.6.2 Return value 2.7 getTabState() 2.7.1 Parameters 2.7.2 Return value 2.8 getTabValue() 2.8.1 Parameters 2.8.2 Return value 2.9 getWindowState() 2.9.1 Parameters 2.9.2 Return value 2.10 getWindowValue() 2.10.1 Parameters 2.10.2 Return value 2.11 init() 2.11.1 Parameters 2.12 setBrowserState() 2.12.1 Parameters 2.13 persistTabAttribute() 2.13.1 Parameters 2.14 setTabState() 2.14.1 Parameters 2.15 setTabValue() 2.15.1 Parameters 2.16 setWindowState() 2.16.1 Parameters 2.17 setWindowValue() 2.17.1 Parameters 2.18 undoCloseTab() 2.18.1 Parameters 3 Note on windows 4 See also

nsISessionStore is defined in browser/components/sessionstore/nsISessionStore.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.8.1).

Inherits from: nsISupports

[edit] 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); New in Firefox 3

AString getBrowserState();

unsigned long getClosedTabCount(in nsIDOMWindow aWindow);

AString getClosedTabData(in nsIDOMWindow aWindow);

AString getTabState(in nsIDOMNode aTab); New in Firefox 3

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 setBrowserState(in AString aState);

void setTabState(in nsIDOMNode aTab, in AString aState); New in Firefox 3

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);

void undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex);

[edit] Methods

[edit] deleteTabValue()

Deletes a value from a specified window.

 void deleteTabValue(
   in nsIDOMNode aTab,
   in AString aKey
 );

[edit] Parameters

aTab

The tab for which to delete the value.

aKey

The key whose value is to be deleted.

[edit] deleteWindowValue()

Deletes a value from a specified window.

 void deleteWindowValue(
   in nsIDOMWindow aWindow,
   in AString aKey
 );

[edit] Parameters

aWindow

The window in which to delete the value.

aKey

The key whose value is to be deleted.

[edit] duplicateTab()

Duplicates a specified tab as thoroughly as possible.

 nsIDOMNode duplicateTab(
   in nsIDOMWindow aWindow,
   in nsIDOMNode aTab
 );

[edit] Parameters

aWindow

The window in which the tab to duplicate resides.

aTab

The tab to duplicate.

[edit] Return value

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

[edit] getBrowserState()

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

 AString getBrowserState();

[edit] Return value

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

[edit] getClosedTabCount()

Returns the number of restorable tabs for a given window.

 unsigned long getClosedTabCount(
   in nsIDOMWindow aWindow
 );

[edit] Parameters

aWindow

The window whose restorable tab count should be returned.

[edit] Return values

The number of restorable tabs in the window.

[edit] getClosedTabData()

Returns a list of closed tabs for a specified window.

 AString getClosedTabData(
   in nsIDOMWindow aWindow
 );

[edit] Parameters

aWindow

The window whose closed tab list is to be retrieved.

[edit] 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.

[edit] getTabState()

Returns the state of the specified tab.

 AString getTabState(
   in nsIDOMNode aTab
 );

[edit] Parameters

aTab

The tab whose state is to be returned.

[edit] Return value

A JSON string representing the state of the specified tab.

[edit] getTabValue()

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

 AString getTabValue(
   in nsIDOMNode aTab,
   in AString aKey
 );

[edit] Parameters

aTab

The tab on which to get the value.

aKey

The key whose corresponding value is to be returned.

[edit] Return value

The string value that was previously assigned to aKey using setTabValue().

[edit] getWindowState()

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

 AString getWindowState(
   in nsIDOMWindow aWindow
 );

[edit] Parameters

aWindow

The window whose state is to be returned. See #Note on windows.

[edit] 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".

[edit] getWindowValue()

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

 AString getWindowValue(
   in nsIDOMWindow aWindow,
   in AString aKey
 );

[edit] Parameters

aWindow

The window from which the value is to be retrieved.

aKey

The key whose corresponding value is to be retrieved.

[edit] Return value

The string value that was previously saved for the specified key, or an empty string if no value is set for that key.

[edit] init()

Initializes the session store service.

 void init(
   in nsIDOMWindow aWindow
 );

[edit] Parameters

aWindow

The window for which to initialize the service.

[edit] setBrowserState()

Sets the current browsing state.

 void setBrowserState(
   in AString aState
 );

[edit] Parameters

aState

A JSON string representing the session state to use.

[edit] persistTabAttribute()

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

 void persistTabAttribute(
   in AString aName
 );

[edit] Parameters

aName

The name of the attribute to be saved and restored for all tabs.

[edit] setTabState()

Sets the state of the specified tab.

 void setTabState(
   in nsIDOMNode aTab,
   in AString aState
 );

[edit] 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().

[edit] setTabValue()

Sets the value of a specified key on a tab.

 void setTabValue(
   in nsIDOMNode aTab,
   in AString aKey,
   in AString aStringValue
 );

[edit] 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. You can use the toSource() method on JavaScript objects, or the eval() function, to assign more complex data (or even entire objects) as the value.

[edit] setWindowState()

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

 void setWindowState(
   in nsIDOMWindow aWindow,
   in AString aState,
   in boolean aOverwrite
 );

[edit] Parameters

aWindow

The browser window 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.

[edit] setWindowValue()

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

 void setWindowValue(
   in nsIDOMWindow aWindow,
   in AString aKey,
   in AString aStringValue
 );

[edit] Parameters

aWindow

The 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. You can use the toSource() method on JavaScript objects, or the eval() function, to assign more complex data (or even entire objects) as the value.

[edit] undoCloseTab()

Reopens a closed tab in a specified window.

 void undoCloseTab(
   in nsIDOMWindow aWindow,
   in unsigned long aIndex
 );

[edit] Parameters

aWindow

The 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.

[edit] 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);
   ...

[edit] See also

nsISupports