nsIPrefService.idl (8822B)
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/. */ 5 6 #include "nsISupports.idl" 7 #include "nsIPrefBranch.idl" 8 9 interface nsIFile; 10 interface nsIPrefOverrideMap; 11 12 /** 13 * A helper function for reading access statistics for preferences. 14 * See nsIPrefService.readStats for more details. 15 */ 16 [function, scriptable, uuid(c3f0cedc-e244-4316-b33a-80306a1c35a1)] 17 interface nsIPrefStatsCallback : nsISupports 18 { 19 void visit(in ACString prefName, in unsigned long accessCount); 20 }; 21 22 [scriptable, uuid(0a2dbc02-2218-4687-b151-33d890676e00)] 23 interface nsIPrefObserver : nsISupports 24 { 25 /** 26 * Invoked when a string preference is witnessed. kind will be "Default" or "User". 27 */ 28 void onStringPref(in string kind, in string name, in string value, in boolean isSticky, in boolean isLocked); 29 30 /** 31 * Invoked when a integer preference is witnessed. kind will be "Default" or "User". 32 */ 33 void onIntPref(in string kind, in string name, in long value, in boolean isSticky, in boolean isLocked); 34 35 /** 36 * Invoked when a boolean preference is witnessed. kind will be "Default" or "User". 37 */ 38 void onBoolPref(in string kind, in string name, in boolean value, in boolean isSticky, in boolean isLocked); 39 40 /** 41 * Invoked when the prefs parser encounters an error. 42 */ 43 void onError(in string message); 44 }; 45 46 /** 47 * The nsIPrefService interface is the main entry point into the back end 48 * preferences management library. The preference service is directly 49 * responsible for the management of the preferences files and also facilitates 50 * access to the preference branch object which allows the direct manipulation 51 * of the preferences themselves. 52 * 53 * @see nsIPrefBranch 54 */ 55 56 [scriptable, uuid(1f84fd56-3956-40df-b86a-1ea01402ee96)] 57 interface nsIPrefService : nsISupports 58 { 59 /** 60 * Called to completely flush and re-initialize the preferences system. 61 * 62 * @throws Error The preference service failed to restart correctly. 63 */ 64 void resetPrefs(); 65 66 /** 67 * Called to write current preferences state to a file. 68 * 69 * @param aFile The file to be written. 70 * 71 * @note 72 * If nullptr is passed in for the aFile parameter the preference data is 73 * written out to the current preferences file (usually prefs.js.) 74 * 75 * @throws Error File failed to write. 76 * 77 * @see readUserPrefsFromFile 78 * @see nsIFile 79 */ 80 void savePrefFile(in nsIFile aFile); 81 82 /** 83 * Called to write current preferences state to a file off of the main thread. 84 * This differs from savePrefFile in that null is not accepted for the aFile 85 * parameter, and aFile cannot be pointing at the current preferences file. 86 * 87 * The backup will be written to disk off of the main thread, unless the 88 * preferences service is not configured to write to disk off of the main 89 * thread. 90 * 91 * @param aFile The file to be written. 92 * @param aOverrideMap Map of pref names to values that will "override" 93 * current pref values in the backup. 94 * @returns A DOM promise that resolves when the backup is complete. 95 * 96 * @see readUserPrefsFromFile 97 * @see nsIFile 98 */ 99 [implicit_jscontext] 100 Promise backupPrefFile( 101 in nsIFile aFile, 102 [optional] in nsIPrefOverrideMap aOverrideMap); 103 104 /** 105 * Call to get a Preferences "Branch" which accesses user preference data. 106 * Using a Set method on this object will always create or set a user 107 * preference value. When using a Get method a user set value will be 108 * returned if one exists, otherwise a default value will be returned. 109 * 110 * @param aPrefRoot The preference "root" on which to base this "branch". 111 * For example, if the root "browser.startup." is used, the 112 * branch will be able to easily access the preferences 113 * "browser.startup.page", "browser.startup.homepage", or 114 * "browser.startup.homepage_override" by simply requesting 115 * "page", "homepage", or "homepage_override". nullptr or "" 116 * may be used to access to the entire preference "tree". 117 * 118 * @return nsIPrefBranch The object representing the requested branch. 119 * 120 * @see getDefaultBranch 121 */ 122 nsIPrefBranch getBranch(in string aPrefRoot); 123 124 /** 125 * Call to get a Preferences "Branch" which accesses only the default 126 * preference data. Using a Set method on this object will always create or 127 * set a default preference value. When using a Get method a default value 128 * will always be returned. 129 * 130 * @param aPrefRoot The preference "root" on which to base this "branch". 131 * For example, if the root "browser.startup." is used, the 132 * branch will be able to easily access the preferences 133 * "browser.startup.page", "browser.startup.homepage", or 134 * "browser.startup.homepage_override" by simply requesting 135 * "page", "homepage", or "homepage_override". nullptr or "" 136 * may be used to access to the entire preference "tree". 137 * 138 * @note 139 * Few consumers will want to create default branch objects. Many of the 140 * branch methods do nothing on a default branch because the operations only 141 * make sense when applied to user set preferences. 142 * 143 * @return nsIPrefBranch The object representing the requested default branch. 144 * 145 * @see getBranch 146 */ 147 nsIPrefBranch getDefaultBranch(in string aPrefRoot); 148 149 /** 150 * The preference service is 'dirty' if there are changes to user preferences 151 * that have not been written to disk 152 */ 153 readonly attribute boolean dirty; 154 155 /** 156 * Read in the preferences specified in a default preference file. This 157 * method does not clear preferences that were already set, but it may 158 * overwrite existing preferences. 159 * 160 * @param aFile The file to be read. 161 * 162 * @throws Error File failed to read or contained invalid data. 163 * @note This method is intended for internal unit testing only! 164 */ 165 void readDefaultPrefsFromFile(in nsIFile aFile); 166 167 /** 168 * Like readDefaultPrefsFromFile, but for a user prefs file. 169 */ 170 void readUserPrefsFromFile(in nsIFile aFile); 171 172 /** 173 * Usage statistics for performance tests. This function takes a function 174 * that is passed (preferenceName, accessCount) as arguments for every 175 * recorded preference. You can use this function to build e.g. a JS object 176 * holding that data. 177 * 178 * This is not implemented in non-debug builds and will throw an error. 179 */ 180 void readStats(in nsIPrefStatsCallback callback); 181 182 /** 183 * Reset usage statistics for performance tests. 184 * 185 * This is not implemented in non-debug builds and will throw an error. 186 */ 187 void resetStats(); 188 189 /** 190 * Parse the given bytes, invoking callbacks on the given observer. 191 * 192 * This method does not modify any preferences. 193 * 194 * @param bytes The data to parse. This data may be UTF-8 encoded, but is not 195 * required to be so: the prefs parser will determine the encoding 196 * automatically. 197 * @param observer The observer to invoke callbacks on. Parsing errors will 198 * be reported via the onError callback. 199 * @param pathLabel An optional string with which to label errors. 200 */ 201 void parsePrefsFromBuffer(in Array<uint8_t> bytes, 202 in nsIPrefObserver observer, 203 [optional] in string pathLabel); 204 205 /** 206 * Last modified time of the user pref file when initially read, in 207 * milliseconds. Can be 0 (unix epoch) if the file didn't exist when we 208 * started. 209 */ 210 readonly attribute PRTime userPrefsFileLastModifiedAtStartup; 211 212 /** 213 * The preamble text for prefs.js. 214 */ 215 readonly attribute ACString prefsJsPreamble; 216 }; 217 218 %{C++ 219 220 #define NS_PREFSERVICE_CID \ 221 { /* {1cd91b88-1dd2-11b2-92e1-ed22ed298000} */ \ 222 0x91ca2441, \ 223 0x050f, \ 224 0x4f7c, \ 225 { 0x9d, 0xf8, 0x75, 0xb4, 0x0e, 0xa4, 0x01, 0x56 } \ 226 } 227 228 #define NS_PREFSERVICE_CONTRACTID "@mozilla.org/preferences-service;1" 229 230 /** 231 * Notification sent before reading the default user preferences files. 232 */ 233 #define NS_PREFSERVICE_READ_TOPIC_ID "prefservice:before-read-userprefs" 234 235 /** 236 * Notification sent when after reading app-provided default 237 * preferences, but before user profile override defaults are loaded. 238 */ 239 #define NS_PREFSERVICE_APPDEFAULTS_TOPIC_ID "prefservice:after-app-defaults" 240 241 %}