nsIContentPrefService

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.

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

Attributes

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.

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.

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.

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.

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

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.

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

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.

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

• nsIContentPrefService2
• nsIContentPrefObserver
• Using content preferences