modules/libpref/public/nsIPref.idl

   1 /* -*- Mode: C++; 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.org 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  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 interface nsILocalFile;
  41 interface nsIObserver;
  42 interface nsIFileSpec;
  43
  44 #include "nsIPrefService.idl"
  45 #include "nsIPrefBranch.idl"
  46
  47 %{C++
  48
  49 #ifndef have_PrefChangedFunc_typedef
  50 typedef int (*PR_CALLBACK PrefChangedFunc)(const char *, void *);
  51 #define have_PrefChangedFunc_typedef
  52 #endif
  53 typedef void (*PrefEnumerationFunc)(const char *, void *);
  54
  55 #define NS_PREF_CID                                    \
  56   { /* {dc26e0e0-ca94-11d1-a9a4-00805f8a7ac4} */       \
  57     0xdc26e0e0,                                        \
  58     0xca94,                                            \
  59     0x11d1,                                            \
  60     { 0xa9, 0xa4, 0x00, 0x80, 0x5f, 0x8a, 0x7a, 0xc4 } \
  61   }
  62
  63 #define NS_PREF_CONTRACTID \
  64   "@mozilla.org/preferences;1"
  65
  66 #define NS_PREF_CLASSNAME "Preferences Service"
  67
  68 #define NS_PREF_VALUE_CHANGED 1
  69 %}
  70 native PrefChangedFunc(PrefChangedFunc);
  71 native PrefEnumerationFunc(PrefEnumerationFunc);
  72
  73 /**
  74  * This entire interface is deprecated and should not be used.
  75  * See nsIPrefService and nsIPrefBranch for the new implementations.
  76  *
  77  * @status DEPRECATED  Replaced by nsIPrefService and nsIPrefBranch
  78  */
  79 [scriptable, uuid(a22ad7b0-ca86-11d1-a9a4-00805f8a7ac4)]
  80 interface nsIPref : nsISupports {
  81
  82   /*
  83    * These are the the Prefs Service methods we will support for now
  84    */
  85
  86   /*
  87    * readUserPrefs
  88    *
  89    * read a user preference file, pass in null for default file
  90    */
  91   void readUserPrefs(in nsIFile aFile);
  92
  93   /*
  94    * resetPrefs
  95    *
  96    * completely flush and reload the preferences system
  97    */
  98   void ResetPrefs();
  99
 100   /*
 101    * resetUserPrefs
 102    *
 103    * flush all current user prefrences (reset all preferences to the default values)
 104    */
 105   void ResetUserPrefs();
 106
 107   /*
 108    * savePrefFile
 109    *
 110    * write current preferences state to a file, pass in null for default file
 111    */
 112   void savePrefFile(in nsIFile aFile);
 113
 114   /*
 115    * branch operations
 116    */
 117
 118   nsIPrefBranch getBranch(in string aPrefRoot);
 119   nsIPrefBranch getDefaultBranch(in string aPrefRoot);
 120
 121
 122   /*
 123    * These are the the Prefs Branch methods we will support for now
 124    */
 125
 126   const long ePrefInvalid = 0;
 127   const long ePrefLocked = 1;
 128   const long ePrefUserset = 2;
 129   const long ePrefConfig = 4;
 130   const long ePrefRemote = 8;
 131   const long ePrefLilocal = 16;
 132   const long ePrefString = 32;
 133   const long ePrefInt = 64;
 134   const long ePrefBool = 128;
 135   const long ePrefValuetypeMask = (ePrefString | ePrefInt | ePrefBool);
 136
 137   /*
 138    * the root of this branch, such as "browser."
 139    */
 140   readonly attribute string root;
 141
 142   /*
 143    * standard methods for accessing preferences
 144    */
 145   long    GetPrefType(in string aPrefName);
 146
 147   boolean GetBoolPref(in string aPrefName);
 148   void    SetBoolPref(in string aPrefName, in long aValue);
 149
 150   string  GetCharPref(in string aPrefName);
 151   void    SetCharPref(in string aPrefName, in string aValue);
 152
 153   long    GetIntPref(in string aPrefName);
 154   void    SetIntPref(in string aPrefName, in long aValue);
 155
 156   /*
 157    * methods for accessing complex preferences (i.e. items beyond the simple bool, char, and int)
 158    */
 159   void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue);
 160   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
 161
 162   /*
 163    * methods for preference state manipulation
 164    */
 165   void    ClearUserPref(in string aPrefName);
 166   boolean PrefIsLocked(in string aPrefName);
 167   void    lockPref(in string aPrefName);
 168   void    unlockPref(in string aPrefName);
 169
 170
 171   /*
 172    * branch-level operations
 173    */
 174
 175   /*
 176    * resetBranch
 177    *
 178    * clears all user preferences starting at the given preference prefix
 179    * pass in null or "" to clear this branch
 180    */
 181   void resetBranch(in string aStartingAt);
 182
 183   /*
 184    * deleteBranch
 185    *
 186    * removes all preferences starting at the given preference prefix
 187    * pass in null or "" to remove this branch
 188    */
 189   void DeleteBranch(in string aStartingAt);
 190
 191   /*
 192    * getChildList
 193    *
 194    * Returns an array of strings representing the child preferences of the branch root
 195    *
 196    * @param startingAt pass in null or "" to enumerate the entire branch
 197    * @param count Receives the number of elements in the array.
 198    * @param childArray Receives the array of child preferences.
 199    */
 200   void getChildList(in string aStartingAt,
 201                     out unsigned long aCount,
 202                     [array, size_is(aCount), retval] out string aChildArray);
 203
 204
 205   /*
 206    * Listeners
 207    */
 208
 209   /*
 210    * The observers have their |Observe| methods called with
 211    * ([the observer], "nsPref:changed", [pref name]).
 212    */
 213   void addObserver(in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak);
 214   void removeObserver(in string aDomain, in nsIObserver aObserver);
 215
 216
 217   /*
 218    * Finally some deprecated methods
 219    */
 220
 221
 222   // these are changing from Copy->get
 223   string CopyCharPref(in string pref);
 224   string CopyDefaultCharPref(in string pref);
 225
 226   /* get & set defaults */
 227   boolean GetDefaultBoolPref(in string pref);
 228   long    GetDefaultIntPref(in string pref);
 229
 230   void SetDefaultBoolPref(in string pref, in boolean value);
 231   void SetDefaultCharPref(in string pref, in string value);
 232   void SetDefaultIntPref(in string pref, in long value);
 233
 234   /* unichar & localized unichar prefs */
 235   wstring CopyUnicharPref(in string pref);
 236   wstring CopyDefaultUnicharPref(in string pref);
 237   void SetUnicharPref(in string pref, in wstring value);
 238   void SetDefaultUnicharPref(in string pref, in wstring value);
 239   wstring getLocalizedUnicharPref(in string pref);
 240   wstring getDefaultLocalizedUnicharPref(in string pref);
 241
 242   /* file & filespec prefs */
 243   nsIFileSpec  GetFilePref(in string pref);
 244   void         SetFilePref(in string pref, in nsIFileSpec value, in boolean setDefault);
 245   nsILocalFile getFileXPref(in string pref);
 246   void         setFileXPref(in string pref, in nsILocalFile value);
 247
 248   /* callbacks */
 249   [noscript] void RegisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
 250   [noscript] void UnregisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
 251
 252   /**
 253    * EnumerateChildren
 254    *
 255    * Call back function "callback" with every preference string
 256    * having prefix "parent". Pass "data" to "callback" when calling.
 257    *
 258    * @param parent A string representation of a prefix of preferences
 259    * @param callback A function to call back for each matching preference
 260    * @param data A piece of data to pass on to the callback
 261    */
 262   [noscript] void EnumerateChildren(in string parent, in PrefEnumerationFunc callback, in voidPtr data);
 263 };