Back to index

lightning-sunbird  0.9+nobinonly
prefapi.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 4; 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 /*
00039 // <pre>
00040 */
00041 #ifndef PREFAPI_H
00042 #define PREFAPI_H
00043 
00044 #include "nscore.h"
00045 #include "pldhash.h"
00046 
00047 NSPR_BEGIN_EXTERN_C
00048 
00049 typedef union
00050 {
00051     char*       stringVal;
00052     PRInt32     intVal;
00053     PRBool      boolVal;
00054 } PrefValue;
00055 
00056 struct PrefHashEntry : PLDHashEntryHdr
00057 {
00058     const char *key;
00059     PrefValue defaultPref;
00060     PrefValue userPref;
00061     PRUint8   flags;
00062 };
00063 
00064 /*
00065 // <font color=blue>
00066 // The Init function initializes the preference context and creates
00067 // the preference hashtable.
00068 // </font>
00069 */
00070 nsresult    PREF_Init();
00071 
00072 /*
00073 // Cleanup should be called at program exit to free the 
00074 // list of registered callbacks.
00075 */
00076 void        PREF_Cleanup();
00077 void        PREF_CleanupPrefs();
00078 
00079 /*
00080 // <font color=blue>
00081 // Preference flags, including the native type of the preference
00082 // </font>
00083 */
00084 
00085 typedef enum { PREF_INVALID = 0,
00086                PREF_LOCKED = 1, PREF_USERSET = 2, PREF_CONFIG = 4, PREF_REMOTE = 8,
00087                         PREF_LILOCAL = 16, PREF_STRING = 32, PREF_INT = 64, PREF_BOOL = 128,
00088                         PREF_VALUETYPE_MASK = (PREF_STRING | PREF_INT | PREF_BOOL)
00089                        } PrefType;
00090 
00091 /*
00092 // <font color=blue>
00093 // Set the various types of preferences.  These functions take a dotted
00094 // notation of the preference name (e.g. "browser.startup.homepage").  
00095 // Note that this will cause the preference to be saved to the file if
00096 // it is different from the default.  In other words, these are used
00097 // to set the _user_ preferences.
00098 //
00099 // If set_default is set to PR_TRUE however, it sets the default value.
00100 // This will only affect the program behavior if the user does not have a value
00101 // saved over it for the particular preference.  In addition, these will never
00102 // be saved out to disk.
00103 //
00104 // Each set returns PREF_VALUECHANGED if the user value changed
00105 // (triggering a callback), or PREF_NOERROR if the value was unchanged.
00106 // </font>
00107 */
00108 nsresult PREF_SetCharPref(const char *pref,const char* value, PRBool set_default = PR_FALSE);
00109 nsresult PREF_SetIntPref(const char *pref,PRInt32 value, PRBool set_default = PR_FALSE);
00110 nsresult PREF_SetBoolPref(const char *pref,PRBool value, PRBool set_default = PR_FALSE);
00111 
00112 PRBool   PREF_HasUserPref(const char* pref_name);
00113 
00114 /*
00115 // <font color=blue>
00116 // Get the various types of preferences.  These functions take a dotted
00117 // notation of the preference name (e.g. "browser.startup.homepage")
00118 //
00119 // They also take a pointer to fill in with the return value and return an
00120 // error value.  At the moment, this is simply an int but it may
00121 // be converted to an enum once the global error strategy is worked out.
00122 //
00123 // They will perform conversion if the type doesn't match what was requested.
00124 // (if it is reasonably possible)
00125 // </font>
00126 */
00127 nsresult PREF_GetIntPref(const char *pref,
00128                            PRInt32 * return_int, PRBool get_default); 
00129 nsresult PREF_GetBoolPref(const char *pref, PRBool * return_val, PRBool get_default);      
00130 /*
00131 // <font color=blue>
00132 // These functions are similar to the above "Get" version with the significant
00133 // difference that the preference module will alloc the memory (e.g. XP_STRDUP) and
00134 // the caller will need to be responsible for freeing it...
00135 // </font>
00136 */
00137 nsresult PREF_CopyCharPref(const char *pref, char ** return_buf, PRBool get_default);
00138 /*
00139 // <font color=blue>
00140 // PRBool function that returns whether or not the preference is locked and therefore
00141 // cannot be changed.
00142 // </font>
00143 */
00144 PRBool PREF_PrefIsLocked(const char *pref_name);
00145 
00146 /*
00147 // <font color=blue>
00148 // Function that sets whether or not the preference is locked and therefore
00149 // cannot be changed.
00150 // </font>
00151 */
00152 nsresult PREF_LockPref(const char *key, PRBool lockIt);
00153 
00154 PrefType PREF_GetPrefType(const char *pref_name);
00155 
00156 /*
00157  * Delete a branch of the tree
00158  */
00159 nsresult PREF_DeleteBranch(const char *branch_name);
00160 
00161 /*
00162  * Clears the given pref (reverts it to its default value)
00163  */
00164 nsresult PREF_ClearUserPref(const char *pref_name);
00165 
00166 /*
00167  * Clears all user prefs
00168  */
00169 nsresult PREF_ClearAllUserPrefs();
00170 
00171 
00172 /*
00173 // <font color=blue>
00174 // The callback function will get passed the pref_node which triggered the call
00175 // and the void * instance_data which was passed to the register callback function.
00176 // Return a non-zero result (nsresult) to pass an error up to the caller.
00177 // </font>
00178 */
00179 /* Temporarily conditionally compile PrefChangedFunc typedef.
00180 ** During migration from old libpref to nsIPref we need it in
00181 ** both header files.  Eventually prefapi.h will become a private
00182 ** file.  The two types need to be in sync for now.  Certain
00183 ** compilers were having problems with multiple definitions.
00184 */
00185 #ifndef have_PrefChangedFunc_typedef
00186 typedef nsresult (*PrefChangedFunc) (const char *, void *); 
00187 #define have_PrefChangedFunc_typedef
00188 #endif
00189 
00190 /*
00191 // <font color=blue>
00192 // Register a callback.  This takes a node in the preference tree and will
00193 // call the callback function if anything below that node is modified.
00194 // Unregister returns PREF_NOERROR if a callback was found that
00195 // matched all the parameters; otherwise it returns PREF_ERROR.
00196 // </font>
00197 */
00198 void PREF_RegisterCallback( const char* domain,
00199                                                         PrefChangedFunc callback, void* instance_data );
00200 nsresult PREF_UnregisterCallback( const char* domain,
00201                                                         PrefChangedFunc callback, void* instance_data );
00202 
00203 /*
00204  * Used by nsPrefService as the callback function of the 'pref' parser
00205  */
00206 void PREF_ReaderCallback( void *closure,
00207                           const char *pref,
00208                           PrefValue   value,
00209                           PrefType    type,
00210                           PRBool      isDefault);
00211 
00212 NSPR_END_EXTERN_C
00213 #endif