1 /* 2 INI LIBRARY 3 4 Header file for reading configuration from INI file 5 and storing as a collection. 6 7 Copyright (C) Dmitri Pal <dpal@redhat.com> 2009 8 9 INI Library is free software: you can redistribute it and/or modify 10 it under the terms of the GNU Lesser General Public License as published by 11 the Free Software Foundation, either version 3 of the License, or 12 (at your option) any later version. 13 14 INI Library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public License 20 along with INI Library. If not, see <http://www.gnu.org/licenses/>. 21 */ 22 23 #ifndef INI_CONFIG_H 24 #define INI_CONFIG_H 25 26 #include <sys/types.h> 27 #include <sys/stat.h> 28 #include <unistd.h> 29 #include <limits.h> 30 #include <stdio.h> 31 #include "collection.h" 32 33 /** @mainpage The INI configuration interface 34 * 35 * The goal of the this interface is to allow applications 36 * to read configuration from the INI file. 37 * 38 * So why yet another library to read data from INI file? 39 * As we started the SSSD project we looked around for a 40 * open source library that would meet the following 41 * requirements: 42 * - Is written in C (not C++) 43 * - Is lightweight. 44 * - Has an live community. 45 * - Supported on multiple platforms . 46 * - Can evolve as we build SSSD solution. 47 * - Can deal with different types of values including arrays. 48 * - Can deal with sections that are related to each other 49 * and can form a hierarchy of sections. 50 * - Has a compatible license we can use. 51 * 52 * We have seen several solutions but none was able to address our 53 * requirements fully. As a result we started developing our own 54 * INI parsing library. It is currently stable, however there is 55 * a list of the enhancements that we eventually plan to implement. 56 * One of the most interesting future features is the grammar 57 * validation utility. It is targeted at helping to diagnose 58 * a misconfiguration. 59 * 60 * Currently INI parser allows reading and merging INI files 61 * and getting a resulting configuration in one object. 62 * 63 * One of the main differences of this interface is that 64 * the library is created with the idea of reading the configuration 65 * data not managing it. Thus currently you will not find 66 * any function that alters the configuration data read from the files. 67 * There is a set of proposed enhancements to be able to manipulate 68 * the configuration data and save it back but there have been no real 69 * driver for it. This API is focused on letting applications read data 70 * from a file (or files) and interpret it, not to generate configuration 71 * files. There are all sorts of different tools that already do that. 72 * 73 * The INI configuration interface uses COLLECTION (see libcollection 74 * interface) to store data internally. 75 * 76 * Concepts: 77 * - The INI file consists of the key value pairs. 78 * - The keys and values are separated by the equal sign. 79 * The spaces around equal sign are trimmed. Everything before the equal 80 * sign is the key, everything after is the value. 81 * - Comments are the lines that start with ";" or "#" in the first 82 * position of the line. 83 * - Library currently does not support multi-line values. 84 * - The keys and values are read and stored in the internal 85 * collection. 86 * - More than one file can constitute the configuration for the application. 87 * For example there can be a generic file in the /etc that 88 * contains configuration for all the applications of this class running 89 * on the box and then there might be a special file 90 * with parameters specific for the application in the 91 * /etc/whatever.d directory. Interface allows reading 92 * both files in one call. The specific configuration for application 93 * will overwrite the generic one. 94 * - If there is no section in the file or there are key value pairs 95 * declared before the first section those pairs will be placed into 96 * the default section. 97 * - The values are treated as strings. Spaces are trimmed at the beginning 98 * and the end of the value. The value ends at the end of the line. 99 * If values is too long an error will be returned. 100 * - Parsing of the values happens when the caller tries to interpret 101 * the value. The caller can use different functions to do this. 102 * The value can be treated as numeric, logical, string, binary, 103 * array of strings or array of numbers. In case of arrays the functions 104 * accept separators that will be used to slice the value into the array 105 * elements. 106 * - If there is any error parsing the section and key values it can be 107 * intercepted by the caller. There are different modes that the library 108 * supports regarding error handling. See details in the description 109 * of the individual functions. 110 */ 111 112 /** 113 * @defgroup ini_config INI configuration interface 114 * @{ 115 */ 116 117 /** 118 * @defgroup constants Constants 119 * @{ 120 */ 121 122 /** 123 * @brief Name of the default section. 124 * 125 * This is the name of the implied section where orphan key-value 126 * pairs will be put. 127 */ 128 #define INI_DEFAULT_SECTION "default" 129 130 /** 131 * @defgroup classes Collection classes 132 * 133 * INI uses COLLECTION library to store data. 134 * It creates different objects with implied internal structure. 135 * To be able to validate the objects 136 * it is a good practice to define a class for each type of 137 * the object. 138 * 139 * This section contains constants that define 140 * internal collection classes used by INI interface. 141 * They are exposed so that if you use collection for 142 * other purposes you can make sure that the object classes 143 * do not overlap. It is a good practice to avoid 144 * them overlapping. Non-overlapping class space 145 * would make internal type checking more effective 146 * so that if an object of the wrong class is passed to 147 * some interface the interface would be able to 148 * check and detect an error. 149 * 150 * @{ 151 */ 152 /** @brief Base for the class definitions. */ 153 #define COL_CLASS_INI_BASE 20000 154 /** 155 * @brief Class for the configuration object. 156 * 157 * The configuration object consists of the collection 158 * of collections where each sub collection is a section. 159 * Application however should not assume that this always 160 * be the case. Use only INI interface functions 161 * get data from the configuration object. 162 * Do not use the raw collection interface to get 163 * data. 164 */ 165 #define COL_CLASS_INI_CONFIG COL_CLASS_INI_BASE + 0 166 /** 167 * @brief A one level collection of key value pairs 168 * where values are always strings. 169 */ 170 #define COL_CLASS_INI_SECTION COL_CLASS_INI_BASE + 1 171 /** 172 * @brief A one level collection of parse errors. 173 * 174 * Collection stores \ref parse_error structures. 175 */ 176 #define COL_CLASS_INI_PERROR COL_CLASS_INI_BASE + 2 177 /** 178 * @brief Collection of error collections. 179 * 180 * When multiple files are read during one call 181 * each file has its own set of parsing errors 182 * and warnings. This is the collection 183 * of such sets. 184 */ 185 #define COL_CLASS_INI_PESET COL_CLASS_INI_BASE + 3 186 187 /** 188 * @brief Collection of metadata. 189 * 190 * Collection that stores metadata. 191 */ 192 #define COL_CLASS_INI_META COL_CLASS_INI_BASE + 4 193 /** 194 * @} 195 */ 196 197 /** 198 * @defgroup errorlevel Error tolerance constants 199 * 200 * Constants in this section define what to do if 201 * error or warning encountered while parsing the INI file. 202 * 203 * @{ 204 */ 205 /** @brief Fail if any problem is detected. */ 206 #define INI_STOP_ON_ANY 0 207 /** @brief Best effort - do not fail. */ 208 #define INI_STOP_ON_NONE 1 209 /** @brief Fail on errors only. */ 210 #define INI_STOP_ON_ERROR 2 211 212 /** 213 * @} 214 */ 215 216 /** 217 * @defgroup parseerr Parsing errors and warnings 218 * 219 * @{ 220 */ 221 /** @brief Line is too long (Error). */ 222 #define ERR_LONGDATA 1 223 /** @brief No closing bracket in section definition (Error). */ 224 #define ERR_NOCLOSESEC 2 225 /** @brief Section name is missing (Error). */ 226 #define ERR_NOSECTION 3 227 /** @brief Section name too long (Error). */ 228 #define ERR_SECTIONLONG 4 229 /** @brief No equal sign (Error). */ 230 #define ERR_NOEQUAL 5 231 /** @brief No key before equal sign (Error). */ 232 #define ERR_NOKEY 6 233 /** @brief Key is too long (Error). */ 234 #define ERR_LONGKEY 7 235 /** @brief Failed to read line (Error). */ 236 #define ERR_READ 8 237 /** @brief Line starts with space when it should not (Error). */ 238 #define ERR_SPACE 9 239 240 /** @brief Size of the error array. */ 241 #define ERR_MAXPARSE ERR_SPACE 242 243 /** 244 * @} 245 */ 246 247 /** 248 * @defgroup gramerr Grammar errors and warnings 249 * 250 * Placeholder for now. Reserved for future use. 251 * 252 * @{ 253 */ 254 #define ERR_MAXGRAMMAR 0 255 /** 256 * @} 257 */ 258 259 /** 260 * @defgroup valerr Validation errors and warnings 261 * 262 * Placeholder for now. Reserved for future use. 263 * 264 * @{ 265 */ 266 #define ERR_MAXVALID 0 267 268 269 /** 270 * @} 271 */ 272 273 /** 274 * @defgroup accesscheck Access control check flags 275 * 276 * @{ 277 */ 278 279 /** 280 * @brief Validate access mode 281 * 282 * If this flag is specified the mode parameter 283 * will be matched against the permissions set on the file 284 * using the provided mask. 285 */ 286 #define INI_ACCESS_CHECK_MODE 0x00000001 287 288 /** 289 * @brief Validate uid 290 * 291 * Provided uid will be checked against uid 292 * of the file. 293 */ 294 #define INI_ACCESS_CHECK_UID 0x00000002 295 296 /** 297 * @brief Validate gid 298 * 299 * Provided gid will be checked against gid 300 * of the file. 301 */ 302 #define INI_ACCESS_CHECK_GID 0x00000004 303 304 /** 305 * @} 306 */ 307 308 309 /** 310 * @} 311 */ 312 313 /** 314 * @defgroup structures Structures 315 * @{ 316 */ 317 318 /** @brief Structure that holds error number and 319 * line number for the encountered error. 320 */ 321 struct parse_error { 322 unsigned line; 323 int error; 324 }; 325 326 327 /** 328 * @} 329 */ 330 331 /** 332 * @defgroup metadata Meta data 333 * 334 * Metadata is a collection of a similar structure as any ini file. 335 * The difference is that there are some predefined sections 336 * and attributes inside these sections. 337 * Using meta flags one can specify what section he is interested 338 * in including into the meta data. If a flag for a corresponding 339 * meta data section is specified the data for this section will 340 * be included into the meta data collection. The caller can then 341 * use meta data collection to get items from it and then get 342 * a specific value using a corresponding conversion function. 343 * 344 * Think about the meta data as an INI file that looks like this: 345 * 346 * <b> 347 * [ACCESS] 348 * - uid = <i>\<ini file owner uid\></i> 349 * - gid = <i>\<ini file group gid\></i> 350 * - perm = <i>\<permissions word\></i> 351 * - name = <i>\<file name\></i> 352 * - created = <i>\<time stamp\></i> 353 * - modified = <i>\<time stamp\></i> 354 * - ... 355 * 356 * [ERROR] 357 * - read_error = <i><file open error if any\></i> 358 * - ... 359 * 360 * [<i>TBD</i>] 361 * - ... 362 * 363 * </b> 364 * 365 * The names of the keys and sections provide an example 366 * of how the meta data is structured. Look information 367 * about specific sections and available keys in this manual 368 * to get the exact set of currently supported sections 369 * and keys. 370 * 371 * @{ 372 */ 373 374 /** 375 * @brief Collect only meta data. 376 * 377 * Special flag that indicates that only meta data 378 * needs to be collected. No parsing should be performed. 379 * 380 */ 381 #define INI_META_ACTION_NOPARSE 0x10000000 382 383 /** 384 * @defgroup metasection Meta data section names 385 * 386 * @{ 387 */ 388 389 /** 390 * @brief Meta data section that stores file access information 391 * and ownership. 392 */ 393 #define INI_META_SEC_ACCESS "ACCESS" 394 395 /** 396 * @brief Meta data "access" section flag to include access section 397 * into the output. 398 */ 399 #define INI_META_SEC_ACCESS_FLAG 0x00000001 400 401 402 /** 403 * @defgroup metaaccesskeys Key names available in the "ACCESS" section 404 * 405 * @{ 406 * 407 */ 408 409 /** 410 * @brief The value for this key will store user ID of the INI file owner. 411 * 412 */ 413 #define INI_META_KEY_UID "uid" 414 415 /** 416 * @brief The value for this key will store group ID of the INI file owner. 417 * 418 */ 419 #define INI_META_KEY_GID "gid" 420 421 /** 422 * @brief The value for this key will store INI file access permissions. 423 * 424 */ 425 #define INI_META_KEY_PERM "perm" 426 427 /** 428 * @brief The value for this key will store INI file device ID. 429 * 430 */ 431 #define INI_META_KEY_DEV "dev" 432 433 /** 434 * @brief The value for this key will store INI file inode number. 435 * 436 */ 437 #define INI_META_KEY_INODE "inode" 438 439 /** 440 * @brief The value for this key will store INI file modification time stamp. 441 * 442 */ 443 #define INI_META_KEY_MODIFIED "modified" 444 445 /** 446 * @brief The value for this key will store INI file full name. 447 * 448 */ 449 #define INI_META_KEY_NAME "name" 450 451 /** 452 * @} 453 */ 454 455 /** 456 * @brief Meta data section that stores error related information. 457 */ 458 #define INI_META_SEC_ERROR "ERROR" 459 460 /** 461 * @brief Meta data "error" section flag to include access section 462 * into the output. 463 */ 464 #define INI_META_SEC_ERROR_FLAG 0x00000002 465 466 467 /** 468 * @defgroup metaerrorkeys Key names available in the "ERROR" section 469 * 470 * @{ 471 * 472 */ 473 474 /** 475 * @brief The value for this key will store read error when file was opened. 476 * 477 * If file was opened by caller first but this section was requested 478 * the value will be zero. 479 */ 480 #define INI_META_KEY_READ_ERROR "read_error" 481 482 483 /** 484 * @} 485 */ 486 487 /** 488 * @} 489 */ 490 491 /** 492 * @} 493 */ 494 495 496 /** 497 * @defgroup functions Functions 498 * @{ 499 */ 500 501 502 /** 503 * @brief Read configuration information from a file. 504 * 505 * @param[in] application Name of the application, 506 * will be used as name of 507 * the collection. 508 * @param[in] config_filename Name of the config file, 509 * if NULL the configuration 510 * collection will be empty. 511 * @param[out] ini_config If *ini_config is NULL 512 * a new ini object will be 513 * allocated, otherwise 514 * the one that is pointed to 515 * will be updated. 516 * @param[in] error_level Break for errors, warnings 517 * or best effort (don't break). 518 * @param[out] error_list List of errors for the file 519 * detected during parsing. 520 * 521 * @return 0 - Success. 522 * @return EINVAL - Invalid parameter. 523 * @return EMOMEM - No memory. 524 * @return Any error returned by fopen(). 525 * 526 */ 527 int config_from_file(const char *application, 528 const char *config_filename, 529 struct collection_item **ini_config, 530 int error_level, 531 struct collection_item **error_list); 532 533 /** 534 * @brief Read configuration information from a file descriptor. 535 * 536 * @param[in] application Name of the application, 537 * will be used as name of 538 * the collection. 539 * @param[in] fd Previously opened file 540 * descriptor for the config file. 541 * @param[in] config_source Name of the file being parsed, 542 * for use when printing the error 543 * list. 544 * @param[out] ini_config If *ini_config is NULL 545 * a new ini object will be 546 * allocated, otherwise 547 * the one that is pointed to 548 * will be updated. 549 * @param[in] error_level Break for errors, warnings 550 * or best effort (don't break). 551 * @param[out] error_list List of errors for the file 552 * detected during parsing. 553 * 554 * @return 0 - Success. 555 * @return EMOMEM - No memory. 556 * @return EINVAL - Invalid parameter. 557 * 558 */ 559 int config_from_fd(const char *application, 560 int fd, 561 const char *config_source, 562 struct collection_item **ini_config, 563 int error_level, 564 struct collection_item **error_list); 565 566 567 568 /** 569 * @brief Read configuration information from a file with 570 * additional meta data. 571 * 572 * Meta data consists of addition information about 573 * the file for example when it was created 574 * or who is the owner. For the detailed description 575 * of the meta data content and structure see 576 * \ref metadata "meta data" section. 577 * 578 * If the metadata argument is not NULL 579 * the calling function MUST always free meta data since it can 580 * be allocated even if the function returned error. 581 * 582 * @param[in] application Name of the application, 583 * will be used as name of 584 * the collection. 585 * @param[in] config_filename Name of the config file, 586 * if NULL the configuration 587 * collection will be empty. 588 * @param[out] ini_config If *ini_config is NULL 589 * a new ini object will be 590 * allocated, otherwise 591 * the one that is pointed to 592 * will be updated. 593 * @param[in] error_level Break for errors, warnings 594 * or best effort (don't break). 595 * @param[out] error_list List of errors for the file 596 * detected during parsing. 597 * @param[in] metaflags A bit mask of flags that define 598 * what kind of metadata should 599 * be collected. 600 * @param[out] metadata Collection of metadata 601 * values. See \ref metadata "meta data" 602 * section for more details. 603 * Can be NULL. 604 * 605 * @return 0 - Success. 606 * @return EINVAL - Invalid parameter. 607 * @return EMOMEM - No memory. 608 * @return Any error returned by fopen(). 609 * 610 * 611 */ 612 int config_from_file_with_metadata( 613 const char *application, 614 const char *config_filename, 615 struct collection_item **ini_config, 616 int error_level, 617 struct collection_item **error_list, 618 uint32_t metaflags, 619 struct collection_item **metadata); 620 621 622 /** 623 * @brief Read configuration information from a file descriptor 624 * with additional meta data. 625 * 626 * Meta data consists of addition information about 627 * the file for example when it was created 628 * or who is the owner. For the detailed description 629 * of the meta data content and structure see 630 * \ref metadata "meta data" section. 631 * 632 * If the metadata argument is not NULL 633 * the calling function MUST always free meta data since it can 634 * be allocated even if the function returned error. 635 * 636 * @param[in] application Name of the application, 637 * will be used as name of 638 * the collection. 639 * @param[in] fd Previously opened file 640 * descriptor for the config file. 641 * @param[in] config_source Name of the file being parsed, 642 * for use when printing the error 643 * list. 644 * @param[out] ini_config If *ini_config is NULL 645 * a new ini object will be 646 * allocated, otherwise 647 * the one that is pointed to 648 * will be updated. 649 * @param[in] error_level Break for errors, warnings 650 * or best effort (don't break). 651 * @param[out] error_list List of errors for the file 652 * detected during parsing. 653 * @param[in] metaflags A bit mask of flags that define 654 * what kind of metadata should 655 * be collected. 656 * @param[out] metadata Collection of metadata 657 * values. See \ref metadata "meta data" 658 * section for more details. 659 * Can be NULL. 660 * 661 * @return 0 - Success. 662 * @return EINVAL - Invalid parameter. 663 * @return EMOMEM - No memory. 664 * 665 */ 666 int config_from_fd_with_metadata( 667 const char *application, 668 int fd, 669 const char *config_source, 670 struct collection_item **ini_config, 671 int error_level, 672 struct collection_item **error_list, 673 uint32_t metaflags, 674 struct collection_item **metadata); 675 676 677 /** 678 * @brief Read default configuration file and then 679 * overwrite it with a specific one from the directory. 680 * 681 * @param[in] application Name of the application, 682 * will be used as name of 683 * the collection. 684 * @param[in] config_file Name of the configuration file, 685 * with default settings for all 686 * appplications. 687 * @param[in] config_dir Name of the directory where 688 * the configuration files for 689 * different applications reside. 690 * Function will look for file 691 * with the name constructed by 692 * appending ".ini" to the end of 693 * the "application" argument. 694 * @param[out] ini_config A new configuration object. 695 * @param[in] error_level Break for errors, warnings 696 * or best effort (don't break). 697 * @param[out] error_set Collection of error lists. 698 * One list per file. 699 * 700 * @return 0 - Success. 701 * @return EINVAL - Invalid parameter. 702 * @return EMOMEM - No memory. 703 * @return Any error returned by fopen(). 704 */ 705 int config_for_app(const char *application, 706 const char *config_file, 707 const char *config_dir, 708 struct collection_item **ini_config, 709 int error_level, 710 struct collection_item **error_set); 711 712 /** 713 * @brief Read default configuration file and then 714 * overwrite it with a specific one from the directory. 715 * 716 * If requested collect meta data for both. 717 * 718 * If the metadata argument is not NULL 719 * the calling function MUST always free meta data since it can 720 * be allocated even if the function returned error. 721 * 722 * @param[in] application Name of the application, 723 * will be used as name of 724 * the collection. 725 * @param[in] config_file Name of the configuration file, 726 * with default settings for all 727 * appplications. 728 * @param[in] config_dir Name of the directory where 729 * the configuration files for 730 * different applications reside. 731 * Function will look for file 732 * with the name constructed by 733 * appending ".ini" to the end of 734 * the "application" argument. 735 * @param[out] ini_config A new configuration object. 736 * @param[in] error_level Break for errors, warnings 737 * or best effort (don't break). 738 * @param[out] error_set Collection of error lists. 739 * One list per file. 740 * @param[in] metaflags A bit mask of flags that define 741 * what kind of metadata should 742 * be collected. 743 * @param[out] meta_default Collection of metadata 744 * values for the default common 745 * config file for all applications. 746 * See \ref metadata "meta data" 747 * section for more details. 748 * Can be NULL. 749 * @param[out] meta_appini Collection of metadata 750 * values for the application 751 * specific config file. 752 * See \ref metadata "meta data" 753 * section for more details. 754 * Can be NULL. 755 * 756 * @return 0 - Success. 757 * @return EINVAL - Invalid parameter. 758 * @return EMOMEM - No memory. 759 * @return Any error returned by fopen(). 760 */ 761 int config_for_app_with_metadata( 762 const char *application, 763 const char *config_file, 764 const char *config_dir, 765 struct collection_item **ini_config, 766 int error_level, 767 struct collection_item **error_set, 768 uint32_t metaflags, 769 struct collection_item **meta_default, 770 struct collection_item **meta_appini); 771 772 773 /** 774 * 775 * @brief Function to check ownership and permissions 776 * 777 * The function allow caller to make decision 778 * if the configuration file is from a trusted source 779 * or not. 780 * 781 * The flags control how to perform check. 782 * See \ref accesscheck "Access control check flags" 783 * section for more information. 784 * 785 * @param[in] metadata Meta data object. 786 * Can't be NULL. 787 * @param[in] flags How and what to check. 788 * Must be nonzero. 789 * @param[in] uid UID to check. 790 * @param[in] gid GID to check. 791 * @param[in] mode Mode to check. 792 * Only permission bits 793 * are used. 794 * @param[in] mask Which mode bits to check. 795 * If 0 all permision bits 796 * are checked. 797 * 798 * @return 0 - Success. 799 * @return EINVAL - Invalid parameter. 800 * @return EACCESS - File properties do not match provided 801 * access parameters. 802 */ 803 int config_access_check(struct collection_item *metadata, 804 uint32_t flags, 805 uid_t uid, 806 gid_t gid, 807 mode_t mode, 808 mode_t mask); 809 810 811 /** 812 * @brief Function compares two meta data objects 813 * 814 * Function compares two meta data objects 815 * to determine whether the configuration 816 * has changed since last time the meta data 817 * was collected. 818 * The function checks three things about the 819 * file: 820 * - time stamp 821 * - device ID 822 * - i-node 823 * If any of those changes function will indicate 824 * that configuration changed. 825 * 826 * @param[in] metadata Recent meta data object. 827 * @param[in] saved_metadata Previously saved meta 828 * data object. 829 * @param[out] changed Will be set to a nonzero value 830 * if the configuration has changed. 831 * 832 * @return 0 - No internal error 833 * @return EINVAL - Invalid argument 834 * @return ENOENT - Expected value is missing 835 * @return ENOMEM - No memory 836 */ 837 int config_changed(struct collection_item *metadata, 838 struct collection_item *saved_metadata, 839 int *changed); 840 841 /** 842 * @brief Function to free configuration object. 843 * 844 * @param[in] ini_config Configuration object. 845 * 846 */ 847 void free_ini_config(struct collection_item *ini_config); 848 849 /** 850 * @brief Function to free configuration errors. 851 * 852 * @param[in] error_set Configuration error set object. 853 * 854 */ 855 void free_ini_config_errors(struct collection_item *error_set); 856 857 858 /** 859 * @brief Function to free metadata. 860 * 861 * @param[in] metadata Configuration meta data object. 862 * 863 */ 864 void free_ini_config_metadata(struct collection_item *metadata); 865 866 867 /** 868 * @brief Print errors and warnings that were detected while parsing one file. 869 * 870 * @param[in] file File descriptor. 871 * @param[in] error_list List of the parsing errors. 872 * 873 */ 874 void print_file_parsing_errors(FILE *file, 875 struct collection_item *error_list); 876 877 878 /** 879 * @brief Print errors and warnings that were detected 880 * parsing configuration as a whole. 881 * 882 * Use this function to print results of the config_for_app() call. 883 * 884 * @param[in] file File descriptor. 885 * @param[in] error_set List of lists of the parsing errors. 886 * 887 */ 888 void print_config_parsing_errors(FILE *file, 889 struct collection_item *error_set); 890 891 /** 892 * @brief Get list of sections. 893 * 894 * Get list of sections from the configuration object 895 * as an array of strings. 896 * Function allocates memory for the array of the sections. 897 * Use \ref free_section_list() to free allocated memory. 898 * 899 * @param[in] ini_config Configuration object. 900 * @param[out] size If not NULL parameter will 901 * receive number of sections 902 * in the configuration. 903 * @param[out] error If not NULL parameter will 904 * receive the error code. 905 * 0 - Success. 906 * EINVAL - Invalid parameter. 907 * ENOMEM - No memory. 908 * 909 * @return Array of strings. 910 */ 911 char **get_section_list(struct collection_item *ini_config, 912 int *size, 913 int *error); 914 915 /** 916 * @brief Free list of sections. 917 * 918 * The section array created by \ref get_section_list() 919 * should be freed using this function. 920 * 921 * @param[in] section_list Array of strings returned by 922 * \ref get_section_list() function. 923 */ 924 void free_section_list(char **section_list); 925 926 /** 927 * @brief Get list of attributes. 928 * 929 * Get list of attributes in a section as an array of strings. 930 * Function allocates memory for the array of attributes. 931 * Use \ref free_attribute_list() to free allocated memory. 932 * 933 * @param[in] ini_config Configuration object. 934 * @param[in] section Section name. 935 * @param[out] size If not NULL parameter will 936 * receive number of attributes 937 * in the section. 938 * @param[out] error If not NULL parameter will 939 * receive the error code. 940 * 0 - Success. 941 * EINVAL - Invalid parameter. 942 * ENOMEM - No memory. 943 * 944 * @return Array of strings. 945 */ 946 char **get_attribute_list(struct collection_item *ini_config, 947 const char *section, 948 int *size, 949 int *error); 950 951 /** 952 * @brief Free list of attributes. 953 * 954 * The attribute array created by \ref get_attribute_list() 955 * should be freed using this function. 956 * 957 * @param[in] attr_list Array of strings returned by 958 * \ref get_attribute_list() function. 959 */ 960 void free_attribute_list(char **attr_list); 961 962 /** 963 * @brief Get a configuration item form the configuration. 964 * 965 * Check return error code first. If the function returns 966 * an error there is a serious problem. 967 * Then check if item is found. Function will set 968 * item parameter to NULL if no attribute with 969 * provided name is found in the collection. 970 * 971 * @param[in] section Section name. 972 * If NULL assumed default. 973 * @param[in] name Attribute name to find. 974 * @param[in] ini_config Configuration object to search. 975 * @param[out] item Element of configuration 976 * collection. 977 * Will be set to NULL if 978 * element with the given name 979 * is not found. 980 * @return 0 - Success. 981 * @return EINVAL - Invalid parameter. 982 * @return ENOMEM - No memory. 983 * 984 */ 985 int get_config_item(const char *section, 986 const char *name, 987 struct collection_item *ini_config, 988 struct collection_item **item); 989 990 /** 991 * @brief Convert item value to integer number. 992 * 993 * This is a conversion function. 994 * It converts the value read from the INI file 995 * and stored in the configuration item 996 * into an integer number. Any of the conversion 997 * functions can be used to try to convert the value 998 * stored as a string inside the item. 999 * The results can be different depending upon 1000 * how the caller tries to interpret the value. 1001 * If "strict" parameter is non zero the function will fail 1002 * if there are more characters after the last digit. 1003 * The value range is from INT_MIN to INT_MAX. 1004 * 1005 * @param[in] item Item to interpret. 1006 * It must be retrieved using 1007 * \ref get_config_item(). 1008 * @param[in] strict Fail the function if 1009 * the symbol after last digit 1010 * is not valid. 1011 * @param[in] def Default value to use if 1012 * conversion failed. 1013 * @param[out] error Variable will get the value 1014 * of the error code if 1015 * error happened. 1016 * Can be NULL. In this case 1017 * function does not set 1018 * the code. 1019 * Codes: 1020 * - 0 - Success. 1021 * - EINVAL - Argument is invalid. 1022 * - EIO - Conversion failed due 1023 * invalid characters. 1024 * - ERANGE - Value is out of range. 1025 * 1026 * @return Converted value. 1027 * In case of failure the function returns default value and 1028 * sets error code into the provided variable. 1029 */ 1030 int get_int_config_value(struct collection_item *item, 1031 int strict, 1032 int def, 1033 int *error); 1034 1035 /** 1036 * @brief Convert item value to long number. 1037 * 1038 * This is a conversion function. 1039 * It converts the value read from the INI file 1040 * and stored in the configuration item 1041 * into a long number. Any of the conversion 1042 * functions can be used to try to convert the value 1043 * stored as a string inside the item. 1044 * The results can be different depending upon 1045 * how the caller tries to interpret the value. 1046 * If "strict" parameter is non zero the function will fail 1047 * if there are more characters after the last digit. 1048 * The value range is from LONG_MIN to LONG_MAX. 1049 * 1050 * @param[in] item Item to interpret. 1051 * It must be retrieved using 1052 * \ref get_config_item(). 1053 * @param[in] strict Fail the function if 1054 * the symbol after last digit 1055 * is not valid. 1056 * @param[in] def Default value to use if 1057 * conversion failed. 1058 * @param[out] error Variable will get the value 1059 * of the error code if 1060 * error happened. 1061 * Can be NULL. In this case 1062 * function does not set 1063 * the code. 1064 * Codes: 1065 * - 0 - Success. 1066 * - EINVAL - Argument is invalid. 1067 * - EIO - Conversion failed due 1068 * invalid characters. 1069 * - ERANGE - Value is out of range. 1070 * 1071 * @return Converted value. 1072 * In case of failure the function returns default value and 1073 * sets error code into the provided variable. 1074 */ 1075 long get_long_config_value(struct collection_item *item, 1076 int strict, 1077 long def, 1078 int *error); 1079 1080 /** 1081 * @brief Convert item value to unsigned integer number. 1082 * 1083 * This is a conversion function. 1084 * It converts the value read from the INI file 1085 * and stored in the configuration item 1086 * into an unsigned integer number. Any of the conversion 1087 * functions can be used to try to convert the value 1088 * stored as a string inside the item. 1089 * The results can be different depending upon 1090 * how the caller tries to interpret the value. 1091 * If "strict" parameter is non zero the function will fail 1092 * if there are more characters after the last digit. 1093 * The value range is from 0 to UINT_MAX. 1094 * 1095 * @param[in] item Item to interpret. 1096 * It must be retrieved using 1097 * \ref get_config_item(). 1098 * @param[in] strict Fail the function if 1099 * the symbol after last digit 1100 * is not valid. 1101 * @param[in] def Default value to use if 1102 * conversion failed. 1103 * @param[out] error Variable will get the value 1104 * of the error code if 1105 * error happened. 1106 * Can be NULL. In this case 1107 * function does not set 1108 * the code. 1109 * Codes: 1110 * - 0 - Success. 1111 * - EINVAL - Argument is invalid. 1112 * - EIO - Conversion failed due 1113 * invalid characters. 1114 * - ERANGE - Value is out of range. 1115 * 1116 * @return Converted value. 1117 * In case of failure the function returns default value and 1118 * sets error code into the provided variable. 1119 */ 1120 unsigned get_unsigned_config_value(struct collection_item *item, 1121 int strict, 1122 unsigned def, 1123 int *error); 1124 1125 /** 1126 * @brief Convert item value to unsigned long number. 1127 * 1128 * This is a conversion function. 1129 * It converts the value read from the INI file 1130 * and stored in the configuration item 1131 * into an unsigned long number. Any of the conversion 1132 * functions can be used to try to convert the value 1133 * stored as a string inside the item. 1134 * The results can be different depending upon 1135 * how the caller tries to interpret the value. 1136 * If "strict" parameter is non zero the function will fail 1137 * if there are more characters after the last digit. 1138 * The value range is from 0 to ULONG_MAX. 1139 * 1140 * @param[in] item Item to interpret. 1141 * It must be retrieved using 1142 * \ref get_config_item(). 1143 * @param[in] strict Fail the function if 1144 * the symbol after last digit 1145 * is not valid. 1146 * @param[in] def Default value to use if 1147 * conversion failed. 1148 * @param[out] error Variable will get the value 1149 * of the error code if 1150 * error happened. 1151 * Can be NULL. In this case 1152 * function does not set 1153 * the code. 1154 * Codes: 1155 * - 0 - Success. 1156 * - EINVAL - Argument is invalid. 1157 * - EIO - Conversion failed due 1158 * invalid characters. 1159 * - ERANGE - Value is out of range. 1160 * 1161 * @return Converted value. 1162 * In case of failure the function returns default value and 1163 * sets error code into the provided variable. 1164 */ 1165 unsigned long get_ulong_config_value(struct collection_item *item, 1166 int strict, 1167 unsigned long def, 1168 int *error); 1169 1170 /** 1171 * @brief Convert item value to integer number. 1172 * 1173 * This is a conversion function. 1174 * It converts the value read from the INI file 1175 * and stored in the configuration item 1176 * into an int32_t number. Any of the conversion 1177 * functions can be used to try to convert the value 1178 * stored as a string inside the item. 1179 * The results can be different depending upon 1180 * how the caller tries to interpret the value. 1181 * If "strict" parameter is non zero the function will fail 1182 * if there are more characters after the last digit. 1183 * The value range is from INT_MIN to INT_MAX. 1184 * 1185 * @param[in] item Item to interpret. 1186 * It must be retrieved using 1187 * \ref get_config_item(). 1188 * @param[in] strict Fail the function if 1189 * the symbol after last digit 1190 * is not valid. 1191 * @param[in] def Default value to use if 1192 * conversion failed. 1193 * @param[out] error Variable will get the value 1194 * of the error code if 1195 * error happened. 1196 * Can be NULL. In this case 1197 * function does not set 1198 * the code. 1199 * Codes: 1200 * - 0 - Success. 1201 * - EINVAL - Argument is invalid. 1202 * - EIO - Conversion failed due 1203 * invalid characters. 1204 * - ERANGE - Value is out of range. 1205 * 1206 * @return Converted value. 1207 * In case of failure the function returns default value and 1208 * sets error code into the provided variable. 1209 */ 1210 int32_t get_int32_config_value(struct collection_item *item, 1211 int strict, 1212 int32_t def, 1213 int *error); 1214 1215 /** 1216 * @brief Convert item value to integer number. 1217 * 1218 * This is a conversion function. 1219 * It converts the value read from the INI file 1220 * and stored in the configuration item 1221 * into an uint32_t number. Any of the conversion 1222 * functions can be used to try to convert the value 1223 * stored as a string inside the item. 1224 * The results can be different depending upon 1225 * how the caller tries to interpret the value. 1226 * If "strict" parameter is non zero the function will fail 1227 * if there are more characters after the last digit. 1228 * The value range is from 0 to ULONG_MAX. 1229 * 1230 * @param[in] item Item to interpret. 1231 * It must be retrieved using 1232 * \ref get_config_item(). 1233 * @param[in] strict Fail the function if 1234 * the symbol after last digit 1235 * is not valid. 1236 * @param[in] def Default value to use if 1237 * conversion failed. 1238 * @param[out] error Variable will get the value 1239 * of the error code if 1240 * error happened. 1241 * Can be NULL. In this case 1242 * function does not set 1243 * the code. 1244 * Codes: 1245 * - 0 - Success. 1246 * - EINVAL - Argument is invalid. 1247 * - EIO - Conversion failed due 1248 * invalid characters. 1249 * - ERANGE - Value is out of range. 1250 * 1251 * @return Converted value. 1252 * In case of failure the function returns default value and 1253 * sets error code into the provided variable. 1254 */ 1255 uint32_t get_uint32_config_value(struct collection_item *item, 1256 int strict, 1257 uint32_t def, 1258 int *error); 1259 1260 /** 1261 * @brief Convert item value to integer number. 1262 * 1263 * This is a conversion function. 1264 * It converts the value read from the INI file 1265 * and stored in the configuration item 1266 * into an int64_t number. Any of the conversion 1267 * functions can be used to try to convert the value 1268 * stored as a string inside the item. 1269 * The results can be different depending upon 1270 * how the caller tries to interpret the value. 1271 * If "strict" parameter is non zero the function will fail 1272 * if there are more characters after the last digit. 1273 * The value range is from LLONG_MIN to LLONG_MAX. 1274 * 1275 * @param[in] item Item to interpret. 1276 * It must be retrieved using 1277 * \ref get_config_item(). 1278 * @param[in] strict Fail the function if 1279 * the symbol after last digit 1280 * is not valid. 1281 * @param[in] def Default value to use if 1282 * conversion failed. 1283 * @param[out] error Variable will get the value 1284 * of the error code if 1285 * error happened. 1286 * Can be NULL. In this case 1287 * function does not set 1288 * the code. 1289 * Codes: 1290 * - 0 - Success. 1291 * - EINVAL - Argument is invalid. 1292 * - EIO - Conversion failed due 1293 * invalid characters. 1294 * - ERANGE - Value is out of range. 1295 * 1296 * @return Converted value. 1297 * In case of failure the function returns default value and 1298 * sets error code into the provided variable. 1299 */ 1300 int64_t get_int64_config_value(struct collection_item *item, 1301 int strict, 1302 int64_t def, 1303 int *error); 1304 1305 /** 1306 * @brief Convert item value to integer number. 1307 * 1308 * This is a conversion function. 1309 * It converts the value read from the INI file 1310 * and stored in the configuration item 1311 * into an uint64_t number. Any of the conversion 1312 * functions can be used to try to convert the value 1313 * stored as a string inside the item. 1314 * The results can be different depending upon 1315 * how the caller tries to interpret the value. 1316 * If "strict" parameter is non zero the function will fail 1317 * if there are more characters after the last digit. 1318 * The value range is from 0 to ULLONG_MAX. 1319 * 1320 * @param[in] item Item to interpret. 1321 * It must be retrieved using 1322 * \ref get_config_item(). 1323 * @param[in] strict Fail the function if 1324 * the symbol after last digit 1325 * is not valid. 1326 * @param[in] def Default value to use if 1327 * conversion failed. 1328 * @param[out] error Variable will get the value 1329 * of the error code if 1330 * error happened. 1331 * Can be NULL. In this case 1332 * function does not set 1333 * the code. 1334 * Codes: 1335 * - 0 - Success. 1336 * - EINVAL - Argument is invalid. 1337 * - EIO - Conversion failed due 1338 * invalid characters. 1339 * - ERANGE - Value is out of range. 1340 * 1341 * @return Converted value. 1342 * In case of failure the function returns default value and 1343 * sets error code into the provided variable. 1344 */ 1345 uint64_t get_uint64_config_value(struct collection_item *item, 1346 int strict, 1347 uint64_t def, 1348 int *error); 1349 1350 /** 1351 * @brief Convert item value to floating point number. 1352 * 1353 * This is a conversion function. 1354 * It converts the value read from the INI file 1355 * and stored in the configuration item 1356 * into a floating point number. Any of the conversion 1357 * functions can be used to try to convert the value 1358 * stored as a string inside the item. 1359 * The results can be different depending upon 1360 * how the caller tries to interpret the value. 1361 * If "strict" parameter is non zero the function will fail 1362 * if there are more characters after the last digit. 1363 * 1364 * @param[in] item Item to interpret. 1365 * It must be retrieved using 1366 * \ref get_config_item(). 1367 * @param[in] strict Fail the function if 1368 * the symbol after last digit 1369 * is not valid. 1370 * @param[in] def Default value to use if 1371 * conversion failed. 1372 * @param[out] error Variable will get the value 1373 * of the error code if 1374 * error happened. 1375 * Can be NULL. In this case 1376 * function does not set 1377 * the code. 1378 * Codes: 1379 * - 0 - Success. 1380 * - EINVAL - Argument is invalid. 1381 * - EIO - Conversion failed due 1382 * invalid characters. 1383 * 1384 * @return Converted value. 1385 * In case of failure the function returns default value and 1386 * sets error code into the provided variable. 1387 */ 1388 double get_double_config_value(struct collection_item *item, 1389 int strict, 1390 double def, 1391 int *error); 1392 1393 /** 1394 * @brief Convert item value into a logical value. 1395 * 1396 * This is a conversion function. 1397 * It converts the value read from the INI file 1398 * and stored in the configuration item 1399 * into a Boolean. Any of the conversion 1400 * functions can be used to try to convert the value 1401 * stored as a string inside the item. 1402 * The results can be different depending upon 1403 * how the caller tries to interpret the value. 1404 * 1405 * @param[in] item Item to interpret. 1406 * It must be retrieved using 1407 * \ref get_config_item(). 1408 * @param[in] def Default value to use if 1409 * conversion failed. 1410 * @param[out] error Variable will get the value 1411 * of the error code if 1412 * error happened. 1413 * Can be NULL. In this case 1414 * function does not set 1415 * the code. 1416 * Codes: 1417 * - 0 - Success. 1418 * - EINVAL - Argument is invalid. 1419 * - EIO - Conversion failed due 1420 * invalid characters. 1421 * 1422 * @return Converted value. 1423 * In case of failure the function returns default value and 1424 * sets error code into the provided variable. 1425 */ 1426 unsigned char get_bool_config_value(struct collection_item *item, 1427 unsigned char def, 1428 int *error); 1429 1430 /** 1431 * @brief Get string configuration value 1432 * 1433 * Function creates a copy of the string value stored in the item. 1434 * Returned value needs to be freed after use. 1435 * If error occurred the returned value will be NULL. 1436 * 1437 * @param[in] item Item to use. 1438 * It must be retrieved using 1439 * \ref get_config_item(). 1440 * @param[out] error Variable will get the value 1441 * of the error code if 1442 * error happened. 1443 * Can be NULL. In this case 1444 * function does not set 1445 * the code. 1446 * Codes: 1447 * - 0 - Success. 1448 * - EINVAL - Argument is invalid. 1449 * - ENOMEM - No memory. 1450 * 1451 * @return Copy of the string or NULL. 1452 */ 1453 char *get_string_config_value(struct collection_item *item, 1454 int *error); 1455 /** 1456 * @brief Function returns the string stored in the item. 1457 * 1458 * Function returns a reference to the string value 1459 * stored inside the item. This string can't be altered. 1460 * The string will go out of scope if the item is deleted. 1461 * 1462 * @param[in] item Item to use. 1463 * It must be retrieved using 1464 * \ref get_config_item(). 1465 * @param[out] error Variable will get the value 1466 * of the error code if 1467 * error happened. 1468 * Can be NULL. In this case 1469 * function does not set 1470 * the code. 1471 * Codes: 1472 * - 0 - Success. 1473 * - EINVAL - Argument is invalid. 1474 * 1475 * @return String from the item. 1476 */ 1477 const char *get_const_string_config_value(struct collection_item *item, 1478 int *error); 1479 1480 /** 1481 * @brief Convert item value into a binary sequence. 1482 * 1483 * This is a conversion function. 1484 * It converts the value read from the INI file 1485 * and stored in the configuration item 1486 * into a sequence of bytes. 1487 * Any of the conversion functions 1488 * can be used to try to convert the value 1489 * stored as a string inside the item. 1490 * The results can be different depending upon 1491 * how the caller tries to interpret the value. 1492 * 1493 * The function allocates memory. 1494 * It is the responsibility of the caller to free it after use. 1495 * Use \ref free_bin_config_value() for this purpose. 1496 * Functions will return NULL if conversion failed. 1497 * 1498 * Function assumes that the value being interpreted 1499 * has a special format. 1500 * The string should be taken in single quotes 1501 * and consist of hex encoded value represented by 1502 * two hex digits per byte. 1503 * Case does not matter. 1504 * 1505 * Example: '0a2BFeCc' 1506 * 1507 * @param[in] item Item to interpret. 1508 * It must be retrieved using 1509 * \ref get_config_item(). 1510 * @param[out] length Variable that optionally receives 1511 * the length of the binary 1512 * sequence. 1513 * @param[out] error Variable will get the value 1514 * of the error code if 1515 * error happened. 1516 * Can be NULL. In this case 1517 * function does not set 1518 * the code. 1519 * Codes: 1520 * - 0 - Success. 1521 * - EINVAL - Argument is invalid. 1522 * - EIO - Conversion failed due 1523 * invalid characters. 1524 * - ENOMEM - No memory. 1525 * 1526 * @return Converted value. 1527 * In case of failure the function returns NULL. 1528 */ 1529 char *get_bin_config_value(struct collection_item *item, 1530 int *length, 1531 int *error); 1532 1533 /** 1534 * @brief Free binary buffer 1535 * 1536 * Free binary value returned by \ref get_bin_config_value(). 1537 * 1538 * @param[in] bin Binary buffer to free. 1539 * 1540 */ 1541 void free_bin_config_value(char *bin); 1542 1543 /** 1544 * @brief Convert value to an array of strings. 1545 * 1546 * This is a conversion function. 1547 * It converts the value read from the INI file 1548 * and stored in the configuration item 1549 * into an array of strings. Any of the conversion 1550 * functions can be used to try to convert the value 1551 * stored as a string inside the item. 1552 * The results can be different depending upon 1553 * how the caller tries to interpret the value. 1554 * 1555 * Separator string includes up to three different separators. 1556 * If separator NULL, comma is assumed. 1557 * The spaces are trimmed automatically around separators 1558 * in the string. 1559 * The function drops empty tokens from the list. 1560 * This means that the string like this: "apple, ,banana, ,orange ," 1561 * will be translated into the list of three items: 1562 * "apple","banana" and "orange". 1563 * 1564 * The length of the allocated array is returned in "size". 1565 * Size and error parameters can be NULL. 1566 * Use \ref free_string_config_array() to free the array after use. 1567 * 1568 * The array is always NULL terminated so 1569 * it is safe not to get size and just loop until 1570 * array element is NULL. 1571 * 1572 * @param[in] item Item to interpret. 1573 * It must be retrieved using 1574 * \ref get_config_item(). 1575 * @param[in] sep String cosisting of separator 1576 * symbols. For example: ",.;" would mean 1577 * that comma, dot and semicolon 1578 * should be treated as separators 1579 * in the value. 1580 * @param[out] size Variable that optionally receives 1581 * the size of the array. 1582 * @param[out] error Variable will get the value 1583 * of the error code if 1584 * error happened. 1585 * Can be NULL. In this case 1586 * function does not set 1587 * the code. 1588 * Codes: 1589 * - 0 - Success. 1590 * - EINVAL - Argument is invalid. 1591 * - EIO - Conversion failed. 1592 * - ENOMEM - No memory. 1593 * 1594 * @return Array of strings. 1595 * In case of failure the function returns NULL. 1596 */ 1597 char **get_string_config_array(struct collection_item *item, 1598 const char *sep, 1599 int *size, 1600 int *error); 1601 1602 /** 1603 * @brief Convert value to an array of strings. 1604 * 1605 * This is a conversion function. 1606 * It converts the value read from the INI file 1607 * and stored in the configuration item 1608 * into an array of strings. Any of the conversion 1609 * functions can be used to try to convert the value 1610 * stored as a string inside the item. 1611 * The results can be different depending upon 1612 * how the caller tries to interpret the value. 1613 * 1614 * Separator string includes up to three different separators. 1615 * If separator NULL, comma is assumed. 1616 * The spaces are trimmed automatically around separators 1617 * in the string. 1618 * The function does not drop empty tokens from the list. 1619 * This means that the string like this: "apple, ,banana, ,orange ," 1620 * will be translated into the list of five items: 1621 * "apple", "", "banana", "" and "orange". 1622 * 1623 * The length of the allocated array is returned in "size". 1624 * Size and error parameters can be NULL. 1625 * Use \ref free_string_config_array() to free the array after use. 1626 * 1627 * The array is always NULL terminated so 1628 * it is safe not to get size and just loop until 1629 * array element is NULL. 1630 * 1631 * @param[in] item Item to interpret. 1632 * It must be retrieved using 1633 * \ref get_config_item(). 1634 * @param[in] sep String cosisting of separator 1635 * symbols. For example: ",.;" would mean 1636 * that comma, dot and semicolon 1637 * should be treated as separators 1638 * in the value. 1639 * @param[out] size Variable that optionally receives 1640 * the size of the array. 1641 * @param[out] error Variable will get the value 1642 * of the error code if 1643 * error happened. 1644 * Can be NULL. In this case 1645 * function does not set 1646 * the code. 1647 * Codes: 1648 * - 0 - Success. 1649 * - EINVAL - Argument is invalid. 1650 * - EIO - Conversion failed. 1651 * - ENOMEM - No memory. 1652 * 1653 * @return Array of strings. 1654 * In case of failure the function returns NULL. 1655 */ 1656 char **get_raw_string_config_array(struct collection_item *item, 1657 const char *sep, 1658 int *size, 1659 int *error); 1660 1661 /** 1662 * @brief Convert value to an array of long values. 1663 * 1664 * This is a conversion function. 1665 * It converts the value read from the INI file 1666 * and stored in the configuration item 1667 * into an array of long values. Any of the conversion 1668 * functions can be used to try to convert the value 1669 * stored as a string inside the item. 1670 * The results can be different depending upon 1671 * how the caller tries to interpret the value. 1672 * 1673 * Separators inside the string are detected automatically. 1674 * The spaces are trimmed automatically around separators 1675 * in the string. 1676 * 1677 * The length of the allocated array is returned in "size". 1678 * Size parameter can't be NULL. 1679 * 1680 * Use \ref free_long_config_array() to free the array after use. 1681 * 1682 * @param[in] item Item to interpret. 1683 * It must be retrieved using 1684 * \ref get_config_item(). 1685 * @param[out] size Variable that receives 1686 * the size of the array. 1687 * @param[out] error Variable will get the value 1688 * of the error code if 1689 * error happened. 1690 * Can be NULL. In this case 1691 * function does not set 1692 * the code. 1693 * Codes: 1694 * - 0 - Success. 1695 * - EINVAL - Argument is invalid. 1696 * - EIO - Conversion failed. 1697 * - ERANGE - Value is out of range. 1698 * - ENOMEM - No memory. 1699 * 1700 * @return Array of long values. 1701 * In case of failure the function returns NULL. 1702 */ 1703 long *get_long_config_array(struct collection_item *item, 1704 int *size, 1705 int *error); 1706 1707 /** 1708 * @brief Convert value to an array of floating point values. 1709 * 1710 * This is a conversion function. 1711 * It converts the value read from the INI file 1712 * and stored in the configuration item 1713 * into an array of floating point values. Any of the conversion 1714 * functions can be used to try to convert the value 1715 * stored as a string inside the item. 1716 * The results can be different depending upon 1717 * how the caller tries to interpret the value. 1718 * 1719 * Separators inside the string are detected automatically. 1720 * The spaces are trimmed automatically around separators 1721 * in the string. 1722 * 1723 * The length of the allocated array is returned in "size". 1724 * Size parameter can't be NULL. 1725 * 1726 * Use \ref free_double_config_array() to free the array after use. 1727 * 1728 * @param[in] item Item to interpret. 1729 * It must be retrieved using 1730 * \ref get_config_item(). 1731 * @param[out] size Variable that receives 1732 * the size of the array. 1733 * @param[out] error Variable will get the value 1734 * of the error code if 1735 * error happened. 1736 * Can be NULL. In this case 1737 * function does not set 1738 * the code. 1739 * Codes: 1740 * - 0 - Success. 1741 * - EINVAL - Argument is invalid. 1742 * - EIO - Conversion failed. 1743 * - ENOMEM - No memory. 1744 * 1745 * @return Array of floating point values. 1746 * In case of failure the function returns NULL. 1747 */ 1748 double *get_double_config_array(struct collection_item *item, 1749 int *size, 1750 int *error); 1751 1752 /** 1753 * @brief Free array of string values. 1754 * 1755 * Use this function to free the array returned by 1756 * \ref get_string_config_array() or by 1757 * \ref get_raw_string_config_array(). 1758 * 1759 * @param[in] str_config Array of string values. 1760 */ 1761 void free_string_config_array(char **str_config); 1762 1763 /** 1764 * @brief Free array of long values. 1765 * 1766 * Use this function to free the array returned by 1767 * \ref get_long_config_array(). 1768 * 1769 * @param[in] array Array of long values. 1770 */ 1771 void free_long_config_array(long *array); 1772 /** 1773 * @brief Free array of floating pointer values. 1774 * 1775 * Use this function to free the array returned by 1776 * \ref get_double_config_array(). 1777 * 1778 * @param[in] array Array of floating pointer values. 1779 */ 1780 void free_double_config_array(double *array); 1781 1782 1783 /** 1784 * @} 1785 */ 1786 1787 #endif 1788