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