This class contains the description of the environment the application is running in. More...

#include <ildblink/ilenv.h>

Public Member Functions
virtual	~IlEnvironment ()
	This virtual destructor must be invoked when the application terminates. More...

IlUChar *	getBinaryResource (int level, const char bundleNames[], IlInt &len, const char key=0)
	Retrieve a binary vector from the current resource bundle. More...

const char *	getEnvOrOption (const char name, const char resName=0, const char *def=0) const
	Retrieve the value of an option. More...

const char *	getEnvOrResource (const char name, const char resName=0, const char *def=0) const
	Retrieve the value of a resource. More...

IlInt	getIntResource (int level, const char bundleNames[], const char key=0)
	Retrieve an integer from the current resource bundle. More...

IlInt	getIntVectNthResource (int level, const char bundleNames[], IlInt nth, const char key=0)
	Retrieve a value in a vector of integers from the current resource bundle. More...

IlInt *	getIntVectResource (int level, const char bundleNames[], IlInt &len, const char key=0)
	Retrieve a vector of integers from the current resource bundle. More...

char *	getMessage (const char key, const char bName=0)
	Retrieve a message text. More...

char *	getMessageUTF8 (const char key, const char bName=0)
	Retrieve a message text. More...

const char *	getOption (const char name, const char def=0) const
	Retrieve the value of an option. More...

const char *	getOptionValue (char *key) const
	Retrieve the value of an option. More...

const char *	getResource (const char name, const char def=0) const
	Retrieve the value of a resource using the resource callback function. More...

IlBoolean	loadResources (const char *bName=0)
	Load a resource bundle for the current locale. More...

IlChangeLocaleFunc	setChangeLocaleCallback (IlChangeLocaleFunc f, IlAny cbkData=0)
	Set a callback function to be called whenever the application locale is changed. More...

IlGetResFunc	setGetResourceCallback (IlGetResFunc f, IlAny cbkData=0)
	Set a callback function to be called whenever the `getResource` member funtion is called. More...

virtual IlBoolean	setLocale (const char language, const char country=0, const char variant=0, const char keysAndVals=0)
	Set the current locale to the one defined by the given arguments. More...

void	setOption (char key, char value)
	Set the value of an option under some key. More...

IlBoolean	setOptionValue (char key, char value)
	Modify the value of an option under some key. More...

Static Public Member Functions
static IlBoolean	Exists ()
	This static function indicates if an environment instance was created or not. More...

static IlEnvironment *	Get ()
	This static function is the only way to gain access to the unique environment object an application has. More...

Detailed Description

This class contains the description of the environment the application is running in.

Library: dbkernel

This class is a container to store all data items pertaining to runtime environment like locale, timezone, resources, date and time formatter, number formatter, and specific options.

Locales, timezones, and resources are managed using ICU exclusively. Options are freeform, provided keys are strings and one knows what type is the value. Resoure bundle elements can be those defined by ICU (International Components for Unicode). The formal structure of resource bundles is precisely the one from ICU: http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt

Date and time formatter and number formatter are not allocated initially: they will be created, according to the current locale and timezone, the first time they are accessed.

Constructor & Destructor Documentation

◆ ~IlEnvironment()

virtual IlEnvironment::~IlEnvironment ( )

virtual

This virtual destructor must be invoked when the application terminates.

The destructor cleans up all its internal structures including the loaded resource bundles. Option keys and values will not be deleted since they were provided by the application and may be used in other places.

Note: The destructor can be called at any time. Such a call will completely remove the existing instance but a brand new one will be created by a call to IlEnvironment::Get.

Member Function Documentation

◆ Exists()

static IlBoolean IlEnvironment::Exists ( )

static

This static function indicates if an environment instance was created or not.

Returns: IlTrue if an environment object has been created, IlFalse otherwise.

See also: setLocale(), setTimeZone(), loadResources().

◆ Get()

static IlEnvironment* IlEnvironment::Get ( )

static

This static function is the only way to gain access to the unique environment object an application has.

Returns: The unique environment object.

If no environment object exists at the time this function is called, one will be created as follows:

The locale is set to the system current one.
The time zone is GMT.
No resources are loaded.
No options are set.
No callback function will be preset for getting resources or be warned of locale changes. Consequently no data will be stored for the callback functions.
No resource bundle access path set.

Note: It is the application responsibility to check the environment objet is properly formed: use the isBad() function. If this call returns IlTrue, then the creation of the default locale object or the initialization of the ICU library failed.

See also: isBad().

◆ getBinaryResource()

IlUChar* IlEnvironment::getBinaryResource	(	int	level,
		const char *	bundleNames[],
		IlInt &	len,
		const char *	key = `0`
	)

Retrieve a binary vector from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
len	An output argument that will, upon successful completion, contains the number of entries in the returned vector.
key	Optional, a key in the last bundle accessed.

Returns: A binary vector that makes up the value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is 0, and the len argument is set to 0.

Note: It is the application responsibility to delete the array.

◆ getEnvOrOption()

const char* IlEnvironment::getEnvOrOption	(	const char *	name,
		const char *	resName = `0`,
		const char *	def = `0`
	)		const

Retrieve the value of an option.

Parameters

name	The name of an environment variable.
resName	Optional, the option name if internally defined.
def	Optional, the default value to return in case no option with this name exists.

Returns: The option or environment value, or the given default value.

The function will first look into the system environment if a variable named name exists, then it will return its value. Else, it will search the application array of options using resName, if given, as key. Finally, if both approaches failed, it will return the given default def.

◆ getEnvOrResource()

const char* IlEnvironment::getEnvOrResource	(	const char *	name,
		const char *	resName = `0`,
		const char *	def = `0`
	)		const

Retrieve the value of a resource.

Parameters

name	The name of an environment variable.
resName	The name used to store the value of the resource.
def	Optional, the default value to return in case no resource of this name exists.

Returns: The resource value or the given default value.

The function will first look into the system environement if a variable named name exists. If so it will return its value. Else, it will call the resource callback function using resName, if given, as key. Finally, if both approaches failed, it will return the given default def.

See also: getResource

◆ getIntResource()

IlInt IlEnvironment::getIntResource	(	int	level,
		const char *	bundleNames[],
		const char *	key = `0`
	)

Retrieve an integer from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
key	Optional, a key in the last bundle accessed.

Returns: The integer value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is INT_MIN.

◆ getIntVectNthResource()

IlInt IlEnvironment::getIntVectNthResource	(	int	level,
		const char *	bundleNames[],
		IlInt	nth,
		const char *	key = `0`
	)

Retrieve a value in a vector of integers from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will dive into one after the other.
nth	The order of the value to retrieve in the vector,
key	Optional, a key in the last bundle accessed.

Returns: The integer at the nth position in the vector.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array bundleNames are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is the smallest possible integer (INT_MIN).

◆ getIntVectResource()

IlInt* IlEnvironment::getIntVectResource	(	int	level,
		const char *	bundleNames[],
		IlInt &	len,
		const char *	key = `0`
	)

Retrieve a vector of integers from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
len	This output argument will, upon successful completion, contains the number of entries in the returned vector.
key	Optional, a key in the last bundle accessed.

Returns: A vector of integers that makes up the value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is 0, and the len argument is set to 0.

Note: It is the application responsibility to delete the array.

◆ getMessage()

char* IlEnvironment::getMessage	(	const char *	key,
		const char *	bName = `0`
	)

Retrieve a message text.

Parameters

key	the message key. It must be a string whose characters all belong to the invariant section of Unicode (the ASCII characters).
bName	the bundle name in which to look for the message text.

Returns: A string containing the message text.

The second argument bName may be null but not the empty string. If it is null and a bundle at least was loaded, the search will happen into the last loaded bundle.

This function is based on the following assumptions:

at least one bundle has been loaded beforehand.
any bundle in any locale has a first level sub-bundle whose name is 'messages'.
this sub-bundle is composed of items which all have a key and a string contents, that is this sub-bundle is of type 'table'.

In case of error, the returned object state is undefined.

Note: It is the application responsibility to check the state of the environment object using the isBad() function. It is also the application responsibility to destroy the returned string once done with it.

See also: getResources

◆ getMessageUTF8()

char* IlEnvironment::getMessageUTF8	(	const char *	key,
		const char *	bName = `0`
	)

Retrieve a message text.

Parameters

key	The message key. It must be a string whose characters all belong to the invariant section of Unicode (the ASCII characters).
bName	The bundle name in which to look for the message text.

Returns: A pointer to a UTF8 encoded string containing the message text.

This function is based on the same assumptions as the function getMessage. In case of error, the returned object is null.

Note: It is the application responsibility to destroy the returned string once done with it.

◆ getOption()

const char* IlEnvironment::getOption	(	const char *	name,
		const char *	def = `0`
	)		const

Retrieve the value of an option.

Parameters

name	The name used to store the value of the option.
def	The default value to return in case no option of this name exists.

Returns: The option value or the given default value.

All option values must be under string form. If one needs to be an integer or real number, it is the application responsibility to proceed to the transformation.

◆ getOptionValue()

const char* IlEnvironment::getOptionValue ( char * key ) const

Retrieve the value of an option.

Parameters

key	The key used to store the value of the option.

Returns: The option value.

All option values must be under string form. If one needs to be an integer or real number, it is the application responsibility to proceed to the transformation.

◆ getResource()

const char* IlEnvironment::getResource	(	const char *	name,
		const char *	def = `0`
	)		const

Retrieve the value of a resource using the resource callback function.

Parameters

name	The name of a resource.
def	The default value to return in case no resource of this name exists.

Returns: The resource value or the given default value.

If no resource callback function was set, it will always return the default value def.

See also: setGetResourceCallback

◆ loadResources()

IlBoolean IlEnvironment::loadResources ( const char * bName = 0 )

Load a resource bundle for the current locale.

Parameters

bName The directory where the file for this resource bundle can be found.

Returns: IlTrue if the operation succeeded.

If the bName argument is null, the contents of the data directories array will be used. If the argument is non null, the internal data directories path are searched for a sub-directory with name bName. If such a directory is found, an attempt at loading the resource bundle will be made.

In case of success the bundle can be retrieved using getResources. The files to load must be in ICU compiled format. Thus the loader will look for files with extension '.res'.

Note: The name is used to register the bundle but it is not copied.

◆ setChangeLocaleCallback()

IlChangeLocaleFunc IlEnvironment::setChangeLocaleCallback	(	IlChangeLocaleFunc	f,
		IlAny	cbkData = `0`
	)

Set a callback function to be called whenever the application locale is changed.

Parameters

f	The callback function implementing the specific mechanism the application will use.
cbkData	Optionally, some application specific data that will be passed as first argument to the callback function.

Returns: The previous callback function or null.

See also: IlChangeLocale, setLocale.

◆ setGetResourceCallback()

IlGetResFunc IlEnvironment::setGetResourceCallback	(	IlGetResFunc	f,
		IlAny	cbkData = `0`
	)

Set a callback function to be called whenever the getResource member funtion is called.

Parameters

f	The callback function implementing the specific mechanism the application will use.
cbkData	Optionally, some application specific data that will be passed as first argument to the callback function.

Returns: The previous callback function or null.

This function cannot fail. So it is possible to remove the callback function and data by calling this function with both arguments set to null.

See also: IlGetResFunc, getResource.

◆ setLocale()

virtual IlBoolean IlEnvironment::setLocale	(	const char *	language,
		const char *	country = `0`,
		const char *	variant = `0`,
		const char *	keysAndVals = `0`
	)

virtual

Set the current locale to the one defined by the given arguments.

Parameters

language	The new locale language.
country	The optional country for the language.
variant	The optional variant applicable for the language and country combination.
keysAndVals	Optional additional settings for the new locale.

Returns: IlTrue if the locale change went well.

The language value must be one defined by the ISO standard 639-2. The country value must be one defined by the ISO standard 3166.

◆ setOption()

void IlEnvironment::setOption	(	char *	key,
		char *	value
	)

Set the value of an option under some key.

Parameters

key	The key used to store the value of the option.
value	The option value.

Note: Neither the key nor the value are copied.

◆ setOptionValue()

IlBoolean IlEnvironment::setOptionValue	(	char *	key,
		char *	value
	)

Modify the value of an option under some key.

Parameters

key	The key used to store the value of the option.
value	The option value.

Returns: IlTrue if the assignment succeeded.

Note: The new value is not copied.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IlEnvironment()

Member Function Documentation

◆ Exists()

◆ Get()

◆ getBinaryResource()

◆ getEnvOrOption()

◆ getEnvOrResource()

◆ getIntResource()

◆ getIntVectNthResource()

◆ getIntVectResource()

◆ getMessage()

◆ getMessageUTF8()

◆ getOption()

◆ getOptionValue()

◆ getResource()

◆ loadResources()

◆ setChangeLocaleCallback()

◆ setGetResourceCallback()

◆ setLocale()

◆ setOption()

◆ setOptionValue()