1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/libpref/src/prefapi.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,191 @@
1.4 +/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 +// <pre>
1.11 +*/
1.12 +#ifndef PREFAPI_H
1.13 +#define PREFAPI_H
1.14 +
1.15 +#include "nscore.h"
1.16 +#include "pldhash.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +// 1 MB should be enough for everyone.
1.23 +static const uint32_t MAX_PREF_LENGTH = 1 * 1024 * 1024;
1.24 +// Actually, 4kb should be enough for everyone.
1.25 +static const uint32_t MAX_ADVISABLE_PREF_LENGTH = 4 * 1024;
1.26 +
1.27 +typedef union
1.28 +{
1.29 + char* stringVal;
1.30 + int32_t intVal;
1.31 + bool boolVal;
1.32 +} PrefValue;
1.33 +
1.34 +struct PrefHashEntry : PLDHashEntryHdr
1.35 +{
1.36 + const char *key;
1.37 + PrefValue defaultPref;
1.38 + PrefValue userPref;
1.39 + uint16_t flags;
1.40 +};
1.41 +
1.42 +/*
1.43 +// <font color=blue>
1.44 +// The Init function initializes the preference context and creates
1.45 +// the preference hashtable.
1.46 +// </font>
1.47 +*/
1.48 +nsresult PREF_Init();
1.49 +
1.50 +/*
1.51 +// Cleanup should be called at program exit to free the
1.52 +// list of registered callbacks.
1.53 +*/
1.54 +void PREF_Cleanup();
1.55 +void PREF_CleanupPrefs();
1.56 +
1.57 +/*
1.58 +// <font color=blue>
1.59 +// Preference flags, including the native type of the preference
1.60 +// </font>
1.61 +*/
1.62 +
1.63 +typedef enum { PREF_INVALID = 0,
1.64 + PREF_LOCKED = 1, PREF_USERSET = 2, PREF_CONFIG = 4, PREF_REMOTE = 8,
1.65 + PREF_LILOCAL = 16, PREF_STRING = 32, PREF_INT = 64, PREF_BOOL = 128,
1.66 + PREF_HAS_DEFAULT = 256,
1.67 + PREF_VALUETYPE_MASK = (PREF_STRING | PREF_INT | PREF_BOOL)
1.68 + } PrefType;
1.69 +
1.70 +/*
1.71 +// <font color=blue>
1.72 +// Set the various types of preferences. These functions take a dotted
1.73 +// notation of the preference name (e.g. "browser.startup.homepage").
1.74 +// Note that this will cause the preference to be saved to the file if
1.75 +// it is different from the default. In other words, these are used
1.76 +// to set the _user_ preferences.
1.77 +//
1.78 +// If set_default is set to true however, it sets the default value.
1.79 +// This will only affect the program behavior if the user does not have a value
1.80 +// saved over it for the particular preference. In addition, these will never
1.81 +// be saved out to disk.
1.82 +//
1.83 +// Each set returns PREF_VALUECHANGED if the user value changed
1.84 +// (triggering a callback), or PREF_NOERROR if the value was unchanged.
1.85 +// </font>
1.86 +*/
1.87 +nsresult PREF_SetCharPref(const char *pref,const char* value, bool set_default = false);
1.88 +nsresult PREF_SetIntPref(const char *pref,int32_t value, bool set_default = false);
1.89 +nsresult PREF_SetBoolPref(const char *pref,bool value, bool set_default = false);
1.90 +
1.91 +bool PREF_HasUserPref(const char* pref_name);
1.92 +
1.93 +/*
1.94 +// <font color=blue>
1.95 +// Get the various types of preferences. These functions take a dotted
1.96 +// notation of the preference name (e.g. "browser.startup.homepage")
1.97 +//
1.98 +// They also take a pointer to fill in with the return value and return an
1.99 +// error value. At the moment, this is simply an int but it may
1.100 +// be converted to an enum once the global error strategy is worked out.
1.101 +//
1.102 +// They will perform conversion if the type doesn't match what was requested.
1.103 +// (if it is reasonably possible)
1.104 +// </font>
1.105 +*/
1.106 +nsresult PREF_GetIntPref(const char *pref,
1.107 + int32_t * return_int, bool get_default);
1.108 +nsresult PREF_GetBoolPref(const char *pref, bool * return_val, bool get_default);
1.109 +/*
1.110 +// <font color=blue>
1.111 +// These functions are similar to the above "Get" version with the significant
1.112 +// difference that the preference module will alloc the memory (e.g. XP_STRDUP) and
1.113 +// the caller will need to be responsible for freeing it...
1.114 +// </font>
1.115 +*/
1.116 +nsresult PREF_CopyCharPref(const char *pref, char ** return_buf, bool get_default);
1.117 +/*
1.118 +// <font color=blue>
1.119 +// bool function that returns whether or not the preference is locked and therefore
1.120 +// cannot be changed.
1.121 +// </font>
1.122 +*/
1.123 +bool PREF_PrefIsLocked(const char *pref_name);
1.124 +
1.125 +/*
1.126 +// <font color=blue>
1.127 +// Function that sets whether or not the preference is locked and therefore
1.128 +// cannot be changed.
1.129 +// </font>
1.130 +*/
1.131 +nsresult PREF_LockPref(const char *key, bool lockIt);
1.132 +
1.133 +PrefType PREF_GetPrefType(const char *pref_name);
1.134 +
1.135 +/*
1.136 + * Delete a branch of the tree
1.137 + */
1.138 +nsresult PREF_DeleteBranch(const char *branch_name);
1.139 +
1.140 +/*
1.141 + * Clears the given pref (reverts it to its default value)
1.142 + */
1.143 +nsresult PREF_ClearUserPref(const char *pref_name);
1.144 +
1.145 +/*
1.146 + * Clears all user prefs
1.147 + */
1.148 +nsresult PREF_ClearAllUserPrefs();
1.149 +
1.150 +
1.151 +/*
1.152 +// <font color=blue>
1.153 +// The callback function will get passed the pref_node which triggered the call
1.154 +// and the void * instance_data which was passed to the register callback function.
1.155 +// Return a non-zero result (nsresult) to pass an error up to the caller.
1.156 +// </font>
1.157 +*/
1.158 +/* Temporarily conditionally compile PrefChangedFunc typedef.
1.159 +** During migration from old libpref to nsIPref we need it in
1.160 +** both header files. Eventually prefapi.h will become a private
1.161 +** file. The two types need to be in sync for now. Certain
1.162 +** compilers were having problems with multiple definitions.
1.163 +*/
1.164 +#ifndef have_PrefChangedFunc_typedef
1.165 +typedef void (*PrefChangedFunc) (const char *, void *);
1.166 +#define have_PrefChangedFunc_typedef
1.167 +#endif
1.168 +
1.169 +/*
1.170 +// <font color=blue>
1.171 +// Register a callback. This takes a node in the preference tree and will
1.172 +// call the callback function if anything below that node is modified.
1.173 +// Unregister returns PREF_NOERROR if a callback was found that
1.174 +// matched all the parameters; otherwise it returns PREF_ERROR.
1.175 +// </font>
1.176 +*/
1.177 +void PREF_RegisterCallback( const char* domain,
1.178 + PrefChangedFunc callback, void* instance_data );
1.179 +nsresult PREF_UnregisterCallback( const char* domain,
1.180 + PrefChangedFunc callback, void* instance_data );
1.181 +
1.182 +/*
1.183 + * Used by nsPrefService as the callback function of the 'pref' parser
1.184 + */
1.185 +void PREF_ReaderCallback( void *closure,
1.186 + const char *pref,
1.187 + PrefValue value,
1.188 + PrefType type,
1.189 + bool isDefault);
1.190 +
1.191 +#ifdef __cplusplus
1.192 +}
1.193 +#endif
1.194 +#endif
