Deprecated since Gecko 20.0 (Firefox 20.0 / Thunderbird 20.0 / SeaMonkey 2.17)
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

Use the asynchronous interface nsIContentPrefService2 instead.

Provides a way for extensions and browser code to save preferences for specific websites. Preferences are saved as key/value pairs on a per-website basis.

dom/interfaces/base/nsIContentPrefService.idlScriptable
Please add a summary to this article.
  Last changed in Gecko 2 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Inherits from: nsISupports

Implemented by: @mozilla.org/content-pref/service;1. To create an instance, use:

var contentPrefService = Components.classes["@mozilla.org/content-pref/service;1"]
                         .getService(Components.interfaces.nsIContentPrefService);

Method overview

void addObserver(in AString aName, in nsIContentPrefObserver aObserver);
nsIVariant getPref(in nsIVariant aGroup, in AString aName, [optional] in nsIContentPrefCallback aCallback);
nsIPropertyBag2 getPrefs(in nsIVariant aGroup);
nsIPropertyBag2 getPrefsByName(in AString aName);
boolean hasPref(in nsIVariant aGroup, in AString aName);
void removeGroupedPrefs();
void removeObserver(in AString aName, in nsIContentPrefObserver aObserver);
void removePref(in nsIVariant aGroup, in AString aName);
void removePrefsByName(in AString aName);
void setPref(in nsIVariant aGroup, in AString aName, in nsIVariant aValue);

Attributes

Attribute Type Description
DBConnection mozIStorageConnection The database connection to the content preferences database. Useful for accessing and manipulating preferences in ways that are caller-specific or for which there is not yet a generic method, although generic functionality useful to multiple callers should generally be added to this unfrozen interface. Also useful for testing the database creation and migration code. Read only.
grouper nsIContentURIGrouper The component that the service uses to determine the groups to which URIs belong. By default, this is the "hostname grouper," which groups URIs by full hostname (in otherwords, by site). Read only.

Methods

addObserver()

Adds an observer that monitors a preference for changes.

void addObserver(
  in AString aName,
  in nsIContentPrefObserver aObserver
);

Parameters

aName
The name of the preference to observe. You may specify null to add a generic observer that is notified of all preference changes.
aObserver
The name of an object implementing nsIContentPrefObserver that will receive notifications of changes to the preference's value.

getPref()

Returns the value of a preference saved for a particular site.

Note: Prior to Gecko 2.0, the site could only be specified by nsIURI. Now a string can be used as well.

nsIVariant getPref(
  in nsIVariant aGroup,
  in AString aName,
  in nsIContentPrefCallback aCallback Optional
);

Parameters

aGroup
The group for which to retrieve a preference; this may be specified as either a URI or as a string; in either case, the group consists of all sites matching the hostname portion of the specified URI. Specify null to get the preference from the global preference space; those preferences apply to all sites.
aName
The name of the preference whose value is to be retrieved.
aCallback
An optional nsIContentPrefCallback to receive the result. If desired, JavaScript callers can instead provide a function to call upon completion.

Return value

The preference's value is returned; this value may be a string, integer, boolean, or any other value. The result may be null (nsIDataType:VTYPE_EMPTY) if the preference's value is either null, or undefined (nsIDataType:VTYPE_VOID) if there is no saved preference by the specified name.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aGroup is not a string, nsIURI, or null. Or if aName is null or an empty string

getPrefs()

Get all preferences and their values for the specified URI.

Note: Prior to Gecko 2.0, the site could only be specified by nsIURI. Now a string can be used as well.

nsIPropertyBag2 getPrefs(
  in nsIVariant aGroup
);

Parameters

aGroup
The group whose preferences are to be retrieved; this may be specified as either a URI or as a string; in either case, the group consists of all sites matching the hostname portion of the specified URI. Specify null to get the preferences from the global preference space; those preferences apply to all sites.

Return value

The result is an nsIPropertyBag2 containing the preferences and their values.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aGroup is not a string, nsIURI, or null.

getPrefsByName()

Returns the values of all preferences with the specified name.

nsIPropertyBag2 getPrefsByName(
  in AString aName
);

Parameters

aName
The name for which all values are to be returned.

Return value

The result is an nsIPropertyBag2 containing the preferences and their values.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aName is null or an empty string.

hasPref()

Determines whether or not a preference exists.

Note: Prior to Gecko 2.0, the site could only be specified by nsIURI. Now a string can be used as well.

boolean hasPref(
  in nsIVariant aGroup,
  in AString aName
);

Parameters

aGroup
The group for which to see if a preference exists; this may be specified as either a URI or as a string. In either case, the group consists of all sites matching the hostname portion of the specified URI. Specify null to check for the preference in the global preference space; those preferences apply to all sites.
aName
The name of the preference whose existence is to be determined.

Return value

true if the preference exists; otherwise false.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aGroup is not a string, nsIURI, or null. Or if aName is null or an empty string

removeGroupedPrefs()

Remove all grouped prefs. Useful for removing references to the sites the user has visited when the user clears their private data.

void removeGroupedPrefs();

removeObserver()

Removes an observer that's presently monitoring a preference for changes.

void removeObserver(
  in AString aName,
  in nsIContentPrefObserver aObserver
);

Parameters

aName
The name of the preference to stop observing. You may specify null to remove a generic observer that is monitoring all preference changes.
aObserver
The name of the observer that will cease receiving notifications of changes to the preference's value.

removePref()

Removes the specified preference.

Note: Prior to Gecko 2.0, the site could only be specified by nsIURI. Now a string can be used as well.

void removePref(
  in nsIVariant aGroup,
  in AString aName
);

Parameters

aGroup
The group for which to delete a preference; this may be specified as either a URI or as a string. In either case, the group consists of all sites matching the hostname portion of the specified URI. Specify null to delete the preference from the global preference space; those preferences apply to all sites.
aName
The name of the preference to remove.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aGroup is not a string, nsIURI, or null. Or if aName is null or an empty string

removePrefsByName()

Removes all preferences with the specified name.

void removePrefsByName(
  in AString aName
);

Parameters

aName
The name of the preferences to remove.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aName is null or an empty string.

setPref()

Sets the value of a preference for a particular URI.

Note: Prior to Gecko 2.0, the site could only be specified by nsIURI. Now a string can be used as well.

void setPref(
  in nsIVariant aGroup,
  in AString aName,
  in nsIVariant aValue
);

Parameters

aGroup
The group for which to set a preference; this may be specified as either a URI or as a string; in either case, the group consists of all sites matching the hostname portion of the specified URI. Specify null to set the preference in the global preference space; those preferences apply to all sites.
aName
The name of the preference whose value is to be set.
aValue
The value to assign to the preference.

Exceptions thrown

NS_ERROR_ILLEGAL_VALUE
If aGroup is not a string, nsIURI, or null. Or if aName is null or an empty string

See also