Dynamic Settings

Description

Accessing and managing the environment dictionary.

Collaboration diagram for Dynamic Settings:

Primitive Get/Put ...
const char *	EnvGet (const char *key)
	Generically read a setting; Returns 'NULL' on non-existence and never prints warnings. More...
const char *	EnvPut (const char *key, const char *value)
	Generically put a string into the dictionary; Passing 'value == NULL' removes the entry. More...
const char *	EnvPut (const char *key, int value)
	Put an integer or boolean variable into the dictionary. More...
static void	EnvDel (const char *key)
	Remove an entry from the environment dictionary.

Get with type ...
These functions get an environment parameter and convert them to a given type. For each type, there are two variants: An advanced function returning the success status and - only on success - writing the result back via a pointer. A simple function returning that type; On error, the type's default value is returned. In all variants, a warning is emitted in case of a syntax error. If a parameter does not existence, 'false' is returned as a success code, and a warning is emitted if 'warnIfMissing' is set. Most parameters have reasonable defaults, so that 'warnIfMissing' is set to 'false' by default. To help with the discovery of typos in parameter keys, all accesses to non-existent parameters are logged as debug messages of level 1 in EnvGet(). Note: The functions with implicit translation capabilities ('EnvGetPath*' and 'EnvGetHost*') convert their strings in place. This means: Later retrievals by EnvGet() will return the absolute path, not the original string, e.g. from the configuration file. These functions may only be called from the main thread.
bool	EnvGetString (const char *key, const char **ret, bool warnIfMissing=false)
	Read a string (advanced variant).
const char *	EnvGetString (const char *key, const char *defaultVal, bool warnIfMissing=false)
	Read a string (simple variant).
static const char *	EnvGetString (const char *key, bool warnIfMissing)
	Read a string (simple variant) without default.
static const char *	EnvGetString (const char *key)
	Accelerator for 'EnvGetString (key, warnIfMissing = false)'.
bool	EnvGetPath (const char *key, const char **ret, const char *path=NULL, bool warnIfMissing=false)
	Read a path, eventually convert value to an absolute path before (advanced). The returned path is always absolute. Relative paths are interpreted as relative to 'path' or HOME2L_ROOT and made absolute.
const char *	EnvGetPath (const char *key, const char *path=NULL, bool warnIfMissing=false)
	Read a path, eventually convert value to an absolute path before (simple).
bool	EnvGetHostAndPort (const char *key, CString *retHost, int *retPort=NULL, int defaultPort=0, bool warnIfMissing=false)
	Get a host + port combination; host names are translated using the 'net.resolve.<name>' settings.
static bool	EnvGetHost (const char *key, CString *retHost, bool warnIfMissing=false)
	Get a host name; host names are translated using the 'net.resolve.<name>' settings.
bool	EnvGetInt (const char *key, int *ret, bool warnIfMissing=false)
	Read an integer (advanced).
int	EnvGetInt (const char *key, int defaultVal=0, bool warnIfMissing=false)
	Read an integer (simple).
bool	EnvGetFloat (const char *key, float *ret, bool warnIfMissing=false)
	Read a float value (advanced).
float	EnvGetFloat (const char *key, float defaultVal=0.0, bool warnIfMissing=false)
	Read a float value (simple).
bool	EnvGetBool (const char *key, bool *ret, bool warnIfMissing=false)
	Read a boolean value (advanced).
bool	EnvGetBool (const char *key, bool defaultVal=false, bool warnIfMissing=false)
	Read a boolean value (simple).

Advanced access to the dictionary ...
void	EnvGetPrefixInterval (const char *prefix, int *retIdx0, int *retIdx1)
const char *	EnvGetKey (int idx)
const char *	EnvGetVal (int idx)
const CDictRaw *	EnvGetKeySet ()
	Get the complete key set for direct key listing. More...

Function Documentation

EnvGet()

const char* EnvGet

(

const char *

key

)

Generically read a setting; Returns 'NULL' on non-existence and never prints warnings.

'key' can optionally be a sequence of keys separated by a colon (":"). In this case, the keys are tried in sequential order and the first available value is returned.

EnvPut() [1/2]

const char* EnvPut	(	const char *	key,
		const char *	value
	)

Generically put a string into the dictionary; Passing 'value == NULL' removes the entry.

Returns

Pointer to the copy of the value as stored in the database. Note: It is allowed to call this method before 'EnvInit' to pre-initialize environment settings. This feature is e.g. used for the Android initialization to set the hostname.

EnvPut() [2/2]

const char* EnvPut	(	const char *	key,
		int	value
	)

Put an integer or boolean variable into the dictionary.

Returns

Pointer the copy of the value as stored in the database.

EnvGetKeySet()

const CDictRaw* EnvGetKeySet

(

)

Get the complete key set for direct key listing.

Manipulations of the returned object are strictly forbidden!