nsISupports
Last changed in Gecko 20.0 (Firefox 20.0 / Thunderbird 20.0 / SeaMonkey 2.17)Description
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 "https://example.com/foo/bar". In the latter case the API extracts the full domain from the URL, so if you specify "https://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. See nsIContentPrefCallback2
for more information about callbacks.
Method overview
void addObserverForName(in AString name, in nsIContentPrefObserver observer); |
void getByDomainAndName(in AString domain, in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback); |
void getBySubdomainAndName(in AString domain, in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback); |
nsIContentPref getCachedByDomainAndName(in AString domain, in AString name, in nsILoadContext context); |
void getCachedBySubdomainAndName(in AString domain, in AString name, in nsILoadContext context, out unsigned long len, [retval,array,size_is(len)] out nsIContentPref prefs); |
nsIContentPref getCachedGlobal(in AString name, in nsILoadContext context); |
void getGlobal(in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback); |
void removeAllDomains(in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeAllGlobals(in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeByDomain(in AString domain, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeByDomainAndName(in AString domain, in AString name, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeByName(in AString name, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeBySubdomain(in AString domain, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeBySubdomainAndName(in AString domain, in AString name, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeGlobal(in AString name, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void removeObserverForName(in AString name, in nsIContentPrefObserver observer); |
void set(in AString domain, in AString name, in nsIVariant value, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
void setGlobal(in AString name, in nsIVariant value, in nsILoadContext context, [optional] in nsIContentPrefCallback2 callback); |
Methods
addObserverForName()
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 notified after the set()
or removal completes but before method's callback is called.
The service holds a strong reference to the observer, so the observer must be removed later to avoid leaking it.
void addObserverForName( in AString name, in nsIContentPrefObserver observer );
Parameters
-
name
-
The name of the preferences to observe. Pass
null
to observe all preference changes regardless of name. -
observer
- The observer.
getByDomainAndName()
Gets the preference with the given domain and name.
void getByDomainAndName( in AString domain, in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback );
Parameters
-
domain
- The preference's domain.
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
-
callback
- HandleResult is called once unless no such preference exists, in which case handleResult is not called at all.
getBySubdomainAndName()
Gets all preferences with the given name whose domains are either the same as or subdomains of the given domain.
void getBySubdomainAndName( in AString domain, in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback );
Parameters
-
domain
- The preferences' domain.
-
name
- The preferences' name.
-
context
- The private-browsing context, if any.
-
callback
- HandleResult is called once for each preference. If no such preferences exist, handleResult is not called at all.
getCachedByDomainAndName()
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.
nsIContentPref getCachedByDomainAndName( in AString domain, in AString name, in nsILoadContext context );
Parameters
-
domain
- The preference's domain.
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
Return value
The preference, or null
if no such preference is known to exist.
getCachedBySubdomainAndName()
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.
void getCachedBySubdomainAndName( in AString domain, in AString name, in nsILoadContext context, out unsigned long len, [retval,array,size_is(len)] out nsIContentPref prefs );
Parameters
-
domain
- The preferences' domain.
-
name
- The preferences' name.
-
context
- The private-browsing context, if any.
-
len
- The length of the returned array.
-
prefs
- The array of preferences.
getCachedGlobal()
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.
nsIContentPref getCachedGlobal( in AString name, in nsILoadContext context );
Parameters
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
Return value
The preference, or null
if no such preference is known to exist.
getGlobal()
Gets the preference with no domain and the given name.
void getGlobal( in AString name, in nsILoadContext context, in nsIContentPrefCallback2 callback );
Parameters
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
-
callback
- HandleResult is called once unless no such preference exists, in which case handleResult is not called at all.
removeAllDomains()
Removes all non-global preferences -- in other words, all preferences that have a domain.
void removeAllDomains(
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeAllGlobals()
Removes all global preferences -- in other words, all preferences that have no domain.
void removeAllGlobals(
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeByDomain()
Removes all preferences with the given domain.
void removeByDomain(
in AString domain,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
domain
- The preferences' domain.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeByDomainAndName()
Removes the preference with the given domain and name.
void removeByDomainAndName(
in AString domain,
in AString name,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
domain
- The preference's domain.
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeByName()
Removes all preferences with the given name regardless of domain, including global preferences with the given name.
void removeByName(
in AString name,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
name
- The preferences' name.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeBySubdomain()
Removes all preferences whose domains are either the same as or subdomains of the given domain.
void removeBySubdomain(
in AString domain,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
domain
- The preferences' domain.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeBySubdomainAndName()
Removes all the preferences with the given name whose domains are either the same as or subdomains of the given domain.
void removeBySubdomainAndName(
in AString domain,
in AString name,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
domain
- The preferences' domain.
-
name
- The preferences' name.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeGlobal()
Removes the preference with no domain and the given name.
void removeGlobal(
in AString name,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
name
- The preference's name.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the operation completes.
removeObserverForName()
Unregisters an observer for the given name.
void removeObserverForName( in AString name, in nsIContentPrefObserver observer );
Parameters
-
name
-
The name for which the observer was registered. Pass
null
if the observer was added with anull
name. -
observer
- The observer.
set()
Sets a preference.
void set(
in AString domain,
in AString name,
in nsIVariant value,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
domain
- The preference's domain.
-
name
- The preference's name.
-
value
- The preference's value.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the preference has been stored.
setGlobal()
Sets a preference with no domain.
void setGlobal(
in AString name,
in nsIVariant value,
in nsILoadContext context,
in nsIContentPrefCallback2 callback Optional
);
Parameters
-
name
- The preference's name.
-
value
- The preference's value.
-
context
- The private-browsing context, if any.
-
callback
Optional - HandleCompletion is called when the preference has been stored.
See also
- Old synchronous API:
nsIContentPrefService
- Using content preferences