/modules/libpref/public/nsIPrefBranch.idl
IDL | 440 lines | 39 code | 30 blank | 371 comment | 0 complexity | 3c6c0457fcaa20c3e7addc152c1ecbc2 MD5 | raw file
1/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is Mozilla Communicator client code. 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 1998 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * Alec Flett <alecf@netscape.com> 24 * Brian Nesse <bnesse@netscape.com> 25 * 26 * Alternatively, the contents of this file may be used under the terms of 27 * either the GNU General Public License Version 2 or later (the "GPL"), or 28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 29 * in which case the provisions of the GPL or the LGPL are applicable instead 30 * of those above. If you wish to allow use of your version of this file only 31 * under the terms of either the GPL or the LGPL, and not to allow others to 32 * use your version of this file under the terms of the MPL, indicate your 33 * decision by deleting the provisions above and replace them with the notice 34 * and other provisions required by the GPL or the LGPL. If you do not delete 35 * the provisions above, a recipient may use your version of this file under 36 * the terms of any one of the MPL, the GPL or the LGPL. 37 * 38 * ***** END LICENSE BLOCK ***** */ 39 40#include "nsISupports.idl" 41 42interface nsIObserver; 43 44/** 45 * The nsIPrefBranch interface is used to manipulate the preferences data. This 46 * object may be obtained from the preferences service (nsIPrefService) and 47 * used to get and set default and/or user preferences across the application. 48 * 49 * This object is created with a "root" value which describes the base point in 50 * the preferences "tree" from which this "branch" stems. Preferences are 51 * accessed off of this root by using just the final portion of the preference. 52 * For example, if this object is created with the root "browser.startup.", 53 * the preferences "browser.startup.page", "browser.startup.homepage", 54 * and "browser.startup.homepage_override" can be accessed by simply passing 55 * "page", "homepage", or "homepage_override" to the various Get/Set methods. 56 * 57 * @see nsIPrefService 58 */ 59 60[scriptable, uuid(7df46a54-d8b0-448e-903c-4341a1b2499c)] 61interface nsIPrefBranch : nsISupports 62{ 63 64 /** 65 * Values describing the basic preference types. 66 * 67 * @see getPrefType 68 */ 69 const long PREF_INVALID = 0; 70 const long PREF_STRING = 32; 71 const long PREF_INT = 64; 72 const long PREF_BOOL = 128; 73 74 /** 75 * Called to get the root on which this branch is based, such as 76 * "browser.startup." 77 */ 78 readonly attribute string root; 79 80 /** 81 * Called to determine the type of a specific preference. 82 * 83 * @param aPrefName The preference to get the type of. 84 * 85 * @return long A value representing the type of the preference. This 86 * value will be PREF_STRING, PREF_INT, or PREF_BOOL. 87 */ 88 long getPrefType(in string aPrefName); 89 90 /** 91 * Called to get the state of an individual boolean preference. 92 * 93 * @param aPrefName The boolean preference to get the state of. 94 * 95 * @return boolean The value of the requested boolean preference. 96 * 97 * @see setBoolPref 98 */ 99 boolean getBoolPref(in string aPrefName); 100 101 /** 102 * Called to set the state of an individual boolean preference. 103 * 104 * @param aPrefName The boolean preference to set the state of. 105 * @param aValue The boolean value to set the preference to. 106 * 107 * @return NS_OK The value was successfully set. 108 * @return Other The value was not set or is the wrong type. 109 * 110 * @see getBoolPref 111 */ 112 void setBoolPref(in string aPrefName, in boolean aValue); 113 114 /** 115 * Called to get the state of an individual string preference. 116 * 117 * @param aPrefName The string preference to retrieve. 118 * 119 * @return string The value of the requested string preference. 120 * 121 * @see setCharPref 122 */ 123 string getCharPref(in string aPrefName); 124 125 /** 126 * Called to set the state of an individual string preference. 127 * 128 * @param aPrefName The string preference to set. 129 * @param aValue The string value to set the preference to. 130 * 131 * @return NS_OK The value was successfully set. 132 * @return Other The value was not set or is the wrong type. 133 * 134 * @see getCharPref 135 */ 136 void setCharPref(in string aPrefName, in string aValue); 137 138 /** 139 * Called to get the state of an individual integer preference. 140 * 141 * @param aPrefName The integer preference to get the value of. 142 * 143 * @return long The value of the requested integer preference. 144 * 145 * @see setIntPref 146 */ 147 long getIntPref(in string aPrefName); 148 149 /** 150 * Called to set the state of an individual integer preference. 151 * 152 * @param aPrefName The integer preference to set the value of. 153 * @param aValue The integer value to set the preference to. 154 * 155 * @return NS_OK The value was successfully set. 156 * @return Other The value was not set or is the wrong type. 157 * 158 * @see getIntPref 159 */ 160 void setIntPref(in string aPrefName, in long aValue); 161 162 /** 163 * Called to get the state of an individual complex preference. A complex 164 * preference is a preference which represents an XPCOM object that can not 165 * be easily represented using a standard boolean, integer or string value. 166 * 167 * @param aPrefName The complex preference to get the value of. 168 * @param aType The XPCOM interface that this complex preference 169 * represents. Interfaces currently supported are: 170 * - nsILocalFile 171 * - nsISupportsString (UniChar) 172 * - nsIPrefLocalizedString (Localized UniChar) 173 * @param aValue The XPCOM object into which to the complex preference 174 * value should be retrieved. 175 * 176 * @return NS_OK The value was successfully retrieved. 177 * @return Other The value does not exist or is the wrong type. 178 * 179 * @see setComplexValue 180 */ 181 void getComplexValue(in string aPrefName, in nsIIDRef aType, 182 [iid_is(aType), retval] out nsQIResult aValue); 183 184 /** 185 * Called to set the state of an individual complex preference. A complex 186 * preference is a preference which represents an XPCOM object that can not 187 * be easily represented using a standard boolean, integer or string value. 188 * 189 * @param aPrefName The complex preference to set the value of. 190 * @param aType The XPCOM interface that this complex preference 191 * represents. Interfaces currently supported are: 192 * - nsILocalFile 193 * - nsISupportsString (UniChar) 194 * - nsIPrefLocalizedString (Localized UniChar) 195 * @param aValue The XPCOM object from which to set the complex preference 196 * value. 197 * 198 * @return NS_OK The value was successfully set. 199 * @return Other The value was not set or is the wrong type. 200 * 201 * @see getComplexValue 202 */ 203 void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue); 204 205 /** 206 * Called to clear a user set value from a specific preference. This will, in 207 * effect, reset the value to the default value. If no default value exists 208 * the preference will cease to exist. 209 * 210 * @param aPrefName The preference to be cleared. 211 * 212 * @note 213 * This method does nothing if this object is a default branch. 214 * 215 * @return NS_OK The user preference was successfully cleared. 216 */ 217 void clearUserPref(in string aPrefName); 218 219 /** 220 * Called to lock a specific preference. Locking a preference will cause the 221 * preference service to always return the default value regardless of 222 * whether there is a user set value or not. 223 * 224 * @param aPrefName The preference to be locked. 225 * 226 * @note 227 * This method can be called on either a default or user branch but, in 228 * effect, always operates on the default branch. 229 * 230 * @return NS_OK The preference was successfully locked. 231 * @return Other The preference does not exist or an error occurred. 232 * 233 * @see unlockPref 234 */ 235 void lockPref(in string aPrefName); 236 237 /** 238 * Called to check if a specific preference has a user value associated to 239 * it. 240 * 241 * @param aPrefName The preference to be tested. 242 * 243 * @note 244 * This method can be called on either a default or user branch but, in 245 * effect, always operates on the user branch. 246 * 247 * @note 248 * If a preference was manually set to a value that equals the default value, 249 * then the preference no longer has a user set value, i.e. it is 250 * considered reset to its default value. 251 * In particular, this method will return false for such a preference and 252 * the preference will not be saved to a file by nsIPrefService.savePrefFile. 253 * 254 * @return boolean true The preference has a user set value. 255 * false The preference only has a default value. 256 */ 257 boolean prefHasUserValue(in string aPrefName); 258 259 /** 260 * Called to check if a specific preference is locked. If a preference is 261 * locked calling its Get method will always return the default value. 262 * 263 * @param aPrefName The preference to be tested. 264 * 265 * @note 266 * This method can be called on either a default or user branch but, in 267 * effect, always operates on the default branch. 268 * 269 * @return boolean true The preference is locked. 270 * false The preference is not locked. 271 * 272 * @see lockPref 273 * @see unlockPref 274 */ 275 boolean prefIsLocked(in string aPrefName); 276 277 /** 278 * Called to unlock a specific preference. Unlocking a previously locked 279 * preference allows the preference service to once again return the user set 280 * value of the preference. 281 * 282 * @param aPrefName The preference to be unlocked. 283 * 284 * @note 285 * This method can be called on either a default or user branch but, in 286 * effect, always operates on the default branch. 287 * 288 * @return NS_OK The preference was successfully unlocked. 289 * @return Other The preference does not exist or an error occurred. 290 * 291 * @see lockPref 292 */ 293 void unlockPref(in string aPrefName); 294 295 296 /** 297 * Called to remove all of the preferences referenced by this branch. 298 * 299 * @param aStartingAt The point on the branch at which to start the deleting 300 * preferences. Pass in "" to remove all preferences 301 * referenced by this branch. 302 * 303 * @note 304 * This method can be called on either a default or user branch but, in 305 * effect, always operates on both. 306 * 307 * @return NS_OK The preference(s) were successfully removed. 308 * @return Other The preference(s) do not exist or an error occurred. 309 */ 310 void deleteBranch(in string aStartingAt); 311 312 /** 313 * Returns an array of strings representing the child preferences of the 314 * root of this branch. 315 * 316 * @param aStartingAt The point on the branch at which to start enumerating 317 * the child preferences. Pass in "" to enumerate all 318 * preferences referenced by this branch. 319 * @param aCount Receives the number of elements in the array. 320 * @param aChildArray Receives the array of child preferences. 321 * 322 * @note 323 * This method can be called on either a default or user branch but, in 324 * effect, always operates on both. 325 * 326 * @return NS_OK The preference list was successfully retrieved. 327 * @return Other The preference(s) do not exist or an error occurred. 328 */ 329 void getChildList(in string aStartingAt, 330 [optional] out unsigned long aCount, 331 [array, size_is(aCount), retval] out string aChildArray); 332 333 /** 334 * Called to reset all of the preferences referenced by this branch to their 335 * default values. 336 * 337 * @param aStartingAt The point on the branch at which to start the resetting 338 * preferences to their default values. Pass in "" to 339 * reset all preferences referenced by this branch. 340 * 341 * @note 342 * This method can be called on either a default or user branch but, in 343 * effect, always operates on the user branch. 344 * 345 * @return NS_OK The preference(s) were successfully reset. 346 * @return Other The preference(s) do not exist or an error occurred. 347 */ 348 void resetBranch(in string aStartingAt); 349 350 /** 351 * Add a preference change observer. On preference changes, the following 352 * arguments will be passed to the nsIObserver.observe() method: 353 * aSubject - The nsIPrefBranch object (this) 354 * aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID 355 * aData - The name of the preference which has changed, relative to 356 * the |root| of the aSubject branch. 357 * 358 * aSubject.get*Pref(aData) will get the new value of the modified 359 * preference. For example, if your observer is registered with 360 * addObserver("bar.", ...) on a branch with root "foo.", modifying 361 * the preference "foo.bar.baz" will trigger the observer, and aData 362 * parameter will be "bar.baz". 363 * 364 * @param aDomain The preference on which to listen for changes. This can 365 * be the name of an entire branch to observe. 366 * e.g. Holding the "root" prefbranch and calling 367 * addObserver("foo.bar.", ...) will observe changes to 368 * foo.bar.baz and foo.bar.bzip 369 * @param aObserver The object to be notified if the preference changes. 370 * @param aHoldWeak true Hold a weak reference to |aObserver|. The object 371 * must implement the nsISupportsWeakReference 372 * interface or this will fail. 373 * false Hold a strong reference to |aObserver|. 374 * 375 * @note 376 * Registering as a preference observer can open an object to potential 377 * cyclical references which will cause memory leaks. These cycles generally 378 * occur because an object both registers itself as an observer (causing the 379 * branch to hold a reference to the observer) and holds a reference to the 380 * branch object for the purpose of getting/setting preference values. There 381 * are 3 approaches which have been implemented in an attempt to avoid these 382 * situations. 383 * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer 384 * may hold a weak reference to it instead of a strong one. 385 * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the 386 * objects currently in its observer list. This ensures that long lived 387 * objects (services for example) will be freed correctly. 388 * 3) The observer can request to be held as a weak reference when it is 389 * registered. This insures that shorter lived objects (say one tied to an 390 * open window) will not fall into the cyclical reference trap. 391 * 392 * @note 393 * The list of registered observers may be changed during the dispatch of 394 * nsPref:changed notification. However, the observers are not guaranteed 395 * to be notified in any particular order, so you can't be sure whether the 396 * added/removed observer will be called during the notification when it 397 * is added/removed. 398 * 399 * @note 400 * It is possible to change preferences during the notification. 401 * 402 * @note 403 * It is not safe to change observers during this callback in Gecko 404 * releases before 1.9. If you want a safe way to remove a pref observer, 405 * please use an nsITimer. 406 * 407 * @see nsIObserver 408 * @see removeObserver 409 */ 410 void addObserver(in string aDomain, in nsIObserver aObserver, 411 in boolean aHoldWeak); 412 413 /** 414 * Remove a preference change observer. 415 * 416 * @param aDomain The preference which is being observed for changes. 417 * @param aObserver An observer previously registered with addObserver(). 418 * 419 * @note 420 * Note that you must call removeObserver() on the same nsIPrefBranch 421 * instance on which you called addObserver() in order to remove aObserver; 422 * otherwise, the observer will not be removed. 423 * 424 * @see nsIObserver 425 * @see addObserver 426 */ 427 void removeObserver(in string aDomain, in nsIObserver aObserver); 428}; 429 430 431%{C++ 432 433#define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1" 434#define NS_PREFBRANCH_CLASSNAME "Preferences Branch" 435/** 436 * Notification sent when a preference changes. 437 */ 438#define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed" 439 440%}