1 /*****************************************************************
2  * gmerlin - a general purpose multimedia framework and applications
3  *
4  * Copyright (c) 2001 - 2011 Members of the Gmerlin project
5  * gmerlin-general@lists.sourceforge.net
6  * http://gmerlin.sourceforge.net
7  *
8  * This program is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation, either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
20  * *****************************************************************/
21 
22 #ifndef __BG_CFG_REGISTRY_H_
23 #define __BG_CFG_REGISTRY_H_
24 
25 #include <gmerlin/parameter.h>
26 
27 /** \defgroup cfg_registry Configuration registry
28  *
29  *  This is a registry for configuration data, which stores the configuration
30  *  of a whole application. Each module has it's own section, sections can
31  *  have subsections. Inside the section, the configuration is stored as
32  *  name-value pairs.
33  *
34  *  You can save a registry in an xml-file and load it again. Furthermore,
35  *  sections can be attached to GUI-widgets. Special
36  *  routines are available to copy all values from/to a section by using
37  *  functions of type \ref bg_set_parameter_func_t and
38  *  \ref bg_get_parameter_func_t.
39  */
40 
41 /** \defgroup cfg_section Configuration section
42  *  \ingroup cfg_registry
43  *
44  *  Sections are nodes in the configuration tree. They can contain
45  *  name-value pairs and child sections. Usually, config sections are
46  *  kept within a configuration registry to store the applications
47  *  configuration data.
48  *
49  *  They can, however, be used indepentently from a registry as
50  *  universal data containers.
51  */
52 
53 /** \ingroup cfg_section
54  *  \brief Configuration section
55  *
56  *  Opaque container for configuration data and child sections
57  */
58 
59 typedef struct bg_cfg_section_s  bg_cfg_section_t;
60 
61 /** \ingroup cfg_registry
62  *  \brief Configuration registry
63  *
64  *  Opaque container for configuration sections.
65  */
66 
67 typedef struct bg_cfg_registry_s bg_cfg_registry_t;
68 
69 /** \ingroup cfg_registry
70  *  \brief Create an empty configuration registry
71  *  \returns A newly allocated and empty registry.
72  *
73  *  To free the registry, use \ref bg_cfg_registry_destroy.
74  */
75 
76 bg_cfg_registry_t * bg_cfg_registry_create();
77 
78 /** \ingroup cfg_registry
79  *  \brief Destroy configuration registry and free all associated memory
80  *  \param reg A configuration registry.
81  */
82 
83 void bg_cfg_registry_destroy(bg_cfg_registry_t * reg);
84 
85 /* cfg_xml.c */
86 
87 /** \ingroup cfg_registry
88  *  \brief Load a configuration registry from an xml- file
89  *  \param reg A configuration registry.
90  *  \param filename Name of the file
91  */
92 
93 void bg_cfg_registry_load(bg_cfg_registry_t * reg, const char * filename);
94 
95 /** \ingroup cfg_registry
96  *  \brief Save a configuration registry to an xml-file
97  *  \param reg A configuration registry.
98  *  \param filename Name of the file
99  */
100 
101 void bg_cfg_registry_save(bg_cfg_registry_t * reg, const char * filename);
102 
103 /** \ingroup cfg_registry
104  *  \brief Check if a registry has a section
105  *  \param reg A configuration registry.
106  *  \param name Name of the section
107  *  \returns 1 if the section is present, 0 else
108  */
109 
110 
111 int bg_cfg_registry_has_section(bg_cfg_registry_t * reg, const char * name);
112 
113 
114 /* The name and xml tag of the section must be set before */
115 
116 /** \ingroup cfg_section
117  *  \brief Convert a configuration section into a libxml2 node
118  *  \param section Configuration section
119  *  \param xml_section Pointer to the xml node for the section
120  *
121  *  See the libxml2 documentation for more infos
122  */
123 
124 void bg_cfg_section_2_xml(const bg_cfg_section_t * section, xmlNodePtr xml_section);
125 
126 /** \ingroup cfg_section
127  *  \brief Convert libxml2 node into a configuration section
128  *  \param xml_doc Pointer to the xml document
129  *  \param xml_section Pointer to the xml node for the section
130  *  \param section Configuration section
131  *
132  *  See the libxml2 documentation for more infos
133  */
134 
135 void bg_cfg_xml_2_section(xmlDocPtr xml_doc, xmlNodePtr xml_section,
136                           bg_cfg_section_t * section);
137 
138 /** \ingroup cfg_section
139  *  \brief Dump a config section to a file
140  *  \param section Configuration section
141  *  \param filename File to write this to
142  *
143  *  Used for debugging
144  */
145 
146 void bg_cfg_section_dump(bg_cfg_section_t * section, const char * filename);
147 
148 /*
149  *  Path looks like "section:subsection:subsubsection"
150  */
151 
152 /** \ingroup cfg_registry
153  *  \brief Find a section in the registry
154  *  \param reg A configuration registry
155  *  \param path The path
156  *  \returns Configuration section
157  *
158  *  Path looks like "section:subsection:subsubsection". If the section
159  *  does not exist, an empty section is created (including enevtually
160  *  missing parent sections).
161  */
162 
163 bg_cfg_section_t * bg_cfg_registry_find_section(bg_cfg_registry_t * reg,
164                                                 const char * path);
165 
166 /** \ingroup cfg_section
167  *  \brief Find a child of a section
168  *  \param section A configuration section
169  *  \param name name of the subsection
170  *  \returns Configuration section
171  *
172  *  If the child section does not exist, an empty section is created.
173  */
174 
175 bg_cfg_section_t * bg_cfg_section_find_subsection(bg_cfg_section_t * section,
176                                                   const char * name);
177 
178 /** \ingroup cfg_section
179  *  \brief Create a subsection at the specified position
180  *  \param section A configuration section
181  *  \param pos Position of the subsection (starting with 0)
182  *  \returns Configuration section
183  */
184 
185 bg_cfg_section_t * bg_cfg_section_create_subsection_at_pos(bg_cfg_section_t * section,
186                                                            int pos);
187 
188 /** \ingroup cfg_section
189  *  \brief Move a subsection to the specified position
190  *  \param section A configuration section
191  *  \param child Subsection to be moved
192  *  \param pos New position of the subsection (starting with 0)
193  */
194 
195 void bg_cfg_section_move_child(bg_cfg_section_t * section, bg_cfg_section_t * child,
196                                int pos);
197 
198 
199 /** \ingroup cfg_section
200  *  \brief Find a child of a section by index
201  *  \param section A configuration section
202  *  \param index Index (starting with 0)
203  *  \returns Configuration section
204  *
205  *  If the child section does not exist, NULL is returned.
206  */
207 
208 bg_cfg_section_t * bg_cfg_section_find_subsection_by_index(bg_cfg_section_t * section,
209                                                            int index);
210 
211 
212 /*
213  *  Create/destroy config sections
214  */
215 
216 /** \ingroup cfg_section
217  *  \brief Create an empty config section
218  *  \param name Name
219  *  \returns Configuration section
220  */
221 
222 bg_cfg_section_t * bg_cfg_section_create(const char * name);
223 
224 /** \ingroup cfg_section
225  *  \brief Create a config section from a parameter array
226  *  \param name Name
227  *  \param parameters A parameter array
228  *  \returns Configuration section
229  *
230  *  Creates a configuration section from a parameter array.
231  *  The values in the section are set from the defaults given in the
232  *  array.
233  */
234 
235 bg_cfg_section_t *
236 bg_cfg_section_create_from_parameters(const char * name,
237                                       const bg_parameter_info_t * parameters);
238 
239 /** \ingroup cfg_section
240  *  \brief Create items from a parameter info
241  *  \param section Configuration section
242  *  \param parameters A parameter array
243  *
244  *  This iterates through parameters and creates all missing
245  *  entries with the values set to their defaults
246  */
247 
248 
249 void bg_cfg_section_create_items(bg_cfg_section_t * section,
250                                  const bg_parameter_info_t * parameters);
251 
252 /** \ingroup cfg_section
253  *  \brief Destroy a config section
254  *  \param section Configuration section
255  */
256 
257 void bg_cfg_section_destroy(bg_cfg_section_t * section);
258 
259 /** \ingroup cfg_section
260  *  \brief Duplicate a configuration section
261  *  \param src Configuration section
262  *  \returns A newly allocated section with all values copied from src.
263  */
264 
265 bg_cfg_section_t * bg_cfg_section_copy(const bg_cfg_section_t * src);
266 
267 /** \ingroup cfg_section
268  *  \brief Set values in a configuration section from another section
269  *  \param src Source section
270  *  \param dst Destination section
271  *
272  *  This function iterates through all entries of src and copies the values
273  *  to dst. Values, which don't exist in dst, are created. The same is then
274  *  done for all children of src.
275  */
276 
277 void bg_cfg_section_transfer(bg_cfg_section_t * src, bg_cfg_section_t * dst);
278 
279 /** \ingroup cfg_section
280  *  \brief Like \ref bg_cfg_section_transfer but acts only on the subsections
281  *  \param src Source section
282  *  \param dst Destination section
283  */
284 
285 void bg_cfg_section_transfer_children(bg_cfg_section_t * src, bg_cfg_section_t * dst);
286 
287 /** \ingroup cfg_section
288  *  \brief Insert a reference to a section as child
289  *  \param section Configuration section
290  *  \param ref Child section to be added as reference
291  */
292 
293 void bg_cfg_section_add_ref(bg_cfg_section_t * section, bg_cfg_section_t * ref);
294 
295 /*
296  *  Get/Set section names
297  */
298 
299 /** \ingroup cfg_section
300  *  \brief Get the name of a configuration section
301  *  \param section Configuration section
302  *  \returns The name
303  */
304 
305 const char * bg_cfg_section_get_name(bg_cfg_section_t * section);
306 
307 /** \ingroup cfg_section
308  *  \brief Get the translated name of a configuration section
309  *  \param section Configuration section
310  *  \returns The translated name
311  *
312  *  The returned string must be freed by the caller
313  */
314 
315 char * bg_cfg_section_get_name_translated(bg_cfg_section_t * section);
316 
317 /** \ingroup cfg_section
318  *  \brief Set the name of a configuration section
319  *  \param section Configuration section
320  *  \param name The new name
321  *  \param gettext_domain First argument for bindtextdomain()
322  *  \param gettext_directory Second argument for bindtextdomain()
323 */
324 
325 void bg_cfg_section_set_name(bg_cfg_section_t * section, const char * name,
326                              const char * gettext_domain,
327                              const char * gettext_directory);
328 
329 /*
330  *  Get/Set values
331  */
332 
333 /** \ingroup cfg_section
334  *  \brief Store a value in the section
335  *  \param section The configuration section
336  *  \param info The parameter destription
337  *  \param value The value to be stored
338  *
339  *  If the value does not exist in the section, it is created
340  *  from the parameter description.
341  */
342 
343 void bg_cfg_section_set_parameter(bg_cfg_section_t * section,
344                                   const bg_parameter_info_t * info,
345                                   const bg_parameter_value_t * value);
346 
347 /** \ingroup cfg_section
348  *  \brief Set values from an option string
349  *  \param section The configuration section
350  *  \param info The parameter destription
351  *  \param str A string describing the values
352  *
353  *  This takes a string from the commandline and
354  *  stores it in the section.
355  *
356  *  \todo Document syntax for all parameter types
357  */
358 
359 int bg_cfg_section_set_parameters_from_string(bg_cfg_section_t * section,
360                                               const bg_parameter_info_t * info,
361                                               const char * str);
362 
363 /** \ingroup cfg_section
364  *  \brief Read a value from the section
365  *  \param section The configuration section
366  *  \param info The parameter destription
367  *  \param value The value will be stored here
368  *
369  *  If the value does not exist in the section, it is created
370  *  from the parameter description.
371  */
372 
373 void bg_cfg_section_get_parameter(bg_cfg_section_t * section,
374                                   const bg_parameter_info_t * info,
375                                   bg_parameter_value_t * value);
376 
377 /** \ingroup cfg_section
378  *  \brief Delete a subsection
379  *  \param section The configuration section
380  *  \param subsection The child section to be deleten
381  *
382  *  If the subsection if no child of section, this function does nothing.
383  */
384 
385 void bg_cfg_section_delete_subsection(bg_cfg_section_t * section,
386                                       bg_cfg_section_t * subsection);
387 
388 /** \ingroup cfg_section
389  *  \brief Delete all subsections
390  *  \param section The configuration section
391  */
392 
393 void bg_cfg_section_delete_subsections(bg_cfg_section_t * section);
394 
395 
396 /*
397  *  Type specific get/set functions, which don't require
398  *  an info structure
399  */
400 
401 /** \ingroup cfg_section
402  *  \brief Store an integer value in a section
403  *  \param section The configuration section
404  *  \param name Name of the entry
405  *  \param value Value to be stored
406  */
407 
408 void bg_cfg_section_set_parameter_int(bg_cfg_section_t * section,
409                                       const char * name, int value);
410 
411 /** \ingroup cfg_section
412  *  \brief Store a float value in a section
413  *  \param section The configuration section
414  *  \param name Name of the entry
415  *  \param value Value to be stored
416  */
417 
418 void bg_cfg_section_set_parameter_float(bg_cfg_section_t * section,
419                                         const char * name, float value);
420 
421 /** \ingroup cfg_section
422  *  \brief Store a string value in a section
423  *  \param section The configuration section
424  *  \param name Name of the entry
425  *  \param value Value to be stored
426  */
427 
428 void bg_cfg_section_set_parameter_string(bg_cfg_section_t * section,
429                                          const char * name, const char * value);
430 
431 /** \ingroup cfg_section
432  *  \brief Store a time value in a section
433  *  \param section The configuration section
434  *  \param name Name of the entry
435  *  \param value Value to be stored
436  */
437 
438 void bg_cfg_section_set_parameter_time(bg_cfg_section_t * section,
439                                        const char * name, gavl_time_t value);
440 
441 /* Get parameter values, return 0 if no such entry */
442 
443 /** \ingroup cfg_section
444  *  \brief Get an integer value from a section
445  *  \param section The configuration section
446  *  \param name Name of the entry
447  *  \param value Returns value
448  *  \returns 1 if entry was available, 0 else.
449  */
450 
451 int bg_cfg_section_get_parameter_int(bg_cfg_section_t * section,
452                                       const char * name, int * value);
453 
454 /** \ingroup cfg_section
455  *  \brief Get an float value from a section
456  *  \param section The configuration section
457  *  \param name Name of the entry
458  *  \param value Returns value
459  *  \returns 1 if entry was available, 0 else.
460  */
461 
462 int bg_cfg_section_get_parameter_float(bg_cfg_section_t * section,
463                                        const char * name, float * value);
464 
465 /** \ingroup cfg_section
466  *  \brief Get an string value from a section
467  *  \param section The configuration section
468  *  \param name Name of the entry
469  *  \param value Returns value
470  *  \returns 1 if entry was available, 0 else.
471  */
472 
473 int bg_cfg_section_get_parameter_string(bg_cfg_section_t * section,
474                                         const char * name, const char ** value);
475 
476 /** \ingroup cfg_section
477  *  \brief Get an time value from a section
478  *  \param section The configuration section
479  *  \param name Name of the entry
480  *  \param value Returns value
481  *  \returns 1 if entry was available, 0 else.
482  */
483 
484 int bg_cfg_section_get_parameter_time(bg_cfg_section_t * section,
485                                       const char * name, gavl_time_t * value);
486 
487 
488 /* Apply all values found in the parameter info */
489 
490 /** \ingroup cfg_section
491  *  \brief Send all parameters to a module
492  *  \param section The configuration section
493  *  \param parameters Parameter array
494  *  \param func Function to be called
495  *  \param callback_data First argument passed to func
496  *
497  *  This function iterates though all parameters and calls
498  *  func with the stored values. It is the main function to transfer
499  *  data from the section to a module.
500  */
501 
502 void bg_cfg_section_apply(bg_cfg_section_t * section,
503                           const bg_parameter_info_t * parameters,
504                           bg_set_parameter_func_t func,
505                           void * callback_data);
506 
507 /** \ingroup cfg_section
508  *  \brief Send all parameters to a module without terminating
509  *  \param section The configuration section
510  *  \param infos Parameter array
511  *  \param func Function to be called
512  *  \param callback_data First argument passed to func
513  *
514  *  This function works like \ref bg_cfg_section_apply but doesn't
515  *  call func with a NULL name argument at the end.
516  */
517 
518 void bg_cfg_section_apply_noterminate(bg_cfg_section_t * section,
519                                       const bg_parameter_info_t * infos,
520                                       bg_set_parameter_func_t func,
521                                       void * callback_data);
522 
523 /** \ingroup cfg_section
524  *  \brief Get parameters from a module
525  *  \param section The configuration section
526  *  \param parameters Parameter array
527  *  \param func Function to be called
528  *  \param callback_data First argument passed to func
529  *
530  *  This function iterates though all parameters and calls
531  *  func with the stored values. It is the main function to transfer
532  *  data from the module to a section. It is used only, if the module
533  *  has parameters, which are changed internally.
534  */
535 
536 void bg_cfg_section_get(bg_cfg_section_t * section,
537                         const bg_parameter_info_t * parameters,
538                         bg_get_parameter_func_t func,
539                         void * callback_data);
540 
541 /** \ingroup cfg_section
542  *  \brief Qurey if a child section is available
543  *  \param section The configuration section
544  *  \param name Name of the child section
545  *  \returns 1 if the child section is available, 0 else.
546  */
547 
548 int bg_cfg_section_has_subsection(bg_cfg_section_t * section,
549                                   const char * name);
550 
551 /** \ingroup cfg_section
552  *  \brief Restore default values of a section
553  *  \param section The configuration section
554  *  \param info Parameter info
555  */
556 
557 void bg_cfg_section_restore_defaults(bg_cfg_section_t * section,
558                                      const bg_parameter_info_t * info);
559 
560 
561 #endif /* __BG_CFG_REGISTRY_H_ */
562