1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsISupports.idl"
7 #include
"nsIPrefBranch.idl"
12 * A helper function for reading access statistics for preferences.
13 * See nsIPrefService.readStats for more details.
15 [function
, scriptable
, uuid(c3f0cedc
-e244
-4316-b33a
-80306a1c35a1
)]
16 interface nsIPrefStatsCallback
: nsISupports
18 void visit
(in ACString prefName
, in unsigned long accessCount
);
21 [scriptable
, uuid(0a2dbc02
-2218-4687-b151
-33d890676e00
)]
22 interface nsIPrefObserver
: nsISupports
25 * Invoked when a string preference is witnessed. kind will be "Default" or "User".
27 void onStringPref
(in string kind
, in string name
, in string value
, in boolean isSticky
, in boolean isLocked
);
30 * Invoked when a integer preference is witnessed. kind will be "Default" or "User".
32 void onIntPref
(in string kind
, in string name
, in long value
, in boolean isSticky
, in boolean isLocked
);
35 * Invoked when a boolean preference is witnessed. kind will be "Default" or "User".
37 void onBoolPref
(in string kind
, in string name
, in boolean value
, in boolean isSticky
, in boolean isLocked
);
40 * Invoked when the prefs parser encounters an error.
42 void onError
(in string message);
46 * The nsIPrefService interface is the main entry point into the back end
47 * preferences management library. The preference service is directly
48 * responsible for the management of the preferences files and also facilitates
49 * access to the preference branch object which allows the direct manipulation
50 * of the preferences themselves.
55 [scriptable
, uuid(1f84fd56
-3956-40df
-b86a
-1ea01402ee96
)]
56 interface nsIPrefService
: nsISupports
59 * Called to completely flush and re-initialize the preferences system.
61 * @throws Error The preference service failed to restart correctly.
66 * Called to write current preferences state to a file.
68 * @param aFile The file to be written.
71 * If nullptr is passed in for the aFile parameter the preference data is
72 * written out to the current preferences file (usually prefs.js.)
74 * @throws Error File failed to write.
76 * @see readUserPrefsFromFile
79 void savePrefFile
(in nsIFile aFile
);
82 * Called to write current preferences state to a file off of the main thread.
83 * This differs from savePrefFile in that null is not accepted for the aFile
84 * parameter, and aFile cannot be pointing at the current preferences file.
86 * The backup will be written to disk off of the main thread, unless the
87 * preferences service is not configured to write to disk off of the main
90 * @param aFile The file to be written.
91 * @returns A DOM promise that resolves when the backup is complete.
93 * @see readUserPrefsFromFile
97 Promise backupPrefFile
(in nsIFile aFile
);
100 * Call to get a Preferences "Branch" which accesses user preference data.
101 * Using a Set method on this object will always create or set a user
102 * preference value. When using a Get method a user set value will be
103 * returned if one exists, otherwise a default value will be returned.
105 * @param aPrefRoot The preference "root" on which to base this "branch".
106 * For example, if the root "browser.startup." is used, the
107 * branch will be able to easily access the preferences
108 * "browser.startup.page", "browser.startup.homepage", or
109 * "browser.startup.homepage_override" by simply requesting
110 * "page", "homepage", or "homepage_override". nullptr or ""
111 * may be used to access to the entire preference "tree".
113 * @return nsIPrefBranch The object representing the requested branch.
115 * @see getDefaultBranch
117 nsIPrefBranch getBranch
(in string aPrefRoot
);
120 * Call to get a Preferences "Branch" which accesses only the default
121 * preference data. Using a Set method on this object will always create or
122 * set a default preference value. When using a Get method a default value
123 * will always be returned.
125 * @param aPrefRoot The preference "root" on which to base this "branch".
126 * For example, if the root "browser.startup." is used, the
127 * branch will be able to easily access the preferences
128 * "browser.startup.page", "browser.startup.homepage", or
129 * "browser.startup.homepage_override" by simply requesting
130 * "page", "homepage", or "homepage_override". nullptr or ""
131 * may be used to access to the entire preference "tree".
134 * Few consumers will want to create default branch objects. Many of the
135 * branch methods do nothing on a default branch because the operations only
136 * make sense when applied to user set preferences.
138 * @return nsIPrefBranch The object representing the requested default branch.
142 nsIPrefBranch getDefaultBranch
(in string aPrefRoot
);
145 * The preference service is 'dirty' if there are changes to user preferences
146 * that have not been written to disk
148 readonly attribute
boolean dirty
;
151 * Read in the preferences specified in a default preference file. This
152 * method does not clear preferences that were already set, but it may
153 * overwrite existing preferences.
155 * @param aFile The file to be read.
157 * @throws Error File failed to read or contained invalid data.
158 * @note This method is intended for internal unit testing only!
160 void readDefaultPrefsFromFile
(in nsIFile aFile
);
163 * Like readDefaultPrefsFromFile, but for a user prefs file.
165 void readUserPrefsFromFile
(in nsIFile aFile
);
168 * Usage statistics for performance tests. This function takes a function
169 * that is passed (preferenceName, accessCount) as arguments for every
170 * recorded preference. You can use this function to build e.g. a JS object
173 * This is not implemented in non-debug builds and will throw an error.
175 void readStats
(in nsIPrefStatsCallback
callback);
178 * Reset usage statistics for performance tests.
180 * This is not implemented in non-debug builds and will throw an error.
185 * Parse the given bytes, invoking callbacks on the given observer.
187 * This method does not modify any preferences.
189 * @param bytes The data to parse. This data may be UTF-8 encoded, but is not
190 * required to be so: the prefs parser will determine the encoding
192 * @param observer The observer to invoke callbacks on. Parsing errors will
193 * be reported via the onError callback.
194 * @param pathLabel An optional string with which to label errors.
196 void parsePrefsFromBuffer
(in Array
<uint8_t
> bytes
,
197 in nsIPrefObserver observer
,
198 [optional] in string pathLabel
);
201 * Last modified time of the user pref file when initially read, in
202 * milliseconds. Can be 0 (unix epoch) if the file didn't exist when we
205 readonly attribute PRTime userPrefsFileLastModifiedAtStartup
;
210 #define NS_PREFSERVICE_CID \
211 { /* {1cd91b88-1dd2-11b2-92e1-ed22ed298000} */ \
215 { 0x9d, 0xf8, 0x75, 0xb4, 0x0e, 0xa4, 0x01, 0x56 } \
218 #define NS_PREFSERVICE_CONTRACTID
"@mozilla.org/preferences-service;1"
221 * Notification sent before reading the default user preferences files.
223 #define NS_PREFSERVICE_READ_TOPIC_ID
"prefservice:before-read-userprefs"
226 * Notification sent when after reading app-provided default
227 * preferences, but before user profile override defaults are loaded.
229 #define NS_PREFSERVICE_APPDEFAULTS_TOPIC_ID
"prefservice:after-app-defaults"