modules/libpref/prefapi.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7 // <pre>
   8 */
   9 #ifndef PREFAPI_H
  10 #define PREFAPI_H
  11
  12 #include "nscore.h"
  13 #include "pldhash.h"
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 // 1 MB should be enough for everyone.
  20 static const uint32_t MAX_PREF_LENGTH = 1 * 1024 * 1024;
  21 // Actually, 4kb should be enough for everyone.
  22 static const uint32_t MAX_ADVISABLE_PREF_LENGTH = 4 * 1024;
  23
  24 typedef union
  25 {
  26     char*       stringVal;
  27     int32_t     intVal;
  28     bool        boolVal;
  29 } PrefValue;
  30
  31 struct PrefHashEntry : PLDHashEntryHdr
  32 {
  33     const char *key;
  34     PrefValue defaultPref;
  35     PrefValue userPref;
  36     uint16_t  flags;
  37 };
  38
  39 /*
  40 // <font color=blue>
  41 // The Init function initializes the preference context and creates
  42 // the preference hashtable.
  43 // </font>
  44 */
  45 nsresult    PREF_Init();
  46
  47 /*
  48 // Cleanup should be called at program exit to free the
  49 // list of registered callbacks.
  50 */
  51 void        PREF_Cleanup();
  52 void        PREF_CleanupPrefs();
  53
  54 /*
  55 // <font color=blue>
  56 // Preference flags, including the native type of the preference
  57 // </font>
  58 */
  59
  60 typedef enum { PREF_INVALID = 0,
  61                PREF_LOCKED = 1, PREF_USERSET = 2, PREF_CONFIG = 4, PREF_REMOTE = 8,
  62                PREF_LILOCAL = 16, PREF_STRING = 32, PREF_INT = 64, PREF_BOOL = 128,
  63                PREF_HAS_DEFAULT = 256,
  64                PREF_VALUETYPE_MASK = (PREF_STRING | PREF_INT | PREF_BOOL)
  65              } PrefType;
  66
  67 /*
  68 // <font color=blue>
  69 // Set the various types of preferences.  These functions take a dotted
  70 // notation of the preference name (e.g. "browser.startup.homepage").
  71 // Note that this will cause the preference to be saved to the file if
  72 // it is different from the default.  In other words, these are used
  73 // to set the _user_ preferences.
  74 //
  75 // If set_default is set to true however, it sets the default value.
  76 // This will only affect the program behavior if the user does not have a value
  77 // saved over it for the particular preference.  In addition, these will never
  78 // be saved out to disk.
  79 //
  80 // Each set returns PREF_VALUECHANGED if the user value changed
  81 // (triggering a callback), or PREF_NOERROR if the value was unchanged.
  82 // </font>
  83 */
  84 nsresult PREF_SetCharPref(const char *pref,const char* value, bool set_default = false);
  85 nsresult PREF_SetIntPref(const char *pref,int32_t value, bool set_default = false);
  86 nsresult PREF_SetBoolPref(const char *pref,bool value, bool set_default = false);
  87
  88 bool     PREF_HasUserPref(const char* pref_name);
  89
  90 /*
  91 // <font color=blue>
  92 // Get the various types of preferences.  These functions take a dotted
  93 // notation of the preference name (e.g. "browser.startup.homepage")
  94 //
  95 // They also take a pointer to fill in with the return value and return an
  96 // error value.  At the moment, this is simply an int but it may
  97 // be converted to an enum once the global error strategy is worked out.
  98 //
  99 // They will perform conversion if the type doesn't match what was requested.
 100 // (if it is reasonably possible)
 101 // </font>
 102 */
 103 nsresult PREF_GetIntPref(const char *pref,
 104                            int32_t * return_int, bool get_default);
 105 nsresult PREF_GetBoolPref(const char *pref, bool * return_val, bool get_default);
 106 /*
 107 // <font color=blue>
 108 // These functions are similar to the above "Get" version with the significant
 109 // difference that the preference module will alloc the memory (e.g. XP_STRDUP) and
 110 // the caller will need to be responsible for freeing it...
 111 // </font>
 112 */
 113 nsresult PREF_CopyCharPref(const char *pref, char ** return_buf, bool get_default);
 114 /*
 115 // <font color=blue>
 116 // bool function that returns whether or not the preference is locked and therefore
 117 // cannot be changed.
 118 // </font>
 119 */
 120 bool PREF_PrefIsLocked(const char *pref_name);
 121
 122 /*
 123 // <font color=blue>
 124 // Function that sets whether or not the preference is locked and therefore
 125 // cannot be changed.
 126 // </font>
 127 */
 128 nsresult PREF_LockPref(const char *key, bool lockIt);
 129
 130 PrefType PREF_GetPrefType(const char *pref_name);
 131
 132 /*
 133  * Delete a branch of the tree
 134  */
 135 nsresult PREF_DeleteBranch(const char *branch_name);
 136
 137 /*
 138  * Clears the given pref (reverts it to its default value)
 139  */
 140 nsresult PREF_ClearUserPref(const char *pref_name);
 141
 142 /*
 143  * Clears all user prefs
 144  */
 145 nsresult PREF_ClearAllUserPrefs();
 146
 147
 148 /*
 149 // <font color=blue>
 150 // The callback function will get passed the pref_node which triggered the call
 151 // and the void * instance_data which was passed to the register callback function.
 152 // Return a non-zero result (nsresult) to pass an error up to the caller.
 153 // </font>
 154 */
 155 /* Temporarily conditionally compile PrefChangedFunc typedef.
 156 ** During migration from old libpref to nsIPref we need it in
 157 ** both header files.  Eventually prefapi.h will become a private
 158 ** file.  The two types need to be in sync for now.  Certain
 159 ** compilers were having problems with multiple definitions.
 160 */
 161 #ifndef have_PrefChangedFunc_typedef
 162 typedef void (*PrefChangedFunc) (const char *, void *);
 163 #define have_PrefChangedFunc_typedef
 164 #endif
 165
 166 /*
 167 // <font color=blue>
 168 // Register a callback.  This takes a node in the preference tree and will
 169 // call the callback function if anything below that node is modified.
 170 // Unregister returns PREF_NOERROR if a callback was found that
 171 // matched all the parameters; otherwise it returns PREF_ERROR.
 172 // </font>
 173 */
 174 void PREF_RegisterCallback( const char* domain,
 175                                                                 PrefChangedFunc callback, void* instance_data );
 176 nsresult PREF_UnregisterCallback( const char* domain,
 177                                                                 PrefChangedFunc callback, void* instance_data );
 178
 179 /*
 180  * Used by nsPrefService as the callback function of the 'pref' parser
 181  */
 182 void PREF_ReaderCallback( void *closure,
 183                           const char *pref,
 184                           PrefValue   value,
 185                           PrefType    type,
 186                           bool        isDefault);
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191 #endif