[INI] Introducing configuration file object

The patch contains two major pieces of work:
* The beginning of the new INI interface
  significantly re-thought and reworked.
* The implementation of the file object.
  Parsing was adjusted to use this object.

1 files changed, 910 insertions, 10 deletions

diff --git a/common/ini/ini_configobj.h b/common/ini/ini_configobj.h
index 4b1b31f..8ecb148 100644
--- a/common/ini/ini_configobj.h
+++ b/common/ini/ini_configobj.h
@@ -22,33 +22,933 @@
 #ifndef INI_CONFIGOBJ_H
 #define INI_CONFIGOBJ_H
 
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <limits.h>
 #include <stdio.h>
 #include "simplebuffer.h"
 
+/**
+ * @defgroup errorlevel Error tolerance constants
+ *
+ * Constants in this section define what to do if
+ * error or warning encountered while parsing the INI file.
+ *
+ * @{
+ */
+/** @brief Fail if any problem is detected. */
+#define INI_STOP_ON_ANY     0
+/** @brief Best effort - do not fail. */
+#define INI_STOP_ON_NONE    1
+/** @brief Fail on errors only. */
+#define INI_STOP_ON_ERROR   2
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup parseerr Parsing errors and warnings
+ *
+ * @{
+ */
+/** @brief Line is too long (Error). */
+#define ERR_LONGDATA        1
+/** @brief No closing bracket in section definition (Error). */
+#define ERR_NOCLOSESEC      2
+/** @brief Section name is missing (Error). */
+#define ERR_NOSECTION       3
+/** @brief Section name too long (Error). */
+#define ERR_SECTIONLONG     4
+/** @brief No equal sign (Error). */
+#define ERR_NOEQUAL         5
+/** @brief No key before equal sign (Error). */
+#define ERR_NOKEY           6
+/** @brief Key is too long (Error). */
+#define ERR_LONGKEY         7
+/** @brief Failed to read line (Error). */
+#define ERR_READ            8
+/** @brief Line starts with space when it should not (Error). */
+#define ERR_SPACE           9
+
+/** @brief Size of the error array. */
+#define ERR_MAXPARSE        ERR_SPACE
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup structures Structures
+ * @{
+ */
+
+
+struct ini_cfgobj;
+struct ini_cfgfile;
+
+/** @brief Structure that holds error number and
+ *  line number for the encountered error.
+ */
+struct ini_parse_error;
+
+
+/**
+ * @}
+ */
+
+
 /********************************************************************/
 /* THIS IS A BEGINNING OF THE THE NEW CONFIG OBJECT INTERFACE - TBD */
 /* It will be moved to the ini_config.h when it is ready            */
 /********************************************************************/
 
-struct configobj;
 
 /* Create a configuration object */
-int ini_config_create(struct configobj **ini_config);
+int ini_config_create(struct ini_cfgobj **ini_config);
 
 /* Destroy a configuration object */
-void ini_config_destroy(struct configobj *ini_config);
+void ini_config_destroy(struct ini_cfgobj *ini_config);
+
+/* Create a file object for parsing a config file */
+int ini_config_file_open(const char *filename,
+                         int error_level,
+                         uint32_t collision_flags,
+                         uint32_t metadata_flags,
+                         struct ini_cfgfile **file_ctx);
+
+/* Close file context and destroy the object */
+void ini_config_file_close(struct ini_cfgfile *file_ctx);
+
+/* How many errors do we have in the list ? */
+unsigned ini_config_error_count(struct ini_cfgfile *file_ctx);
+
+/* Get the list of error strings */
+int ini_config_get_errors(struct ini_cfgfile *file_ctx,
+                          char ***errors);
+
+/* Get the fully resolved file name */
+const char *ini_config_get_filename(struct ini_cfgfile *file_ctx);
+
+/* Free error strings */
+void ini_config_free_errors(char **errors);
+
+/* Parse the file and create a config object */
+int ini_config_parse(struct ini_cfgfile *file_ctx,
+                     struct ini_cfgobj *ini_config);
+
+/* Function to print errors from the list */
+void ini_print_errors(FILE *file, char **error_list);
+
+
+/* TBD rename the function */
+/** @brief Function to return a parsing error as a string.
+ *
+ * @param[in] parsing_error    Error code for the parsing error.
+ *
+ * @return Error string.
+ */
+const char *parsing_error_str(int parsing_error);
+
+
+/* Merge two configurations together creating a new one */
+int ini_config_merge(struct ini_cfgobj *first,
+                     struct ini_cfgobj *second,
+                     uint32_t collision_flags,
+                     struct ini_cfgobj **result);
+
+/* Set the folding boundary for multiline values.
+ * Use before serializing and saving to a file if the
+ * default boundary of 80 characters does not work for you.
+ */
+int ini_config_set_wrap(struct ini_cfgobj *ini_config,
+                        uint32_t boundary);
 
 /* Serialize configuration object into provided buffer */
-int ini_config_serialize(struct configobj *ini_config,
+int ini_config_serialize(struct ini_cfgobj *ini_config,
                          struct simplebuffer *sbobj);
 
-int ini_config_parse(FILE *file,
-                     const char *config_filename,
-                     struct configobj *ini_config,
-                     int error_level,
-                     struct collection_item **error_list,
-                     uint32_t boundary);
+/* Check access */
+int ini_config_access_check(struct ini_cfgfile *file_ctx,
+                            uint32_t flags,
+                            uid_t uid,
+                            gid_t gid,
+                            mode_t mode,
+                            mode_t mask);
+
+/* Determins if two file context different by comparing
+ * - time stamp
+ * - device ID
+ * - i-node
+ */
+int ini_config_changed(struct ini_cfgfile *file_ctx,
+                       struct ini_cfgfile *file_ctx_saved,
+                       int *changed);
+
+
+/****************************************************/
+/* VALUE MANAGEMENT                                 */
+/****************************************************/
+
+/**
+ * @brief Get list of sections.
+ *
+ * Get list of sections from the configuration object
+ * as an array of strings.
+ * Function allocates memory for the array of the sections.
+ * Use \ref free_section_list() to free allocated memory.
+ *
+ * @param[in]  ini_config       Configuration object.
+ * @param[out] size             If not NULL parameter will
+ *                              receive number of sections
+ *                              in the configuration.
+ * @param[out] error            If not NULL parameter will
+ *                              receive the error code.
+ *                              0 - Success.
+ *                              EINVAL - Invalid parameter.
+ *                              ENOMEM - No memory.
+ *
+ * @return Array of strings.
+ */
+char **get_section_list(struct ini_cfgobj *ini_config,
+                        int *size,
+                        int *error);
+
+/**
+ * @brief Free list of sections.
+ *
+ * The section array created by \ref get_section_list()
+ * should be freed using this function.
+ *
+ * @param[in] section_list       Array of strings returned by
+ *                               \ref get_section_list() function.
+ */
+void free_section_list(char **section_list);
+
+/**
+ * @brief Get list of attributes.
+ *
+ * Get list of attributes in a section as an array of strings.
+ * Function allocates memory for the array of attributes.
+ * Use \ref free_attribute_list() to free allocated memory.
+ *
+ * @param[in]  ini_config       Configuration object.
+ * @param[in]  section          Section name.
+ * @param[out] size             If not NULL parameter will
+ *                              receive number of attributes
+ *                              in the section.
+ * @param[out] error            If not NULL parameter will
+ *                              receive the error code.
+ *                              0 - Success.
+ *                              EINVAL - Invalid parameter.
+ *                              ENOMEM - No memory.
+ *
+ * @return Array of strings.
+ */
+char **get_attribute_list(struct ini_cfgobj *ini_config,
+                          const char *section,
+                          int *size,
+                          int *error);
+
+/**
+ * @brief Free list of attributes.
+ *
+ * The attribute array created by \ref get_attribute_list()
+ * should be freed using this function.
+ *
+ * @param[in] attr_list          Array of strings returned by
+ *                               \ref get_attribute_list() function.
+ */
+void free_attribute_list(char **attr_list);
 
 
+/**
+ * @brief Get an integer value from the configuration.
+ *
+ * Function looks up the section and key in
+ * in the configuration object and tries to convert
+ * into an integer number.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ * The value range is from INT_MIN to INT_MAX.
+ *
+ * @param[in]  ini_config       Configuration object.
+ * @param[in]  section          Section of the configuration file.
+ * @param[in]  name             Key to look up inside the section.
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] value            Fetched value or default
+ *
+ * In case of failure the function assignes default value
+ * to the resulting value and returns corresponging error code.
+ *
+ * @return 0 - Success.
+ * @return EINVAL - Argument is invalid.
+ * @return EIO - Conversion failed due invalid characters.
+ * @return ERANGE - Value is out of range.
+ * @return ENOKEY - Value is not found.
+ * @return ENOMEM - No memory.
+ */
+int get_int_config_value(struct ini_cfgobj *ini_config,
+                         const char *section,
+                         const char *name,
+                         int strict,
+                         int def,
+                         int *value);
+
+/* Similar functions are below */
+int get_long_config_value(struct ini_cfgobj *ini_config,
+                          const char *section,
+                          const char *name,
+                          int strict,
+                          long def,
+                          long *value);
+
+int get_unsigned_config_value(struct ini_cfgobj *ini_config,
+                              const char *section,
+                              const char *name,
+                              int strict,
+                              unsigned def,
+                              unsigned *value);
+
+int get_ulong_config_value(struct ini_cfgobj *ini_config,
+                           const char *section,
+                           const char *name,
+                           int strict,
+                           unsigned long def,
+                           unsigned long *value);
+
+
+
+
+
+
+
+#ifdef THE_PART_I_HAVE_PROCESSED
+
+
+
+
+
+
+/**
+ * @brief Convert item value to integer number.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an int32_t number. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ * The value range is from INT_MIN to INT_MAX.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *                              - ERANGE - Value is out of range.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+int32_t get_int32_config_value(struct collection_item *item,
+                               int strict,
+                               int32_t def,
+                               int *error);
+
+/**
+ * @brief Convert item value to integer number.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an uint32_t number. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ * The value range is from 0 to ULONG_MAX.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *                              - ERANGE - Value is out of range.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+uint32_t get_uint32_config_value(struct collection_item *item,
+                                 int strict,
+                                 uint32_t def,
+                                 int *error);
+
+/**
+ * @brief Convert item value to integer number.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an int64_t number. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ * The value range is from LLONG_MIN to LLONG_MAX.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *                              - ERANGE - Value is out of range.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+int64_t get_int64_config_value(struct collection_item *item,
+                               int strict,
+                               int64_t def,
+                               int *error);
+
+/**
+ * @brief Convert item value to integer number.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an uint64_t number. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ * The value range is from 0 to ULLONG_MAX.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *                              - ERANGE - Value is out of range.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+uint64_t get_uint64_config_value(struct collection_item *item,
+                                 int strict,
+                                 uint64_t def,
+                                 int *error);
+
+/**
+ * @brief Convert item value to floating point number.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into a floating point number. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ * If "strict" parameter is non zero the function will fail
+ * if there are more characters after the last digit.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  strict           Fail the function if
+ *                              the symbol after last digit
+ *                              is not valid.
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+double get_double_config_value(struct collection_item *item,
+                               int strict,
+                               double def,
+                               int *error);
+
+/**
+ * @brief Convert item value into a logical value.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into a Boolean. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  def              Default value to use if
+ *                              conversion failed.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *
+ * @return Converted value.
+ * In case of failure the function returns default value and
+ * sets error code into the provided variable.
+ */
+unsigned char get_bool_config_value(struct collection_item *item,
+                                    unsigned char def,
+                                    int *error);
+
+/**
+ * @brief Get string configuration value
+ *
+ * Function creates a copy of the string value stored in the item.
+ * Returned value needs to be freed after use.
+ * If error occurred the returned value will be NULL.
+ *
+ * @param[in]  item             Item to use.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Copy of the string or NULL.
+ */
+char *get_string_config_value(struct collection_item *item,
+                              int *error);
+/**
+ * @brief Function returns the string stored in the item.
+ *
+ * Function returns a reference to the string value
+ * stored inside the item. This string can't be altered.
+ * The string will go out of scope if the item is deleted.
+ *
+ * @param[in]  item             Item to use.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *
+ * @return String from the item.
+ */
+const char *get_const_string_config_value(struct collection_item *item,
+                                          int *error);
+
+/**
+ * @brief Convert item value into a binary sequence.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into a sequence of bytes.
+ * Any of the conversion functions
+ * can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * The function allocates memory.
+ * It is the responsibility of the caller to free it after use.
+ * Use \ref free_bin_config_value() for this purpose.
+ * Functions will return NULL if conversion failed.
+ *
+ * Function assumes that the value being interpreted
+ * has a special format.
+ * The string should be taken in single quotes
+ * and consist of hex encoded value represented by
+ * two hex digits per byte.
+ * Case does not matter.
+ *
+ * Example: '0a2BFeCc'
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[out] length           Variable that optionally receives
+ *                              the length of the binary
+ *                              sequence.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed due
+ *                                invalid characters.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Converted value.
+ * In case of failure the function returns NULL.
+ */
+char *get_bin_config_value(struct collection_item *item,
+                           int *length,
+                           int *error);
+
+/**
+ * @brief Free binary buffer
+ *
+ * Free binary value returned by \ref get_bin_config_value().
+ *
+ * @param[in] bin              Binary buffer to free.
+ *
+ */
+void free_bin_config_value(char *bin);
+
+/**
+ * @brief Convert value to an array of strings.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an array of strings. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * Separator string includes up to three different separators.
+ * If separator NULL, comma is assumed.
+ * The spaces are trimmed automatically around separators
+ * in the string.
+ * The function drops empty tokens from the list.
+ * This means that the string like this: "apple, ,banana, ,orange ,"
+ * will be translated into the list of three items:
+ * "apple","banana" and "orange".
+ *
+ * The length of the allocated array is returned in "size".
+ * Size and error parameters can be NULL.
+ * Use \ref free_string_config_array() to free the array after use.
+ *
+ * The array is always NULL terminated so
+ * it is safe not to get size and just loop until
+ * array element is NULL.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  sep              String cosisting of separator
+ *                              symbols. For example: ",.;" would mean
+ *                              that comma, dot and semicolon
+ *                              should be treated as separators
+ *                              in the value.
+ * @param[out] size             Variable that optionally receives
+ *                              the size of the array.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Array of strings.
+ * In case of failure the function returns NULL.
+ */
+char **get_string_config_array(struct collection_item *item,
+                               const char *sep,
+                               int *size,
+                               int *error);
+
+/**
+ * @brief Convert value to an array of strings.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an array of strings. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * Separator string includes up to three different separators.
+ * If separator NULL, comma is assumed.
+ * The spaces are trimmed automatically around separators
+ * in the string.
+ * The function does not drop empty tokens from the list.
+ * This means that the string like this: "apple, ,banana, ,orange ,"
+ * will be translated into the list of five items:
+ * "apple", "", "banana", "" and "orange".
+ *
+ * The length of the allocated array is returned in "size".
+ * Size and error parameters can be NULL.
+ * Use \ref free_string_config_array() to free the array after use.
+ *
+ * The array is always NULL terminated so
+ * it is safe not to get size and just loop until
+ * array element is NULL.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[in]  sep              String cosisting of separator
+ *                              symbols. For example: ",.;" would mean
+ *                              that comma, dot and semicolon
+ *                              should be treated as separators
+ *                              in the value.
+ * @param[out] size             Variable that optionally receives
+ *                              the size of the array.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Array of strings.
+ * In case of failure the function returns NULL.
+ */
+char **get_raw_string_config_array(struct collection_item *item,
+                                   const char *sep,
+                                   int *size,
+                                   int *error);
+
+/**
+ * @brief Convert value to an array of long values.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an array of long values. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * Separators inside the string are detected automatically.
+ * The spaces are trimmed automatically around separators
+ * in the string.
+ *
+ * The length of the allocated array is returned in "size".
+ * Size parameter can't be NULL.
+ *
+ * Use \ref free_long_config_array() to free the array after use.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[out] size             Variable that receives
+ *                              the size of the array.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed.
+ *                              - ERANGE - Value is out of range.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Array of long values.
+ * In case of failure the function returns NULL.
+ */
+long *get_long_config_array(struct collection_item *item,
+                            int *size,
+                            int *error);
+
+/**
+ * @brief Convert value to an array of floating point values.
+ *
+ * This is a conversion function.
+ * It converts the value read from the INI file
+ * and stored in the configuration item
+ * into an array of floating point values. Any of the conversion
+ * functions can be used to try to convert the value
+ * stored as a string inside the item.
+ * The results can be different depending upon
+ * how the caller tries to interpret the value.
+ *
+ * Separators inside the string are detected automatically.
+ * The spaces are trimmed automatically around separators
+ * in the string.
+ *
+ * The length of the allocated array is returned in "size".
+ * Size parameter can't be NULL.
+ *
+ * Use \ref free_double_config_array() to free the array after use.
+ *
+ * @param[in]  item             Item to interpret.
+ *                              It must be retrieved using
+ *                              \ref get_config_item().
+ * @param[out] size             Variable that receives
+ *                              the size of the array.
+ * @param[out] error            Variable will get the value
+ *                              of the error code if
+ *                              error happened.
+ *                              Can be NULL. In this case
+ *                              function does not set
+ *                              the code.
+ *                              Codes:
+ *                              - 0 - Success.
+ *                              - EINVAL - Argument is invalid.
+ *                              - EIO - Conversion failed.
+ *                              - ENOMEM - No memory.
+ *
+ * @return Array of floating point values.
+ * In case of failure the function returns NULL.
+ */
+double *get_double_config_array(struct collection_item *item,
+                                int *size,
+                                int *error);
+
+/**
+ * @brief Free array of string values.
+ *
+ * Use this function to free the array returned by
+ * \ref get_string_config_array() or by
+ * \ref get_raw_string_config_array().
+ *
+ * @param[in] str_config        Array of string values.
+ */
+void free_string_config_array(char **str_config);
+
+/**
+ * @brief Free array of long values.
+ *
+ * Use this function to free the array returned by
+ * \ref get_long_config_array().
+ *
+ * @param[in] array         Array of long values.
+ */
+void free_long_config_array(long *array);
+/**
+ * @brief Free array of floating pointer values.
+ *
+ * Use this function to free the array returned by
+ * \ref get_double_config_array().
+ *
+ * @param[in] array         Array of floating pointer values.
+ */
+void free_double_config_array(double *array);
+
+#endif
 
 #endif