nsIContentPrefService2

Content Preferences

Content preferences allow the application to associate arbitrary data, or
“preferences”, with specific domains, or web “content”. Specifically, a
content preference is a structure with three values: a domain with which the
preference is associated, a name that identifies the preference within its
domain, and a value. (See nsIContentPref below.)

For example, if you want to remember the user’s preference for a certain zoom
level on www.mozilla.org pages, you might store a preference whose domain is
“www.mozilla.org”, whose name is “zoomLevel”, and whose value is the numeric
zoom level.

A preference need not have a domain, and in that case the preference is
called a “global” preference. This interface doesn’t impart any special
significance to global preferences; they’re simply name-value pairs that
aren’t associated with any particular domain. As a consumer of this
interface, you might choose to let a global preference override all non-
global preferences of the same name, for example, for whatever definition of
“override” is appropriate for your use case.

Domain Parameters

Many methods of this interface accept a “domain” parameter. Domains may be
specified either exactly, like “example.com”, or as full URLs, like
“http://example.com/foo/bar”. In the latter case the API extracts the full
domain from the URL, so if you specify “http://foo.bar.example.com/baz”, the
domain is taken to be “foo.bar.example.com”, not “example.com”.

Private-Browsing Context Parameters

Many methods also accept a “context” parameter. This parameter relates to
private browsing and determines the kind of storage that a method uses,
either the usual permanent storage or temporary storage set aside for private
browsing sessions.

Pass null to unconditionally use permanent storage. Pass an nsILoadContext
to use storage appropriate to the context’s usePrivateBrowsing attribute: if
usePrivateBrowsing is true, temporary private-browsing storage is used, and
otherwise permanent storage is used. A context can be obtained from the
window or channel whose content pertains to the preferences being modified or
retrieved.

Callbacks

The methods of callback objects are always called asynchronously.

Observers are called after callbacks are called, but they are called in the
same turn of the event loop as callbacks.

See nsIContentPrefCallback2 below for more information about callbacks.

Methods

getByName(name, context, callback)

Gets all the preferences with the given name.

Parameters

getByDomainAndName(domain, name, context, callback)

Gets the preference with the given domain and name.

Parameters

getBySubdomainAndName(domain, name, context, callback)

Gets all preferences with the given name whose domains are either the same
as or subdomains of the given domain.

Parameters

getGlobal(name, context, callback)

Gets the preference with no domain and the given name.

Parameters

getCachedByDomainAndName(domain, name, context)

Synchronously retrieves from the in-memory cache the preference with the
given domain and name.

In addition to caching preference values, the cache also keeps track of
preferences that are known not to exist. If the preference is known not to
exist, the value attribute of the returned object will be undefined
(nsIDataType::VTYPE_VOID).

If the preference is neither cached nor known not to exist, then null is
returned, and get() must be called to determine whether the preference
exists.

Parameters

Returns

getCachedBySubdomainAndName(domain, name, context, len, prefs)

Synchronously retrieves from the in-memory cache all preferences with the
given name whose domains are either the same as or subdomains of the given
domain.

The preferences are returned in an array through the out-parameter. If a
preference for a particular subdomain is known not to exist, then an object
corresponding to that preference will be present in the array, and, as with
getCachedByDomainAndName, its value attribute will be undefined.

Parameters

getCachedGlobal(name, context)

Synchronously retrieves from the in-memory cache the preference with no
domain and the given name.

As with getCachedByDomainAndName, if the preference is cached then it is
returned; if the preference is known not to exist, then the value attribute
of the returned object will be undefined; if the preference is neither
cached nor known not to exist, then null is returned.

Parameters

Returns

set(domain, name, value, context, callback)

Sets a preference.

Parameters

setGlobal(name, value, context, callback)

Sets a preference with no domain.

Parameters

removeByDomainAndName(domain, name, context, callback)

Removes the preference with the given domain and name.

Parameters

removeBySubdomainAndName(domain, name, context, callback)

Removes all the preferences with the given name whose domains are either
the same as or subdomains of the given domain.

Parameters

removeGlobal(name, context, callback)

Removes the preference with no domain and the given name.

Parameters

removeByDomain(domain, context, callback)

Removes all preferences with the given domain.

Parameters

removeBySubdomain(domain, context, callback)

Removes all preferences whose domains are either the same as or subdomains
of the given domain.

Parameters

removeByName(name, context, callback)

Removes all preferences with the given name regardless of domain, including
global preferences with the given name.

Parameters

removeAllDomains(context, callback)

Removes all non-global preferences – in other words, all preferences that
have a domain.

Parameters

removeAllDomainsSince(since, context, callback)

Parameters

removeAllGlobals(context, callback)

Removes all global preferences – in other words, all preferences that have
no domain.

Parameters

addObserverForName(name, observer)

Registers an observer that will be notified whenever a preference with the
given name is set or removed.

When a set or remove method is called, observers are called after the set
or removal completes and after the method’s callback is called, and they
are called in the same turn of the event loop as the callback.

The service holds a strong reference to the observer, so the observer must
be removed later to avoid leaking it.

Parameters

removeObserverForName(name, observer)

Unregisters an observer for the given name.

Parameters

extractDomain(str)

Extracts and returns the domain from the given string representation of a
URI. This is how the API extracts domains from URIs passed to it.

Parameters

Returns