Line data Source code
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 "PLDHashTable.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 : /*
32 : // <font color=blue>
33 : // The Init function initializes the preference context and creates
34 : // the preference hashtable.
35 : // </font>
36 : */
37 : void PREF_Init();
38 :
39 : /*
40 : // Cleanup should be called at program exit to free the
41 : // list of registered callbacks.
42 : */
43 : void PREF_Cleanup();
44 : void PREF_CleanupPrefs();
45 :
46 : /*
47 : // <font color=blue>
48 : // Preference flags, including the native type of the preference. Changing any of these
49 : // values will require modifying the code inside of PrefTypeFlags class.
50 : // </font>
51 : */
52 :
53 : enum class PrefType {
54 : Invalid = 0,
55 : String = 1,
56 : Int = 2,
57 : Bool = 3,
58 : };
59 :
60 : // Keep the type of the preference, as well as the flags guiding its behaviour.
61 : class PrefTypeFlags
62 : {
63 : public:
64 : PrefTypeFlags() : mValue(AsInt(PrefType::Invalid)) {}
65 : explicit PrefTypeFlags(PrefType aType) : mValue(AsInt(aType)) {}
66 9126 : PrefTypeFlags& Reset() { mValue = AsInt(PrefType::Invalid); return *this; }
67 :
68 : bool IsTypeValid() const { return !IsPrefType(PrefType::Invalid); }
69 19817 : bool IsTypeString() const { return IsPrefType(PrefType::String); }
70 1230 : bool IsTypeInt() const { return IsPrefType(PrefType::Int); }
71 2343 : bool IsTypeBool() const { return IsPrefType(PrefType::Bool); }
72 30214 : bool IsPrefType(PrefType type) const { return GetPrefType() == type; }
73 :
74 18729 : PrefTypeFlags& SetPrefType(PrefType aType) {
75 18729 : mValue = mValue - AsInt(GetPrefType()) + AsInt(aType);
76 18729 : return *this;
77 : }
78 61747 : PrefType GetPrefType() const {
79 185241 : return (PrefType)(mValue & (AsInt(PrefType::String) |
80 123494 : AsInt(PrefType::Int) |
81 123494 : AsInt(PrefType::Bool)));
82 : }
83 :
84 26857 : bool HasDefault() const { return mValue & PREF_FLAG_HAS_DEFAULT; }
85 9083 : PrefTypeFlags& SetHasDefault(bool aSetOrUnset) { return SetFlag(PREF_FLAG_HAS_DEFAULT, aSetOrUnset); }
86 :
87 350 : bool HasStickyDefault() const { return mValue & PREF_FLAG_STICKY_DEFAULT; }
88 9 : PrefTypeFlags& SetHasStickyDefault(bool aSetOrUnset) { return SetFlag(PREF_FLAG_STICKY_DEFAULT, aSetOrUnset); }
89 :
90 19908 : bool IsLocked() const { return mValue & PREF_FLAG_LOCKED; }
91 0 : PrefTypeFlags& SetLocked(bool aSetOrUnset) { return SetFlag(PREF_FLAG_LOCKED, aSetOrUnset); }
92 :
93 30584 : bool HasUserValue() const { return mValue & PREF_FLAG_USERSET; }
94 520 : PrefTypeFlags& SetHasUserValue(bool aSetOrUnset) { return SetFlag(PREF_FLAG_USERSET, aSetOrUnset); }
95 :
96 : private:
97 231825 : static uint16_t AsInt(PrefType aType) { return (uint16_t)aType; }
98 :
99 9612 : PrefTypeFlags& SetFlag(uint16_t aFlag, bool aSetOrUnset) {
100 9612 : mValue = aSetOrUnset ? mValue | aFlag : mValue & ~aFlag;
101 9612 : return *this;
102 : }
103 :
104 : // Pack both the value of type (PrefType) and flags into the same int. This is why
105 : // the flag enum starts at 4, as PrefType occupies the bottom two bits.
106 : enum {
107 : PREF_FLAG_LOCKED = 4,
108 : PREF_FLAG_USERSET = 8,
109 : PREF_FLAG_CONFIG = 16,
110 : PREF_FLAG_REMOTE = 32,
111 : PREF_FLAG_LILOCAL = 64,
112 : PREF_FLAG_HAS_DEFAULT = 128,
113 : PREF_FLAG_STICKY_DEFAULT = 256,
114 : };
115 : uint16_t mValue;
116 : };
117 :
118 : struct PrefHashEntry : PLDHashEntryHdr
119 : {
120 : PrefTypeFlags prefFlags; // This field goes first to minimize struct size on 64-bit.
121 : const char *key;
122 : PrefValue defaultPref;
123 : PrefValue userPref;
124 : };
125 :
126 : /*
127 : // <font color=blue>
128 : // Set the various types of preferences. These functions take a dotted
129 : // notation of the preference name (e.g. "browser.startup.homepage").
130 : // Note that this will cause the preference to be saved to the file if
131 : // it is different from the default. In other words, these are used
132 : // to set the _user_ preferences.
133 : //
134 : // If set_default is set to true however, it sets the default value.
135 : // This will only affect the program behavior if the user does not have a value
136 : // saved over it for the particular preference. In addition, these will never
137 : // be saved out to disk.
138 : //
139 : // Each set returns PREF_VALUECHANGED if the user value changed
140 : // (triggering a callback), or PREF_NOERROR if the value was unchanged.
141 : // </font>
142 : */
143 : nsresult PREF_SetCharPref(const char *pref,const char* value, bool set_default = false);
144 : nsresult PREF_SetIntPref(const char *pref,int32_t value, bool set_default = false);
145 : nsresult PREF_SetBoolPref(const char *pref,bool value, bool set_default = false);
146 :
147 : bool PREF_HasUserPref(const char* pref_name);
148 :
149 : /*
150 : // <font color=blue>
151 : // Get the various types of preferences. These functions take a dotted
152 : // notation of the preference name (e.g. "browser.startup.homepage")
153 : //
154 : // They also take a pointer to fill in with the return value and return an
155 : // error value. At the moment, this is simply an int but it may
156 : // be converted to an enum once the global error strategy is worked out.
157 : //
158 : // They will perform conversion if the type doesn't match what was requested.
159 : // (if it is reasonably possible)
160 : // </font>
161 : */
162 : nsresult PREF_GetIntPref(const char *pref,
163 : int32_t * return_int, bool get_default);
164 : nsresult PREF_GetBoolPref(const char *pref, bool * return_val, bool get_default);
165 : /*
166 : // <font color=blue>
167 : // These functions are similar to the above "Get" version with the significant
168 : // difference that the preference module will alloc the memory (e.g. XP_STRDUP) and
169 : // the caller will need to be responsible for freeing it...
170 : // </font>
171 : */
172 : nsresult PREF_CopyCharPref(const char *pref, char ** return_buf, bool get_default);
173 : /*
174 : // <font color=blue>
175 : // bool function that returns whether or not the preference is locked and therefore
176 : // cannot be changed.
177 : // </font>
178 : */
179 : bool PREF_PrefIsLocked(const char *pref_name);
180 :
181 : /*
182 : // <font color=blue>
183 : // Function that sets whether or not the preference is locked and therefore
184 : // cannot be changed.
185 : // </font>
186 : */
187 : nsresult PREF_LockPref(const char *key, bool lockIt);
188 :
189 : PrefType PREF_GetPrefType(const char *pref_name);
190 :
191 : /*
192 : * Delete a branch of the tree
193 : */
194 : nsresult PREF_DeleteBranch(const char *branch_name);
195 :
196 : /*
197 : * Clears the given pref (reverts it to its default value)
198 : */
199 : nsresult PREF_ClearUserPref(const char *pref_name);
200 :
201 : /*
202 : * Clears all user prefs
203 : */
204 : nsresult PREF_ClearAllUserPrefs();
205 :
206 :
207 : /*
208 : // <font color=blue>
209 : // The callback function will get passed the pref_node which triggered the call
210 : // and the void * instance_data which was passed to the register callback function.
211 : // Return a non-zero result (nsresult) to pass an error up to the caller.
212 : // </font>
213 : */
214 : /* Temporarily conditionally compile PrefChangedFunc typedef.
215 : ** During migration from old libpref to nsIPref we need it in
216 : ** both header files. Eventually prefapi.h will become a private
217 : ** file. The two types need to be in sync for now. Certain
218 : ** compilers were having problems with multiple definitions.
219 : */
220 : #ifndef have_PrefChangedFunc_typedef
221 : typedef void (*PrefChangedFunc) (const char *, void *);
222 : #define have_PrefChangedFunc_typedef
223 : #endif
224 :
225 : /*
226 : // <font color=blue>
227 : // Register a callback. This takes a node in the preference tree and will
228 : // call the callback function if anything below that node is modified.
229 : // Unregister returns PREF_NOERROR if a callback was found that
230 : // matched all the parameters; otherwise it returns PREF_ERROR.
231 : // </font>
232 : */
233 : void PREF_RegisterPriorityCallback(const char* domain,
234 : PrefChangedFunc callback,
235 : void* instance_data );
236 : void PREF_RegisterCallback(const char* domain,
237 : PrefChangedFunc callback, void* instance_data );
238 : nsresult PREF_UnregisterCallback(const char* domain,
239 : PrefChangedFunc callback, void* instance_data );
240 :
241 : /*
242 : * Used by nsPrefService as the callback function of the 'pref' parser
243 : */
244 : void PREF_ReaderCallback( void *closure,
245 : const char *pref,
246 : PrefValue value,
247 : PrefType type,
248 : bool isDefault,
249 : bool isStickyDefault);
250 :
251 :
252 : /*
253 : * Callback whenever we change a preference
254 : */
255 : typedef void (*PrefsDirtyFunc) ();
256 : void PREF_SetDirtyCallback(PrefsDirtyFunc);
257 :
258 : #ifdef __cplusplus
259 : }
260 : #endif
261 : #endif
|
