gmerlin
Typedefs | Functions
Configuration section

Typedefs

typedef struct bg_cfg_section_s bg_cfg_section_t
 Configuration section. More...
 

Functions

void bg_cfg_section_2_xml (const bg_cfg_section_t *section, xmlNodePtr xml_section)
 Convert a configuration section into a libxml2 node. More...
 
void bg_cfg_xml_2_section (xmlDocPtr xml_doc, xmlNodePtr xml_section, bg_cfg_section_t *section)
 Convert libxml2 node into a configuration section. More...
 
void bg_cfg_section_dump (bg_cfg_section_t *section, const char *filename)
 Dump a config section to a file. More...
 
bg_cfg_section_tbg_cfg_section_find_subsection (bg_cfg_section_t *section, const char *name)
 Find a child of a section. More...
 
bg_cfg_section_tbg_cfg_section_create_subsection_at_pos (bg_cfg_section_t *section, int pos)
 Create a subsection at the specified position. More...
 
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. More...
 
bg_cfg_section_tbg_cfg_section_find_subsection_by_index (bg_cfg_section_t *section, int index)
 Find a child of a section by index. More...
 
bg_cfg_section_tbg_cfg_section_create (const char *name)
 Create an empty config section. More...
 
bg_cfg_section_tbg_cfg_section_create_from_parameters (const char *name, const bg_parameter_info_t *parameters)
 Create a config section from a parameter array. More...
 
void bg_cfg_section_create_items (bg_cfg_section_t *section, const bg_parameter_info_t *parameters)
 Create items from a parameter info. More...
 
void bg_cfg_section_destroy (bg_cfg_section_t *section)
 Destroy a config section. More...
 
bg_cfg_section_tbg_cfg_section_copy (const bg_cfg_section_t *src)
 Duplicate a configuration section. More...
 
void bg_cfg_section_transfer (bg_cfg_section_t *src, bg_cfg_section_t *dst)
 Set values in a configuration section from another section. More...
 
void bg_cfg_section_transfer_children (bg_cfg_section_t *src, bg_cfg_section_t *dst)
 Like bg_cfg_section_transfer but acts only on the subsections. More...
 
void bg_cfg_section_add_ref (bg_cfg_section_t *section, bg_cfg_section_t *ref)
 Insert a reference to a section as child. More...
 
const char * bg_cfg_section_get_name (bg_cfg_section_t *section)
 Get the name of a configuration section. More...
 
char * bg_cfg_section_get_name_translated (bg_cfg_section_t *section)
 Get the translated name of a configuration section. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void bg_cfg_section_delete_subsection (bg_cfg_section_t *section, bg_cfg_section_t *subsection)
 Delete a subsection. More...
 
void bg_cfg_section_delete_subsections (bg_cfg_section_t *section)
 Delete all subsections. More...
 
void bg_cfg_section_set_parameter_int (bg_cfg_section_t *section, const char *name, int value)
 Store an integer value in a section. More...
 
void bg_cfg_section_set_parameter_float (bg_cfg_section_t *section, const char *name, float value)
 Store a float value in a section. More...
 
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. More...
 
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. More...
 
int bg_cfg_section_get_parameter_int (bg_cfg_section_t *section, const char *name, int *value)
 Get an integer value from a section. More...
 
int bg_cfg_section_get_parameter_float (bg_cfg_section_t *section, const char *name, float *value)
 Get an float value from a section. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int bg_cfg_section_has_subsection (bg_cfg_section_t *section, const char *name)
 Qurey if a child section is available. More...
 
void bg_cfg_section_restore_defaults (bg_cfg_section_t *section, const bg_parameter_info_t *info)
 Restore default values of a section. More...
 

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 ( const bg_cfg_section_t section,
xmlNodePtr  xml_section 
)

Convert a configuration section into a libxml2 node.

Parameters
sectionConfiguration section
xml_sectionPointer 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_docPointer to the xml document
xml_sectionPointer to the xml node for the section
sectionConfiguration section

See the libxml2 documentation for more infos

void bg_cfg_section_dump ( bg_cfg_section_t section,
const char *  filename 
)

Dump a config section to a file.

Parameters
sectionConfiguration section
filenameFile to write this to

Used for debugging

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

Find a child of a section.

Parameters
sectionA configuration section
namename 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
sectionA configuration section
posPosition 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
sectionA configuration section
childSubsection to be moved
posNew 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
sectionA configuration section
indexIndex (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
nameName
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
nameName
parametersA 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
sectionConfiguration section
parametersA 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
sectionConfiguration section
bg_cfg_section_t* bg_cfg_section_copy ( const bg_cfg_section_t src)

Duplicate a configuration section.

Parameters
srcConfiguration 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
srcSource section
dstDestination 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.

void bg_cfg_section_transfer_children ( bg_cfg_section_t src,
bg_cfg_section_t dst 
)

Like bg_cfg_section_transfer but acts only on the subsections.

Parameters
srcSource section
dstDestination section
void bg_cfg_section_add_ref ( bg_cfg_section_t section,
bg_cfg_section_t ref 
)

Insert a reference to a section as child.

Parameters
sectionConfiguration section
refChild section to be added as reference
const char* bg_cfg_section_get_name ( bg_cfg_section_t section)

Get the name of a configuration section.

Parameters
sectionConfiguration 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
sectionConfiguration 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
sectionConfiguration section
nameThe new name
gettext_domainFirst argument for bindtextdomain()
gettext_directorySecond 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
sectionThe configuration section
infoThe parameter destription
valueThe 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
sectionThe configuration section
infoThe parameter destription
strA 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
sectionThe configuration section
infoThe parameter destription
valueThe 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
sectionThe configuration section
subsectionThe child section to be deleten

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

void bg_cfg_section_delete_subsections ( bg_cfg_section_t section)

Delete all subsections.

Parameters
sectionThe configuration section
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
sectionThe configuration section
nameName of the entry
valueValue 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
sectionThe configuration section
nameName of the entry
valueValue 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
sectionThe configuration section
nameName of the entry
valueValue 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
sectionThe configuration section
nameName of the entry
valueValue 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
sectionThe configuration section
nameName of the entry
valueReturns 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
sectionThe configuration section
nameName of the entry
valueReturns 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
sectionThe configuration section
nameName of the entry
valueReturns 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
sectionThe configuration section
nameName of the entry
valueReturns 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
sectionThe configuration section
parametersParameter array
funcFunction to be called
callback_dataFirst 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
sectionThe configuration section
infosParameter array
funcFunction to be called
callback_dataFirst 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
sectionThe configuration section
parametersParameter array
funcFunction to be called
callback_dataFirst 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
sectionThe configuration section
nameName of the child section
Returns
1 if the child section is available, 0 else.
void bg_cfg_section_restore_defaults ( bg_cfg_section_t section,
const bg_parameter_info_t info 
)

Restore default values of a section.

Parameters
sectionThe configuration section
infoParameter info