Configuration section
[Configuration registry]

Typedefs
typedef struct bg_cfg_section_s	bg_cfg_section_t
	Configuration section.
Functions
void	bg_cfg_section_2_xml (bg_cfg_section_t *section, xmlNodePtr xml_section)
	Convert a configuration section into a libxml2 node.
void	bg_cfg_xml_2_section (xmlDocPtr xml_doc, xmlNodePtr xml_section, bg_cfg_section_t *section)
	Convert libxml2 node into a configuration section.
bg_cfg_section_t *	bg_cfg_section_find_subsection (bg_cfg_section_t *section, const char *name)
	Find a child of a section.
bg_cfg_section_t *	bg_cfg_section_create_subsection_at_pos (bg_cfg_section_t *section, int pos)
	Create a subsection at the specified position.
void	bg_cfg_section_move_child (bg_cfg_section_t *section, bg_cfg_section_t *child, int pos)
	Move a subsection to the specified position.
bg_cfg_section_t *	bg_cfg_section_find_subsection_by_index (bg_cfg_section_t *section, int index)
	Find a child of a section by index.
bg_cfg_section_t *	bg_cfg_section_create (const char *name)
	Create an empty config section.
bg_cfg_section_t *	bg_cfg_section_create_from_parameters (const char *name, const bg_parameter_info_t *parameters)
	Create a config section from a parameter array.
void	bg_cfg_section_create_items (bg_cfg_section_t *section, const bg_parameter_info_t *parameters)
	Create items from a parameter info.
void	bg_cfg_section_destroy (bg_cfg_section_t *section)
	Destroy a config section.
bg_cfg_section_t *	bg_cfg_section_copy (const bg_cfg_section_t *src)
	Duplicate a configuration section.
void	bg_cfg_section_restore (bg_cfg_section_t *section, bg_cfg_section_t *section_saved)
	Restore a configuration section from a previously copied one.
void	bg_cfg_section_transfer (bg_cfg_section_t *src, bg_cfg_section_t *dst)
	Set values in a configuration section from another section.
const char *	bg_cfg_section_get_name (bg_cfg_section_t *section)
	Get the name of a configuration section.
char *	bg_cfg_section_get_name_translated (bg_cfg_section_t *section)
	Get the translated name of a configuration section.
void	bg_cfg_section_set_name (bg_cfg_section_t *section, const char *name, const char *gettext_domain, const char *gettext_directory)
	Set the name of a configuration section.
void	bg_cfg_section_set_parameter (bg_cfg_section_t *section, const bg_parameter_info_t *info, const bg_parameter_value_t *value)
	Store a value in the section.
int	bg_cfg_section_set_parameters_from_string (bg_cfg_section_t *section, const bg_parameter_info_t *info, const char *str)
	Set values from an option string.
void	bg_cfg_section_get_parameter (bg_cfg_section_t *section, const bg_parameter_info_t *info, bg_parameter_value_t *value)
	Read a value from the section.
void	bg_cfg_section_delete_subsection (bg_cfg_section_t *section, bg_cfg_section_t *subsection)
	Delete a subsection.
void	bg_cfg_section_set_parameter_int (bg_cfg_section_t *section, const char *name, int value)
	Store an integer value in a section.
void	bg_cfg_section_set_parameter_float (bg_cfg_section_t *section, const char *name, float value)
	Store a float value in a section.
void	bg_cfg_section_set_parameter_string (bg_cfg_section_t *section, const char *name, const char *value)
	Store a string value in a section.
void	bg_cfg_section_set_parameter_time (bg_cfg_section_t *section, const char *name, gavl_time_t value)
	Store a time value in a section.
int	bg_cfg_section_get_parameter_int (bg_cfg_section_t *section, const char *name, int *value)
	Get an integer value from a section.
int	bg_cfg_section_get_parameter_float (bg_cfg_section_t *section, const char *name, float *value)
	Get an float value from a section.
int	bg_cfg_section_get_parameter_string (bg_cfg_section_t *section, const char *name, const char **value)
	Get an string value from a section.
int	bg_cfg_section_get_parameter_time (bg_cfg_section_t *section, const char *name, gavl_time_t *value)
	Get an time value from a section.
void	bg_cfg_section_apply (bg_cfg_section_t *section, const bg_parameter_info_t *parameters, bg_set_parameter_func_t func, void *callback_data)
	Send all parameters to a module.
void	bg_cfg_section_apply_noterminate (bg_cfg_section_t *section, const bg_parameter_info_t *infos, bg_set_parameter_func_t func, void *callback_data)
	Send all parameters to a module without terminating.
void	bg_cfg_section_get (bg_cfg_section_t *section, const bg_parameter_info_t *parameters, bg_get_parameter_func_t func, void *callback_data)
	Get parameters from a module.
int	bg_cfg_section_has_subsection (bg_cfg_section_t *section, const char *name)
	Qurey if a child section is available.

---

Detailed Description

Sections are nodes in the configuration tree. They can contain name-value pairs and child sections. Usually, config sections are kept within a configuration registry to store the applications configuration data.

They can, however, be used indepentently from a registry as universal data containers.

---

Typedef Documentation

typedef struct bg_cfg_section_s bg_cfg_section_t

Configuration section.

Opaque container for configuration data and child sections

---

Function Documentation

void bg_cfg_section_2_xml	(	bg_cfg_section_t *	section,
		xmlNodePtr	xml_section
	)

Convert a configuration section into a libxml2 node.

Parameters:

	section	Configuration section
	xml_section	Pointer to the xml node for the section

See the libxml2 documentation for more infos

void bg_cfg_xml_2_section	(	xmlDocPtr	xml_doc,
		xmlNodePtr	xml_section,
		bg_cfg_section_t *	section
	)

Convert libxml2 node into a configuration section.

Parameters:

	xml_doc	Pointer to the xml document
	xml_section	Pointer to the xml node for the section
	section	Configuration section

See the libxml2 documentation for more infos

bg_cfg_section_t* bg_cfg_section_find_subsection	(	bg_cfg_section_t *	section,
		const char *	name
	)

Find a child of a section.

Parameters:

	section	A configuration section
	name	name of the subsection

Returns:

Configuration section

If the child section does not exist, an empty section is created.

bg_cfg_section_t* bg_cfg_section_create_subsection_at_pos	(	bg_cfg_section_t *	section,
		int	pos
	)

Create a subsection at the specified position.

Parameters:

	section	A configuration section
	pos	Position of the subsection (starting with 0)

Returns:

Configuration section

void bg_cfg_section_move_child	(	bg_cfg_section_t *	section,
		bg_cfg_section_t *	child,
		int	pos
	)

Move a subsection to the specified position.

Parameters:

	section	A configuration section
	child	Subsection to be moved
	pos	New position of the subsection (starting with 0)

bg_cfg_section_t* bg_cfg_section_find_subsection_by_index	(	bg_cfg_section_t *	section,
		int	index
	)

Find a child of a section by index.

Parameters:

	section	A configuration section
	index	Index (starting with 0)

Returns:

Configuration section

If the child section does not exist, NULL is returned.

bg_cfg_section_t* bg_cfg_section_create

(

const char *

name

)

Create an empty config section.

Parameters:

name

Name

Returns:

Configuration section

bg_cfg_section_t* bg_cfg_section_create_from_parameters	(	const char *	name,
		const bg_parameter_info_t *	parameters
	)

Create a config section from a parameter array.

Parameters:

	name	Name
	parameters	A parameter array

Returns:

Configuration section

Creates a configuration section from a parameter array. The values in the section are set from the defaults given in the array.

void bg_cfg_section_create_items	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	parameters
	)

Create items from a parameter info.

Parameters:

	section	Configuration section
	parameters	A parameter array

This iterates through parameters and creates all missing entries with the values set to their defaults

void bg_cfg_section_destroy

(

bg_cfg_section_t *

section

)

Destroy a config section.

Parameters:

section

Configuration section

bg_cfg_section_t* bg_cfg_section_copy

(

const bg_cfg_section_t *

src

)

Duplicate a configuration section.

Parameters:

src

Configuration section

Returns:

A newly allocated section with all values copied from src.

void bg_cfg_section_restore	(	bg_cfg_section_t *	section,
		bg_cfg_section_t *	section_saved
	)

Restore a configuration section from a previously copied one.

Parameters:

	section	Configuration section
	section_saved	Saved configuration section

Returns:

A newly allocated section with all values copied from src.

void bg_cfg_section_transfer	(	bg_cfg_section_t *	src,
		bg_cfg_section_t *	dst
	)

Set values in a configuration section from another section.

Parameters:

	src	Source section
	dst	Destination section

This function iterates through all entries of src and copies the values to dst. Values, which don't exist in dst, are created. The same is then done for all children of src.

const char* bg_cfg_section_get_name

(

bg_cfg_section_t *

section

)

Get the name of a configuration section.

Parameters:

section

Configuration section

Returns:

The name

char* bg_cfg_section_get_name_translated

(

bg_cfg_section_t *

section

)

Get the translated name of a configuration section.

Parameters:

section

Configuration section

Returns:

The translated name

The returned string must be freed by the caller

void bg_cfg_section_set_name	(	bg_cfg_section_t *	section,
		const char *	name,
		const char *	gettext_domain,
		const char *	gettext_directory
	)

Set the name of a configuration section.

Parameters:

	section	Configuration section
	name	The new name
	gettext_domain	First argument for bindtextdomain()
	gettext_directory	Second argument for bindtextdomain()

void bg_cfg_section_set_parameter	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	info,
		const bg_parameter_value_t *	value
	)

Store a value in the section.

Parameters:

	section	The configuration section
	info	The parameter destription
	value	The value to be stored

If the value does not exist in the section, it is created from the parameter description.

int bg_cfg_section_set_parameters_from_string	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	info,
		const char *	str
	)

Set values from an option string.

Parameters:

	section	The configuration section
	info	The parameter destription
	str	A string describing the values

This takes a string from the commandline and stores it in the section.

Todo:

Document syntax for all parameter types

void bg_cfg_section_get_parameter	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	info,
		bg_parameter_value_t *	value
	)

Read a value from the section.

Parameters:

	section	The configuration section
	info	The parameter destription
	value	The value will be stored here

If the value does not exist in the section, it is created from the parameter description.

void bg_cfg_section_delete_subsection	(	bg_cfg_section_t *	section,
		bg_cfg_section_t *	subsection
	)

Delete a subsection.

Parameters:

	section	The configuration section
	subsection	The child section to be deleten

If the subsection if no child of section, this function does nothing.

void bg_cfg_section_set_parameter_int	(	bg_cfg_section_t *	section,
		const char *	name,
		int	value
	)

Store an integer value in a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Value to be stored

void bg_cfg_section_set_parameter_float	(	bg_cfg_section_t *	section,
		const char *	name,
		float	value
	)

Store a float value in a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Value to be stored

void bg_cfg_section_set_parameter_string	(	bg_cfg_section_t *	section,
		const char *	name,
		const char *	value
	)

Store a string value in a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Value to be stored

void bg_cfg_section_set_parameter_time	(	bg_cfg_section_t *	section,
		const char *	name,
		gavl_time_t	value
	)

Store a time value in a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Value to be stored

int bg_cfg_section_get_parameter_int	(	bg_cfg_section_t *	section,
		const char *	name,
		int *	value
	)

Get an integer value from a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Returns value

Returns:

1 if entry was available, 0 else.

int bg_cfg_section_get_parameter_float	(	bg_cfg_section_t *	section,
		const char *	name,
		float *	value
	)

Get an float value from a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Returns value

Returns:

1 if entry was available, 0 else.

int bg_cfg_section_get_parameter_string	(	bg_cfg_section_t *	section,
		const char *	name,
		const char **	value
	)

Get an string value from a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Returns value

Returns:

1 if entry was available, 0 else.

int bg_cfg_section_get_parameter_time	(	bg_cfg_section_t *	section,
		const char *	name,
		gavl_time_t *	value
	)

Get an time value from a section.

Parameters:

	section	The configuration section
	name	Name of the entry
	value	Returns value

Returns:

1 if entry was available, 0 else.

void bg_cfg_section_apply	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	parameters,
		bg_set_parameter_func_t	func,
		void *	callback_data
	)

Send all parameters to a module.

Parameters:

	section	The configuration section
	parameters	Parameter array
	func	Function to be called
	callback_data	First argument passed to func

This function iterates though all parameters and calls func with the stored values. It is the main function to transfer data from the section to a module.

void bg_cfg_section_apply_noterminate	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	infos,
		bg_set_parameter_func_t	func,
		void *	callback_data
	)

Send all parameters to a module without terminating.

Parameters:

	section	The configuration section
	infos	Parameter array
	func	Function to be called
	callback_data	First argument passed to func

This function works like bg_cfg_section_apply but doesn't call func with a NULL name argument at the end.

void bg_cfg_section_get	(	bg_cfg_section_t *	section,
		const bg_parameter_info_t *	parameters,
		bg_get_parameter_func_t	func,
		void *	callback_data
	)

Get parameters from a module.

Parameters:

	section	The configuration section
	parameters	Parameter array
	func	Function to be called
	callback_data	First argument passed to func

This function iterates though all parameters and calls func with the stored values. It is the main function to transfer data from the module to a section. It is used only, if the module has parameters, which are changed internally.

int bg_cfg_section_has_subsection	(	bg_cfg_section_t *	section,
		const char *	name
	)

Qurey if a child section is available.

Parameters:

	section	The configuration section
	name	Name of the child section

Returns:

1 if the child section is available, 0 else.