Config Loader

Loader for ini-style configuration files with key-value pairs. More...

Data Structures
struct	config_scalar_value
	Description of a scalar value. More...
struct	config_array_member
	Description of one array member. More...
struct	config_nested_array_member
struct	config_array_value
	Description of an array. More...
struct	config_section
	Description of sections in the config file. More...

Macros
#define	CONFIG_MEMBER(member, structure)   #member, ua_offsetof(struct structure, member)
	Helper macro for describing a member of an array. More...
#define	CONFIG_ARRAY_MEMBER(member, length_field, structure)   #member, ua_offsetof(struct structure, member), ua_offsetof(struct structure, length_field)
	Helper macro for describing an array member inside an array. More...
#define	CONFIG_ARRAY(array, len_field, members)   (void **) &array, sizeof(*array), &len_field, members, countof(members), NULL, 0
	Helper macro for describing an array member inside a section. More...
#define	CONFIG_ARRAY_WITH_NESTED_ARRAY(array, len_field, members, array_members)   (void **) &array, sizeof(*array), &len_field, members, countof(members), array_members, countof(array_members)
	Helper macro for describing an array with nested array inside a section. More...
#define	CONFIG_MAX_LINE_LENGTH   UA_STREAM_BUF_SIZE
	Maximum length of lines in the settings file the loader can process. More...
#define	CONFIG_MAX_ARRAY_LENGTH   50
	Maximum length of arrays being loaded. More...
#define	CONFIG_MAX_RECURSION_DEPTH   10
	Maximum recursion depth for nested arrays and included configurations (cumulated). More...

Typedefs
typedef int(*	config_load_value) (char *string, void *value, uint32_t type)
	Function pointer for loading custom values: More...
typedef int(*	config_clear_value) (void *value, uint32_t type)
	Function pointer for clearing custom values: More...
typedef int(*	config_write_value) (struct ua_filestream *stream, void *value, uint32_t type)
	Function pointer for writing custom values: More...

Enumerations
enum	config_data_type {   CONFIG_TYPE_BOOL, CONFIG_TYPE_UINT8, CONFIG_TYPE_INT8, CONFIG_TYPE_UINT16,   CONFIG_TYPE_INT16, CONFIG_TYPE_UINT32, CONFIG_TYPE_INT32, CONFIG_TYPE_UINT64,   CONFIG_TYPE_INT64, CONFIG_TYPE_DOUBLE, CONFIG_TYPE_STRING, CONFIG_TYPE_CERTIFICATE_TYPE }
	Builtin types for scalar values and array members. More...

Functions
CONFIG_EXPORT int	config_load_from_file (const char *filename, const struct config_section *sections, unsigned int num_sections, config_load_value load_fct, config_clear_value clear_fct)
	Load configuration from file. More...
CONFIG_EXPORT void	config_clear (const struct config_section *sections, unsigned int num_sections, config_clear_value clear_fct)
	Clear a configuration loaded from file. More...
CONFIG_EXPORT int	config_write_to_file (const char *filename, const struct config_section *sections, unsigned int num_sections, config_write_value write_fct)
	Write a config to a settings file. More...
CONFIG_EXPORT int	config_load_certificate_type (const char *string, const size_t string_len, enum certificate_types *type)
	Converts the string representation of the certificate type to the enumeration value. More...
CONFIG_EXPORT int	config_write_certificate_type (enum certificate_types type, const char **string)
	Converts the enumeration representation of the certificate type to the string value. More...
CONFIG_EXPORT int	config_set_string_parameter (const char **param, const char *new_value)
	Allows changing string parameters in appconfig. More...

Detailed Description

Loader for ini-style configuration files with key-value pairs.

To be able to load settings file the config loader needs a description of the structure of the settings file. For this description the config loader defines a number of structs like config_scalar_value or config_array_value. Every value must be inside a section, described by config_section. The values are written directly into a global struct provided by the caller. A small example how to use these is given further below.

The config loader has a number of builtin data types, including boolean, string and different numeric types. However it is also possible to implement own types by implementing functions that comply with config_load_value and config_clear_value and also config_write_value, if configs should also be written back to files. These functions must be passed to respective functions when calling. The custom types should use identifiers starting at 1000, as number below are reserverd for builtin types.

The config loader supports arrays, these need a pointer to the data and a length field, the latter must be a 32bit integer. It is possible to nest arrays inside other arrays, however this is not recommended as the description structure becomes very difficult to create. If it is still done it is important, that the lenght field is directly before the pointer to the data.

It is possible to include other settings file into a settings by using the include statement like this: '!include more_settings.conf'. There are a few points to consider when using includes:

• The included path may be either absolute or relative, in case of a relative path the inlcuded settings file is loaded relative to the path of the current settings file.
• The location of the include statement inside the file is important, values set before the include are replaced by the included values, values after the include replace included values.
• Inlcuded files need to have their own sections, the section the include statement is in does not matter for the included values, the include statement may also be outside of a section.
• Arrays can also be replaced by setting a new size in the included file, this will delete the complete previous array and create new one with the new size, all values of the previous array are lost. When the included file only contains values for members of an array only these members are replaced and other values are kept.

The example config consists of a simple struct with two scalar members and one array:

struct my_array {
    uint32_t member1;
    char *member2;
};

struct my_config {
    bool scalar1;
    char *scalar2;
    struct my_array *array1;
    uint32_t num_array1;
};

struct my_config g_config;

All members of the config must be described with structs defined by the config loader, the provided macros can simplify some of these descriptions. Values can only be loaded from inside a section, so the section here is called 'section1':

static const struct config_array_member my_array_members[] = {
    {CONFIG_MEMBER(member1, my_array), CONFIG_TYPE_UINT32},
    {CONFIG_MEMBER(member2, my_array), CONFIG_TYPE_STRING}
};

static const struct config_array_value section1_arrays[] = {
    {"my_array", CONFIG_ARRAY(g_config.array1, g_config.num_array1, my_array_members)}
};

static const struct config_scalar_value section1_scalars[] = {
    {"scalar1", &g_config.scalar1, CONFIG_TYPE_BOOL},
    {"scalar2", &g_config.scalar2, CONFIG_TYPE_STRING}
};

static const struct config_section my_config_sections[] = {
    {"section1", section1_scalars, countof(section1_scalars), section1_arrays, countof(section1_arrays)},
};

Before loading the config, memset is used to have a defined state for the config, then config_load_from_file is called:

ua_memset(&g_config, 0, sizeof(struct my_config));

ret = config_load_from_file("my_settings.conf", my_config_sections, countof(my_config_sections), NULL, NULL);
if (ret != 0) goto error;

The settings file 'my_settings.conf' could look like this:

[section1]

scalar1 = true
scalar2 = some string

my_array/size = 2
my_array/0/member1 = 123
my_array/0/member2 = array string
my_array/1/member1 = 4711
my_array/1/member2 = another string

Macro Definition Documentation

CONFIG_ARRAY

#define CONFIG_ARRAY	(		array,
			len_field,
			members
	)		(void **) &array, sizeof(*array), &len_field, members, countof(members), NULL, 0

Helper macro for describing an array member inside a section.

CONFIG_ARRAY_MEMBER

#define CONFIG_ARRAY_MEMBER	(		member,
			length_field,
			structure
	)		#member, ua_offsetof(struct structure, member), ua_offsetof(struct structure, length_field)

Helper macro for describing an array member inside an array.

CONFIG_ARRAY_WITH_NESTED_ARRAY

#define CONFIG_ARRAY_WITH_NESTED_ARRAY	(		array,
			len_field,
			members,
			array_members
	)		(void **) &array, sizeof(*array), &len_field, members, countof(members), array_members, countof(array_members)

Helper macro for describing an array with nested array inside a section.

CONFIG_MAX_ARRAY_LENGTH

#define CONFIG_MAX_ARRAY_LENGTH   50

Maximum length of arrays being loaded.

CONFIG_MAX_LINE_LENGTH

#define CONFIG_MAX_LINE_LENGTH   UA_STREAM_BUF_SIZE

Maximum length of lines in the settings file the loader can process.

CONFIG_MAX_RECURSION_DEPTH

#define CONFIG_MAX_RECURSION_DEPTH   10

Maximum recursion depth for nested arrays and included configurations (cumulated).

CONFIG_MEMBER

#define CONFIG_MEMBER	(		member,
			structure
	)		#member, ua_offsetof(struct structure, member)

Helper macro for describing a member of an array.

Typedef Documentation

config_clear_value

typedef int(* config_clear_value) (void *value, uint32_t type)

Function pointer for clearing custom values:

Parameters

value	A pointer to the value that must be cleared
type	The type of the value to be cleared.

Returns

Zero on success or negative errorcode on failure.

config_load_value

typedef int(* config_load_value) (char *string, void *value, uint32_t type)

Function pointer for loading custom values:

Parameters

string	The value to be loaded as string.
value	A pointer to where the value must be written to
type	The type of the value to be loaded.

Returns

Zero on success or negative errorcode on failure.

config_write_value

typedef int(* config_write_value) (struct ua_filestream *stream, void *value, uint32_t type)

Function pointer for writing custom values:

Parameters

stream	A filestream to write the value to.
value	A pointer to the value to write.
type	The type of the value to be written.

Returns

Zero on success or negative errorcode on failure.

Enumeration Type Documentation

config_data_type

enum config_data_type

Builtin types for scalar values and array members.

Custom types should start at a value of 1000

Function Documentation

config_clear()

CONFIG_EXPORT void config_clear	(	const struct config_section *	sections,
		unsigned int	num_sections,
		config_clear_value	clear_fct
	)

Clear a configuration loaded from file.

Iterate through a configuration and free dynamic memory by passing all pointers to ua_free() and setting it to NULL.

Parameters

sections	array of sections describing the configuration.
num_sections	number of elements in sections.
clear_fct	Function for clearing custom types, must be NULL if none exist.

config_load_certificate_type()

CONFIG_EXPORT int config_load_certificate_type	(	const char *	string,
		const size_t	string_len,
		enum certificate_types *	type
	)

Converts the string representation of the certificate type to the enumeration value.

Parameters

string	String read from the configuration file.
string_len	Length of string.
type	Returns the enumeration value.

Returns

UA_EGOOD in success case or UA_EBADINVALIDARGUMENT in error case.

config_load_from_file()

CONFIG_EXPORT int config_load_from_file	(	const char *	filename,
		const struct config_section *	sections,
		unsigned int	num_sections,
		config_load_value	load_fct,
		config_clear_value	clear_fct
	)

Load configuration from file.

Load a configuration described by sections from the file filename.

The configuration may already be initilized with default values, which are overwritten if the according values are contained in the configuration file. All pointers to dynamic memory (e.g. arrays or strings) must be allocated by ua_malloc. In case of an error all values (including the default values) are freed with ua_free.

Parameters

filename	filename of the configuration file.
sections	array of sections in the configuration file.
num_sections	number of elements in sections.
load_fct	Function for loading custom values, must be NULL if there are none.
clear_fct	Function for clearing custom values, must be set if load_fct is set.

Returns

errorcode in case of failure or zero on success.

config_set_string_parameter()

CONFIG_EXPORT int config_set_string_parameter	(	const char **	param,
		const char *	new_value
	)

Allows changing string parameters in appconfig.

This function will free existing string values and creates a new copy of the given value. Attention: You can only modify the configuration before calling uaapplication_init. Changes afterwards may have no effect.

Parameters

param	Address of appconfig string parameter.
new_value	New value.

Returns

Zero on success.

config_write_certificate_type()

CONFIG_EXPORT int config_write_certificate_type	(	enum certificate_types	type,
		const char **	string
	)

Converts the enumeration representation of the certificate type to the string value.

Parameters

type	The enumeration value of the certificate type.
string	Returns the string value of the certificate type.

Returns

UA_EGOOD in success case or UA_EBADINVALIDARGUMENT in error case.

config_write_to_file()

CONFIG_EXPORT int config_write_to_file	(	const char *	filename,
		const struct config_section *	sections,
		unsigned int	num_sections,
		config_write_value	write_fct
	)

Write a config to a settings file.

If the file does not exist it will be created, if the file exists it will be overwritten. There are no comments written to the generated file, so if a file with comments is overwritten all comments will be lost.

All values will be written into a single file, so if some values were loaded from an included file these are still written into the target file.

Parameters

filename	Name of the file to write.
sections	array of sections describing the configuration.
num_sections	number of elements in sections.
write_fct	Function for writing custom values.

Returns

Zero on success or errorcode on failure