1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/base/nsIContentPrefService2.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,394 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.6 + * You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIVariant;
1.11 +interface nsIContentPrefObserver;
1.12 +interface nsIContentPrefCallback2;
1.13 +interface nsILoadContext;
1.14 +interface nsIContentPref;
1.15 +
1.16 +/**
1.17 + * Content Preferences
1.18 + *
1.19 + * Content preferences allow the application to associate arbitrary data, or
1.20 + * "preferences", with specific domains, or web "content". Specifically, a
1.21 + * content preference is a structure with three values: a domain with which the
1.22 + * preference is associated, a name that identifies the preference within its
1.23 + * domain, and a value. (See nsIContentPref below.)
1.24 + *
1.25 + * For example, if you want to remember the user's preference for a certain zoom
1.26 + * level on www.mozilla.org pages, you might store a preference whose domain is
1.27 + * "www.mozilla.org", whose name is "zoomLevel", and whose value is the numeric
1.28 + * zoom level.
1.29 + *
1.30 + * A preference need not have a domain, and in that case the preference is
1.31 + * called a "global" preference. This interface doesn't impart any special
1.32 + * significance to global preferences; they're simply name-value pairs that
1.33 + * aren't associated with any particular domain. As a consumer of this
1.34 + * interface, you might choose to let a global preference override all non-
1.35 + * global preferences of the same name, for example, for whatever definition of
1.36 + * "override" is appropriate for your use case.
1.37 + *
1.38 + *
1.39 + * Domain Parameters
1.40 + *
1.41 + * Many methods of this interface accept a "domain" parameter. Domains may be
1.42 + * specified either exactly, like "example.com", or as full URLs, like
1.43 + * "http://example.com/foo/bar". In the latter case the API extracts the full
1.44 + * domain from the URL, so if you specify "http://foo.bar.example.com/baz", the
1.45 + * domain is taken to be "foo.bar.example.com", not "example.com".
1.46 + *
1.47 + *
1.48 + * Private-Browsing Context Parameters
1.49 + *
1.50 + * Many methods also accept a "context" parameter. This parameter relates to
1.51 + * private browsing and determines the kind of storage that a method uses,
1.52 + * either the usual permanent storage or temporary storage set aside for private
1.53 + * browsing sessions.
1.54 + *
1.55 + * Pass null to unconditionally use permanent storage. Pass an nsILoadContext
1.56 + * to use storage appropriate to the context's usePrivateBrowsing attribute: if
1.57 + * usePrivateBrowsing is true, temporary private-browsing storage is used, and
1.58 + * otherwise permanent storage is used. A context can be obtained from the
1.59 + * window or channel whose content pertains to the preferences being modified or
1.60 + * retrieved.
1.61 + *
1.62 + *
1.63 + * Callbacks
1.64 + *
1.65 + * The methods of callback objects are always called asynchronously.
1.66 + *
1.67 + * Observers are called after callbacks are called, but they are called in the
1.68 + * same turn of the event loop as callbacks.
1.69 + *
1.70 + * See nsIContentPrefCallback2 below for more information about callbacks.
1.71 + */
1.72 +
1.73 +[scriptable, uuid(f2507add-dc39-48e0-9147-e0270376148b)]
1.74 +interface nsIContentPrefService2 : nsISupports
1.75 +{
1.76 + /**
1.77 + * Gets all the preferences with the given name.
1.78 + *
1.79 + * @param name The preferences' name.
1.80 + * @param context The private-browsing context, if any.
1.81 + * @param callback handleResult is called once for each preference unless
1.82 + * no such preferences exist, in which case handleResult
1.83 + * is not called at all.
1.84 + */
1.85 + void getByName(in AString name,
1.86 + in nsILoadContext context,
1.87 + in nsIContentPrefCallback2 callback);
1.88 +
1.89 + /**
1.90 + * Gets the preference with the given domain and name.
1.91 + *
1.92 + * @param domain The preference's domain.
1.93 + * @param name The preference's name.
1.94 + * @param context The private-browsing context, if any.
1.95 + * @param callback handleResult is called once unless no such preference
1.96 + * exists, in which case handleResult is not called at all.
1.97 + */
1.98 + void getByDomainAndName(in AString domain,
1.99 + in AString name,
1.100 + in nsILoadContext context,
1.101 + in nsIContentPrefCallback2 callback);
1.102 +
1.103 + /**
1.104 + * Gets all preferences with the given name whose domains are either the same
1.105 + * as or subdomains of the given domain.
1.106 + *
1.107 + * @param domain The preferences' domain.
1.108 + * @param name The preferences' name.
1.109 + * @param context The private-browsing context, if any.
1.110 + * @param callback handleResult is called once for each preference. If no
1.111 + * such preferences exist, handleResult is not called at all.
1.112 + */
1.113 + void getBySubdomainAndName(in AString domain,
1.114 + in AString name,
1.115 + in nsILoadContext context,
1.116 + in nsIContentPrefCallback2 callback);
1.117 +
1.118 + /**
1.119 + * Gets the preference with no domain and the given name.
1.120 + *
1.121 + * @param name The preference's name.
1.122 + * @param context The private-browsing context, if any.
1.123 + * @param callback handleResult is called once unless no such preference
1.124 + * exists, in which case handleResult is not called at all.
1.125 + */
1.126 + void getGlobal(in AString name,
1.127 + in nsILoadContext context,
1.128 + in nsIContentPrefCallback2 callback);
1.129 +
1.130 + /**
1.131 + * Synchronously retrieves from the in-memory cache the preference with the
1.132 + * given domain and name.
1.133 + *
1.134 + * In addition to caching preference values, the cache also keeps track of
1.135 + * preferences that are known not to exist. If the preference is known not to
1.136 + * exist, the value attribute of the returned object will be undefined
1.137 + * (nsIDataType::VTYPE_VOID).
1.138 + *
1.139 + * If the preference is neither cached nor known not to exist, then null is
1.140 + * returned, and get() must be called to determine whether the preference
1.141 + * exists.
1.142 + *
1.143 + * @param domain The preference's domain.
1.144 + * @param name The preference's name.
1.145 + * @param context The private-browsing context, if any.
1.146 + * @return The preference, or null if no such preference is known to
1.147 + * exist.
1.148 + */
1.149 + nsIContentPref getCachedByDomainAndName(in AString domain,
1.150 + in AString name,
1.151 + in nsILoadContext context);
1.152 +
1.153 + /**
1.154 + * Synchronously retrieves from the in-memory cache all preferences with the
1.155 + * given name whose domains are either the same as or subdomains of the given
1.156 + * domain.
1.157 + *
1.158 + * The preferences are returned in an array through the out-parameter. If a
1.159 + * preference for a particular subdomain is known not to exist, then an object
1.160 + * corresponding to that preference will be present in the array, and, as with
1.161 + * getCachedByDomainAndName, its value attribute will be undefined.
1.162 + *
1.163 + * @param domain The preferences' domain.
1.164 + * @param name The preferences' name.
1.165 + * @param context The private-browsing context, if any.
1.166 + * @param len The length of the returned array.
1.167 + * @param prefs The array of preferences.
1.168 + */
1.169 + void getCachedBySubdomainAndName(in AString domain,
1.170 + in AString name,
1.171 + in nsILoadContext context,
1.172 + [optional] out unsigned long len,
1.173 + [retval,array,size_is(len)] out nsIContentPref prefs);
1.174 +
1.175 + /**
1.176 + * Synchronously retrieves from the in-memory cache the preference with no
1.177 + * domain and the given name.
1.178 + *
1.179 + * As with getCachedByDomainAndName, if the preference is cached then it is
1.180 + * returned; if the preference is known not to exist, then the value attribute
1.181 + * of the returned object will be undefined; if the preference is neither
1.182 + * cached nor known not to exist, then null is returned.
1.183 + *
1.184 + * @param name The preference's name.
1.185 + * @param context The private-browsing context, if any.
1.186 + * @return The preference, or null if no such preference is known to
1.187 + * exist.
1.188 + */
1.189 + nsIContentPref getCachedGlobal(in AString name,
1.190 + in nsILoadContext context);
1.191 +
1.192 + /**
1.193 + * Sets a preference.
1.194 + *
1.195 + * @param domain The preference's domain.
1.196 + * @param name The preference's name.
1.197 + * @param value The preference's value.
1.198 + * @param context The private-browsing context, if any.
1.199 + * @param callback handleCompletion is called when the preference has been
1.200 + * stored.
1.201 + */
1.202 + void set(in AString domain,
1.203 + in AString name,
1.204 + in nsIVariant value,
1.205 + in nsILoadContext context,
1.206 + [optional] in nsIContentPrefCallback2 callback);
1.207 +
1.208 + /**
1.209 + * Sets a preference with no domain.
1.210 + *
1.211 + * @param name The preference's name.
1.212 + * @param value The preference's value.
1.213 + * @param context The private-browsing context, if any.
1.214 + * @param callback handleCompletion is called when the preference has been
1.215 + * stored.
1.216 + */
1.217 + void setGlobal(in AString name,
1.218 + in nsIVariant value,
1.219 + in nsILoadContext context,
1.220 + [optional] in nsIContentPrefCallback2 callback);
1.221 +
1.222 + /**
1.223 + * Removes the preference with the given domain and name.
1.224 + *
1.225 + * @param domain The preference's domain.
1.226 + * @param name The preference's name.
1.227 + * @param context The private-browsing context, if any.
1.228 + * @param callback handleCompletion is called when the operation completes.
1.229 + */
1.230 + void removeByDomainAndName(in AString domain,
1.231 + in AString name,
1.232 + in nsILoadContext context,
1.233 + [optional] in nsIContentPrefCallback2 callback);
1.234 +
1.235 + /**
1.236 + * Removes all the preferences with the given name whose domains are either
1.237 + * the same as or subdomains of the given domain.
1.238 + *
1.239 + * @param domain The preferences' domain.
1.240 + * @param name The preferences' name.
1.241 + * @param context The private-browsing context, if any.
1.242 + * @param callback handleCompletion is called when the operation completes.
1.243 + */
1.244 + void removeBySubdomainAndName(in AString domain,
1.245 + in AString name,
1.246 + in nsILoadContext context,
1.247 + [optional] in nsIContentPrefCallback2 callback);
1.248 +
1.249 + /**
1.250 + * Removes the preference with no domain and the given name.
1.251 + *
1.252 + * @param name The preference's name.
1.253 + * @param context The private-browsing context, if any.
1.254 + * @param callback handleCompletion is called when the operation completes.
1.255 + */
1.256 + void removeGlobal(in AString name,
1.257 + in nsILoadContext context,
1.258 + [optional] in nsIContentPrefCallback2 callback);
1.259 +
1.260 + /**
1.261 + * Removes all preferences with the given domain.
1.262 + *
1.263 + * @param domain The preferences' domain.
1.264 + * @param context The private-browsing context, if any.
1.265 + * @param callback handleCompletion is called when the operation completes.
1.266 + */
1.267 + void removeByDomain(in AString domain,
1.268 + in nsILoadContext context,
1.269 + [optional] in nsIContentPrefCallback2 callback);
1.270 +
1.271 + /**
1.272 + * Removes all preferences whose domains are either the same as or subdomains
1.273 + * of the given domain.
1.274 + *
1.275 + * @param domain The preferences' domain.
1.276 + * @param context The private-browsing context, if any.
1.277 + * @param callback handleCompletion is called when the operation completes.
1.278 + */
1.279 + void removeBySubdomain(in AString domain,
1.280 + in nsILoadContext context,
1.281 + [optional] in nsIContentPrefCallback2 callback);
1.282 +
1.283 + /**
1.284 + * Removes all preferences with the given name regardless of domain, including
1.285 + * global preferences with the given name.
1.286 + *
1.287 + * @param name The preferences' name.
1.288 + * @param context The private-browsing context, if any.
1.289 + * @param callback handleCompletion is called when the operation completes.
1.290 + */
1.291 + void removeByName(in AString name,
1.292 + in nsILoadContext context,
1.293 + [optional] in nsIContentPrefCallback2 callback);
1.294 +
1.295 + /**
1.296 + * Removes all non-global preferences -- in other words, all preferences that
1.297 + * have a domain.
1.298 + *
1.299 + * @param context The private-browsing context, if any.
1.300 + * @param callback handleCompletion is called when the operation completes.
1.301 + */
1.302 + void removeAllDomains(in nsILoadContext context,
1.303 + [optional] in nsIContentPrefCallback2 callback);
1.304 +
1.305 + /**
1.306 + * Removes all global preferences -- in other words, all preferences that have
1.307 + * no domain.
1.308 + *
1.309 + * @param context The private-browsing context, if any.
1.310 + * @param callback handleCompletion is called when the operation completes.
1.311 + */
1.312 + void removeAllGlobals(in nsILoadContext context,
1.313 + [optional] in nsIContentPrefCallback2 callback);
1.314 +
1.315 + /**
1.316 + * Registers an observer that will be notified whenever a preference with the
1.317 + * given name is set or removed.
1.318 + *
1.319 + * When a set or remove method is called, observers are called after the set
1.320 + * or removal completes and after the method's callback is called, and they
1.321 + * are called in the same turn of the event loop as the callback.
1.322 + *
1.323 + * The service holds a strong reference to the observer, so the observer must
1.324 + * be removed later to avoid leaking it.
1.325 + *
1.326 + * @param name The name of the preferences to observe. Pass null to
1.327 + * observe all preference changes regardless of name.
1.328 + * @param observer The observer.
1.329 + */
1.330 + void addObserverForName(in AString name,
1.331 + in nsIContentPrefObserver observer);
1.332 +
1.333 + /**
1.334 + * Unregisters an observer for the given name.
1.335 + *
1.336 + * @param name The name for which the observer was registered. Pass null
1.337 + * if the observer was added with a null name.
1.338 + * @param observer The observer.
1.339 + */
1.340 + void removeObserverForName(in AString name,
1.341 + in nsIContentPrefObserver observer);
1.342 +
1.343 + /**
1.344 + * Extracts and returns the domain from the given string representation of a
1.345 + * URI. This is how the API extracts domains from URIs passed to it.
1.346 + *
1.347 + * @param str The string representation of a URI, like
1.348 + * "http://example.com/foo/bar".
1.349 + * @return If the given string is a valid URI, the domain of that URI is
1.350 + * returned. Otherwise, the string itself is returned.
1.351 + */
1.352 + AString extractDomain(in AString str);
1.353 +};
1.354 +
1.355 +/**
1.356 + * The callback used by the above methods.
1.357 + */
1.358 +[scriptable, uuid(1a12cf41-79e8-4d0f-9899-2f7b27c5d9a1)]
1.359 +interface nsIContentPrefCallback2 : nsISupports
1.360 +{
1.361 + /**
1.362 + * For the retrieval methods, this is called once for each retrieved
1.363 + * preference. It is not called for other methods.
1.364 + *
1.365 + * @param pref The retrieved preference.
1.366 + */
1.367 + void handleResult(in nsIContentPref pref);
1.368 +
1.369 + /**
1.370 + * Called when an error occurs. This may be called multiple times before
1.371 + * handleCompletion is called.
1.372 + *
1.373 + * @param error A number in Components.results describing the error.
1.374 + */
1.375 + void handleError(in nsresult error);
1.376 +
1.377 + /**
1.378 + * Called when the method finishes. This will be called exactly once for
1.379 + * each method invocation, and afterward no other callback methods will be
1.380 + * called.
1.381 + *
1.382 + * @param reason One of the COMPLETE_* values indicating the manner in which
1.383 + * the method completed.
1.384 + */
1.385 + void handleCompletion(in unsigned short reason);
1.386 +
1.387 + const unsigned short COMPLETE_OK = 0;
1.388 + const unsigned short COMPLETE_ERROR = 1;
1.389 +};
1.390 +
1.391 +[scriptable, function, uuid(9f24948d-24b5-4b1b-b554-7dbd58c1d792)]
1.392 +interface nsIContentPref : nsISupports
1.393 +{
1.394 + readonly attribute AString domain;
1.395 + readonly attribute AString name;
1.396 + readonly attribute nsIVariant value;
1.397 +};
