modules/libpref/public/nsIPrefBranch.idl

   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
  42 /**
  43  * The nsIPrefBranch interface is used to manipulate the preferences data. This
  44  * object may be obtained from the preferences service (nsIPrefService) and
  45  * used to get and set default and/or user preferences across the application.
  46  *
  47  * This object is created with a "root" value which describes the base point in
  48  * the preferences "tree" from which this "branch" stems. Preferences are
  49  * accessed off of this root by using just the final portion of the preference.
  50  * For example, if this object is created with the root "browser.startup.",
  51  * the preferences "browser.startup.page", "browser.startup.homepage",
  52  * and "browser.startup.homepage_override" can be accessed by simply passing
  53  * "page", "homepage", or "homepage_override" to the various Get/Set methods.
  54  *
  55  * @see nsIPrefService
  56  *
  57  * @status FROZEN
  58  */
  59
  60 [scriptable, uuid(56c35506-f14b-11d3-99d3-ddbfac2ccf65)]
  61 interface 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 long 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    *                    - nsIFileSpec (deprecated - to be removed eventually)
 174    * @param aValue    The XPCOM object into which to the complex preference
 175    *                  value should be retrieved.
 176    *
 177    * @return NS_OK The value was successfully retrieved.
 178    * @return Other The value does not exist or is the wrong type.
 179    *
 180    * @see setComplexValue
 181    */
 182   void getComplexValue(in string aPrefName, in nsIIDRef aType,
 183                        [iid_is(aType), retval] out nsQIResult aValue);
 184
 185   /**
 186    * Called to set the state of an individual complex preference. A complex
 187    * preference is a preference which represents an XPCOM object that can not
 188    * be easily represented using a standard boolean, integer or string value.
 189    *
 190    * @param aPrefName The complex preference to set the value of.
 191    * @param aType     The XPCOM interface that this complex preference
 192    *                  represents. Interfaces currently supported are:
 193    *                    - nsILocalFile
 194    *                    - nsISupportsString (UniChar)
 195    *                    - nsIPrefLocalizedString (Localized UniChar)
 196    *                    - nsIFileSpec (deprecated - to be removed eventually)
 197    * @param aValue    The XPCOM object from which to set the complex preference
 198    *                  value.
 199    *
 200    * @return NS_OK The value was successfully set.
 201    * @return Other The value was not set or is the wrong type.
 202    *
 203    * @see getComplexValue
 204    */
 205   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
 206
 207   /**
 208    * Called to clear a user set value from a specific preference. This will, in
 209    * effect, reset the value to the default value. If no default value exists
 210    * the preference will cease to exist.
 211    *
 212    * @param aPrefName The preference to be cleared.
 213    *
 214    * @note
 215    * This method does nothing if this object is a default branch.
 216    *
 217    * @return NS_OK The user preference was successfully cleared.
 218    * @return Other The preference does not exist or have a user set value.
 219    */
 220   void clearUserPref(in string aPrefName);
 221
 222   /**
 223    * Called to lock a specific preference. Locking a preference will cause the
 224    * preference service to always return the default value regardless of
 225    * whether there is a user set value or not.
 226    *
 227    * @param aPrefName The preference to be locked.
 228    *
 229    * @note
 230    * This method can be called on either a default or user branch but, in
 231    * effect, always operates on the default branch.
 232    *
 233    * @return NS_OK The preference was successfully locked.
 234    * @return Other The preference does not exist or an error occurred.
 235    *
 236    * @see unlockPref
 237    */
 238   void lockPref(in string aPrefName);
 239
 240   /**
 241    * Called to check if a specific preference has a user value associated to
 242    * it.
 243    *
 244    * @param aPrefName The preference to be tested.
 245    *
 246    * @note
 247    * This method can be called on either a default or user branch but, in
 248    * effect, always operates on the user branch.
 249    *
 250    * @note
 251    * If a preference was manually set to a value that equals the default value,
 252    * then the preference no longer has a user set value, i.e. it is
 253    * considered reset to its default value.
 254    * In particular, this method will return false for such a preference and
 255    * the preference will not be saved to a file by nsIPrefService.savePrefFile.
 256    *
 257    * @return boolean  true  The preference has a user set value.
 258    *                  false The preference only has a default value.
 259    */
 260   boolean prefHasUserValue(in string aPrefName);
 261
 262   /**
 263    * Called to check if a specific preference is locked. If a preference is
 264    * locked calling its Get method will always return the default value.
 265    *
 266    * @param aPrefName The preference to be tested.
 267    *
 268    * @note
 269    * This method can be called on either a default or user branch but, in
 270    * effect, always operates on the default branch.
 271    *
 272    * @return boolean  true  The preference is locked.
 273    *                  false The preference is not locked.
 274    *
 275    * @see lockPref
 276    * @see unlockPref
 277    */
 278   boolean prefIsLocked(in string aPrefName);
 279
 280   /**
 281    * Called to unlock a specific preference. Unlocking a previously locked
 282    * preference allows the preference service to once again return the user set
 283    * value of the preference.
 284    *
 285    * @param aPrefName The preference to be unlocked.
 286    *
 287    * @note
 288    * This method can be called on either a default or user branch but, in
 289    * effect, always operates on the default branch.
 290    *
 291    * @return NS_OK The preference was successfully unlocked.
 292    * @return Other The preference does not exist or an error occurred.
 293    *
 294    * @see lockPref
 295    */
 296   void    unlockPref(in string aPrefName);
 297
 298
 299   /**
 300    * Called to remove all of the preferences referenced by this branch.
 301    *
 302    * @param aStartingAt The point on the branch at which to start the deleting
 303    *                    preferences. Pass in "" to remove all preferences
 304    *                    referenced by this branch.
 305    *
 306    * @note
 307    * This method can be called on either a default or user branch but, in
 308    * effect, always operates on both.
 309    *
 310    * @return NS_OK The preference(s) were successfully removed.
 311    * @return Other The preference(s) do not exist or an error occurred.
 312    */
 313   void deleteBranch(in string aStartingAt);
 314
 315   /**
 316    * Returns an array of strings representing the child preferences of the
 317    * root of this branch.
 318    *
 319    * @param aStartingAt The point on the branch at which to start enumerating
 320    *                    the child preferences. Pass in "" to enumerate all
 321    *                    preferences referenced by this branch.
 322    * @param aCount      Receives the number of elements in the array.
 323    * @param aChildArray Receives the array of child preferences.
 324    *
 325    * @note
 326    * This method can be called on either a default or user branch but, in
 327    * effect, always operates on both.
 328    *
 329    * @return NS_OK The preference list was successfully retrieved.
 330    * @return Other The preference(s) do not exist or an error occurred.
 331    */
 332   void getChildList(in string aStartingAt, out unsigned long aCount,
 333                     [array, size_is(aCount), retval] out string aChildArray);
 334
 335   /**
 336    * Called to reset all of the preferences referenced by this branch to their
 337    * default values.
 338    *
 339    * @param aStartingAt The point on the branch at which to start the resetting
 340    *                    preferences to their default values. Pass in "" to
 341    *                    reset all preferences referenced by this branch.
 342    *
 343    * @note
 344    * This method can be called on either a default or user branch but, in
 345    * effect, always operates on the user branch.
 346    *
 347    * @return NS_OK The preference(s) were successfully reset.
 348    * @return Other The preference(s) do not exist or an error occurred.
 349    */
 350   void resetBranch(in string aStartingAt);
 351
 352 };
 353
 354
 355 %{C++
 356
 357 #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
 358 #define NS_PREFBRANCH_CLASSNAME "Preferences Branch"
 359
 360 %}