Back to index

lightning-sunbird  0.9+nobinonly
nsIPref.idl
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #include "nsISupports.idl"
00039 
00040 interface nsILocalFile;
00041 interface nsIObserver;
00042 interface nsIFileSpec;
00043 
00044 #include "nsIPrefService.idl"
00045 #include "nsIPrefBranch.idl"
00046 
00047 /*
00048  * This entire interface is deprecated and should not be used.
00049  * See nsIPrefService and nsIPrefBranch for the new implementations.
00050  */
00051 
00052 %{C++
00053 
00054 
00055 #ifndef have_PrefChangedFunc_typedef
00056 typedef int (*PR_CALLBACK PrefChangedFunc)(const char *, void *);
00057 #define have_PrefChangedFunc_typedef
00058 #endif
00059 typedef void (*PrefEnumerationFunc)(const char *, void *);
00060 
00061 #define NS_PREF_CID                                    \
00062   { /* {dc26e0e0-ca94-11d1-a9a4-00805f8a7ac4} */       \
00063     0xdc26e0e0,                                        \
00064     0xca94,                                            \
00065     0x11d1,                                            \
00066     { 0xa9, 0xa4, 0x00, 0x80, 0x5f, 0x8a, 0x7a, 0xc4 } \
00067   }
00068 
00069 #define NS_PREF_CONTRACTID \
00070   "@mozilla.org/preferences;1" 
00071 
00072 #define NS_PREF_CLASSNAME "Preferences Service"
00073  
00074 #define NS_PREF_VALUE_CHANGED 1 
00075 %}
00076 native PrefChangedFunc(PrefChangedFunc);
00077 native PrefEnumerationFunc(PrefEnumerationFunc);
00078 
00079 
00080 [scriptable, uuid(a22ad7b0-ca86-11d1-a9a4-00805f8a7ac4)]
00081 interface nsIPref : nsISupports {
00082 
00083   /*
00084    * These are the the Prefs Service methods we will support for now
00085    */
00086 
00087   /*
00088    * readUserPrefs
00089    * 
00090    * read a user preference file, pass in null for default file
00091    */
00092   void readUserPrefs(in nsIFile aFile);
00093 
00094   /*
00095    * resetPrefs
00096    * 
00097    * completely flush and reload the preferences system
00098    */
00099   void ResetPrefs();
00100 
00101   /*
00102    * resetUserPrefs
00103    * 
00104    * flush all current user prefrences (reset all preferences to the default values)
00105    */
00106   void ResetUserPrefs();
00107 
00108   /*
00109    * savePrefFile
00110    * 
00111    * write current preferences state to a file, pass in null for default file
00112    */
00113   void savePrefFile(in nsIFile aFile);
00114 
00115   /*
00116    * branch operations
00117    */
00118 
00119   nsIPrefBranch getBranch(in string aPrefRoot);
00120   nsIPrefBranch getDefaultBranch(in string aPrefRoot);
00121 
00122 
00123   /*
00124    * These are the the Prefs Branch methods we will support for now
00125    */
00126 
00127   const long ePrefInvalid = 0;
00128   const long ePrefLocked = 1;
00129   const long ePrefUserset = 2;
00130   const long ePrefConfig = 4;
00131   const long ePrefRemote = 8;
00132   const long ePrefLilocal = 16;
00133   const long ePrefString = 32;
00134   const long ePrefInt = 64;
00135   const long ePrefBool = 128;
00136   const long ePrefValuetypeMask = (ePrefString | ePrefInt | ePrefBool);
00137 
00138   /*
00139    * the root of this branch, such as "browser."
00140    */
00141   readonly attribute string root;
00142 
00143   /*
00144    * standard methods for accessing preferences
00145    */
00146   long    GetPrefType(in string aPrefName);
00147 
00148   boolean GetBoolPref(in string aPrefName);
00149   void    SetBoolPref(in string aPrefName, in long aValue);
00150 
00151   string  GetCharPref(in string aPrefName);
00152   void    SetCharPref(in string aPrefName, in string aValue);
00153 
00154   long    GetIntPref(in string aPrefName);
00155   void    SetIntPref(in string aPrefName, in long aValue);
00156 
00157   /*
00158    * methods for accessing complex preferences (i.e. items beyond the simple bool, char, and int)
00159    */
00160   void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue);
00161   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
00162 
00163   /*
00164    * methods for preference state manipulation
00165    */
00166   void    ClearUserPref(in string aPrefName);
00167   boolean PrefIsLocked(in string aPrefName);
00168   void    lockPref(in string aPrefName);
00169   void    unlockPref(in string aPrefName);
00170 
00171 
00172   /*
00173    * branch-level operations
00174    */
00175 
00176   /*
00177    * resetBranch
00178    * 
00179    * clears all user preferences starting at the given preference prefix
00180    * pass in null or "" to clear this branch
00181    */
00182   void resetBranch(in string aStartingAt);
00183 
00184   /*
00185    * deleteBranch
00186    * 
00187    * removes all preferences starting at the given preference prefix
00188    * pass in null or "" to remove this branch
00189    */
00190   void DeleteBranch(in string aStartingAt);
00191 
00192   /*
00193    * getChildList
00194    *
00195    * Returns an array of strings representing the child preferences of the branch root
00196    * 
00197    * @param startingAt pass in null or "" to enumerate the entire branch
00198    * @param count Receives the number of elements in the array.
00199    * @param childArray Receives the array of child preferences.
00200    */
00201   void getChildList(in string aStartingAt,
00202                     out unsigned long aCount,
00203                     [array, size_is(aCount), retval] out string aChildArray);
00204 
00205 
00206   /*
00207    * Listeners
00208    */
00209 
00210   /*
00211    * The observers have their |Observe| methods called with
00212    * ([the observer], "nsPref:changed", [pref name]).
00213    */
00214   void addObserver(in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak);
00215   void removeObserver(in string aDomain, in nsIObserver aObserver);
00216 
00217 
00218   /*
00219    * Finally some deprecated methods
00220    */
00221 
00222   
00223   // these are changing from Copy->get
00224   string CopyCharPref(in string pref);
00225   string CopyDefaultCharPref(in string pref);
00226 
00227   /* get & set defaults */
00228   boolean GetDefaultBoolPref(in string pref);
00229   long    GetDefaultIntPref(in string pref);
00230 
00231   void SetDefaultBoolPref(in string pref, in boolean value);
00232   void SetDefaultCharPref(in string pref, in string value);
00233   void SetDefaultIntPref(in string pref, in long value);
00234 
00235   /* unichar & localized unichar prefs */
00236   wstring CopyUnicharPref(in string pref);
00237   wstring CopyDefaultUnicharPref(in string pref);
00238   void SetUnicharPref(in string pref, in wstring value);
00239   void SetDefaultUnicharPref(in string pref, in wstring value);
00240   wstring getLocalizedUnicharPref(in string pref);
00241   wstring getDefaultLocalizedUnicharPref(in string pref);
00242 
00243   /* file & filespec prefs */
00244   nsIFileSpec  GetFilePref(in string pref);
00245   void         SetFilePref(in string pref, in nsIFileSpec value, in boolean setDefault);
00246   nsILocalFile getFileXPref(in string pref);
00247   void         setFileXPref(in string pref, in nsILocalFile value);
00248 
00249   /* callbacks */
00250   [noscript] void RegisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
00251   [noscript] void UnregisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
00252 
00263   [noscript] void EnumerateChildren(in string parent, in PrefEnumerationFunc callback, in voidPtr data);
00264 };