michael@0: /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /*
michael@0: // <pre>
michael@0: */
michael@0: #ifndef PREFAPI_H
michael@0: #define PREFAPI_H
michael@0: 
michael@0: #include "nscore.h"
michael@0: #include "pldhash.h"
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: // 1 MB should be enough for everyone.
michael@0: static const uint32_t MAX_PREF_LENGTH = 1 * 1024 * 1024;
michael@0: // Actually, 4kb should be enough for everyone.
michael@0: static const uint32_t MAX_ADVISABLE_PREF_LENGTH = 4 * 1024;
michael@0: 
michael@0: typedef union
michael@0: {
michael@0:     char*       stringVal;
michael@0:     int32_t     intVal;
michael@0:     bool        boolVal;
michael@0: } PrefValue;
michael@0: 
michael@0: struct PrefHashEntry : PLDHashEntryHdr
michael@0: {
michael@0:     const char *key;
michael@0:     PrefValue defaultPref;
michael@0:     PrefValue userPref;
michael@0:     uint16_t  flags;
michael@0: };
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // The Init function initializes the preference context and creates
michael@0: // the preference hashtable.
michael@0: // </font>
michael@0: */
michael@0: nsresult    PREF_Init();
michael@0: 
michael@0: /*
michael@0: // Cleanup should be called at program exit to free the 
michael@0: // list of registered callbacks.
michael@0: */
michael@0: void        PREF_Cleanup();
michael@0: void        PREF_CleanupPrefs();
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // Preference flags, including the native type of the preference
michael@0: // </font>
michael@0: */
michael@0: 
michael@0: typedef enum { PREF_INVALID = 0,
michael@0:                PREF_LOCKED = 1, PREF_USERSET = 2, PREF_CONFIG = 4, PREF_REMOTE = 8,
michael@0:                PREF_LILOCAL = 16, PREF_STRING = 32, PREF_INT = 64, PREF_BOOL = 128,
michael@0:                PREF_HAS_DEFAULT = 256,
michael@0:                PREF_VALUETYPE_MASK = (PREF_STRING | PREF_INT | PREF_BOOL)
michael@0:              } PrefType;
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // Set the various types of preferences.  These functions take a dotted
michael@0: // notation of the preference name (e.g. "browser.startup.homepage").  
michael@0: // Note that this will cause the preference to be saved to the file if
michael@0: // it is different from the default.  In other words, these are used
michael@0: // to set the _user_ preferences.
michael@0: //
michael@0: // If set_default is set to true however, it sets the default value.
michael@0: // This will only affect the program behavior if the user does not have a value
michael@0: // saved over it for the particular preference.  In addition, these will never
michael@0: // be saved out to disk.
michael@0: //
michael@0: // Each set returns PREF_VALUECHANGED if the user value changed
michael@0: // (triggering a callback), or PREF_NOERROR if the value was unchanged.
michael@0: // </font>
michael@0: */
michael@0: nsresult PREF_SetCharPref(const char *pref,const char* value, bool set_default = false);
michael@0: nsresult PREF_SetIntPref(const char *pref,int32_t value, bool set_default = false);
michael@0: nsresult PREF_SetBoolPref(const char *pref,bool value, bool set_default = false);
michael@0: 
michael@0: bool     PREF_HasUserPref(const char* pref_name);
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // Get the various types of preferences.  These functions take a dotted
michael@0: // notation of the preference name (e.g. "browser.startup.homepage")
michael@0: //
michael@0: // They also take a pointer to fill in with the return value and return an
michael@0: // error value.  At the moment, this is simply an int but it may
michael@0: // be converted to an enum once the global error strategy is worked out.
michael@0: //
michael@0: // They will perform conversion if the type doesn't match what was requested.
michael@0: // (if it is reasonably possible)
michael@0: // </font>
michael@0: */
michael@0: nsresult PREF_GetIntPref(const char *pref,
michael@0:                            int32_t * return_int, bool get_default);	
michael@0: nsresult PREF_GetBoolPref(const char *pref, bool * return_val, bool get_default);	
michael@0: /*
michael@0: // <font color=blue>
michael@0: // These functions are similar to the above "Get" version with the significant
michael@0: // difference that the preference module will alloc the memory (e.g. XP_STRDUP) and
michael@0: // the caller will need to be responsible for freeing it...
michael@0: // </font>
michael@0: */
michael@0: nsresult PREF_CopyCharPref(const char *pref, char ** return_buf, bool get_default);
michael@0: /*
michael@0: // <font color=blue>
michael@0: // bool function that returns whether or not the preference is locked and therefore
michael@0: // cannot be changed.
michael@0: // </font>
michael@0: */
michael@0: bool PREF_PrefIsLocked(const char *pref_name);
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // Function that sets whether or not the preference is locked and therefore
michael@0: // cannot be changed.
michael@0: // </font>
michael@0: */
michael@0: nsresult PREF_LockPref(const char *key, bool lockIt);
michael@0: 
michael@0: PrefType PREF_GetPrefType(const char *pref_name);
michael@0: 
michael@0: /*
michael@0:  * Delete a branch of the tree
michael@0:  */
michael@0: nsresult PREF_DeleteBranch(const char *branch_name);
michael@0: 
michael@0: /*
michael@0:  * Clears the given pref (reverts it to its default value)
michael@0:  */
michael@0: nsresult PREF_ClearUserPref(const char *pref_name);
michael@0: 
michael@0: /*
michael@0:  * Clears all user prefs
michael@0:  */
michael@0: nsresult PREF_ClearAllUserPrefs();
michael@0: 
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // The callback function will get passed the pref_node which triggered the call
michael@0: // and the void * instance_data which was passed to the register callback function.
michael@0: // Return a non-zero result (nsresult) to pass an error up to the caller.
michael@0: // </font>
michael@0: */
michael@0: /* Temporarily conditionally compile PrefChangedFunc typedef.
michael@0: ** During migration from old libpref to nsIPref we need it in
michael@0: ** both header files.  Eventually prefapi.h will become a private
michael@0: ** file.  The two types need to be in sync for now.  Certain
michael@0: ** compilers were having problems with multiple definitions.
michael@0: */
michael@0: #ifndef have_PrefChangedFunc_typedef
michael@0: typedef void (*PrefChangedFunc) (const char *, void *);
michael@0: #define have_PrefChangedFunc_typedef
michael@0: #endif
michael@0: 
michael@0: /*
michael@0: // <font color=blue>
michael@0: // Register a callback.  This takes a node in the preference tree and will
michael@0: // call the callback function if anything below that node is modified.
michael@0: // Unregister returns PREF_NOERROR if a callback was found that
michael@0: // matched all the parameters; otherwise it returns PREF_ERROR.
michael@0: // </font>
michael@0: */
michael@0: void PREF_RegisterCallback( const char* domain,
michael@0: 								PrefChangedFunc callback, void* instance_data );
michael@0: nsresult PREF_UnregisterCallback( const char* domain,
michael@0: 								PrefChangedFunc callback, void* instance_data );
michael@0: 
michael@0: /*
michael@0:  * Used by nsPrefService as the callback function of the 'pref' parser
michael@0:  */
michael@0: void PREF_ReaderCallback( void *closure,
michael@0:                           const char *pref,
michael@0:                           PrefValue   value,
michael@0:                           PrefType    type,
michael@0:                           bool        isDefault);
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: #endif