/* INI LIBRARY Interface that allows modification of the INI file. Copyright (C) Dmitri Pal 2014 INI Library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. INI Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with INI Library. If not, see . */ #ifndef INI_CONFIGMOD_H #define INI_CONFIGMOD_H /** * @defgroup insflags Flags used in add_xxx_value functions * * Flags used in add_xxx_value functions. * * @{ */ /** @brief This is the default mode - no dup checks on insert */ #define INI_VA_NOCHECK 0 /** * @brief Update a specific value. * Value of index is used to determine which one out of the duplicates * needs to be updated. Index is 0-based. If the index is out of range * the function will do best effort and return the last instance of the key. * For example if you have five duplicates and you are searching for the tenth * the function will find and return fifth instance. */ #define INI_VA_MOD 1 /** * @brief Update a specific value. * Value of index is used to determine which out of the duplicates * needs to be updated. Index is 0-based. If the value is not found or * the index is out of range the function returns ENOENT. * For example if you have five duplicates and and you are searching for tenth * the error ENOENT will be returned. */ #define INI_VA_MOD_E 2 /** * @brief Check for duplicate name and overwrite if found. * Value of index is used to determine which one of the duplicates * needs to be updated. Index is 0-based. If the value is not found * the new value will be added following other position related arguments. * This option performs best effort search. * For example if you have five duplicates and you are searching for the tenth * the function will find and return fifth instance. */ #define INI_VA_MODADD 3 /** * @brief Check for duplicate name and overwrite if found. * Value of index is used to determine which one of the duplicates * needs to be updated. Index is 0-based. If the value is not found * the new value will be added following other position related arguments. * This option performs exact search. * For example if you have five duplicates and and you are searching for tenth * the error ENOENT will be returned. */ #define INI_VA_MODADD_E 4 /** @brief Find all instances of the specific key and remove them first. * Then add respecting the position related arguments. */ #define INI_VA_CLEAN 5 /** @brief Return error EEXIST if an entry with the same name exists. */ #define INI_VA_DUPERROR 6 /** * @} */ /** * @brief Function to add a section. * * Function creates a new section in the specified position. * The position is relative to other sections. Duplicate sections * are not allowed. In case a duplicate section is detected function * will return error EEXIST. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to add. * @param[in] comments Array of comments. Can be NULL if no comment is * needed for the section. It is expected that * comment lines start with the correct comment * symbol. Function does not check this. * @param[in] count_comment Count of comments in the array. If 0 * the array is expected to be NULL terminated * and function will traverse array until its end. * @param[in] position A constant that specifies the way the * section should be added. For more information * see "disposition constants" section of * the collection interface. The value is used * only in addition so see the explanation * in the "insert" paragraph. Since duplicate * sections are not allowed any constants that * allow addition of duplicates will cause function * to return an error. * @param[in] other_section Used in conjunction with position constant. * In some cases it is convenient to add * a section that immediately before * or after another section. While position defines * where it should be added this parameter defines * the section to relate to. * @param[in] idx Index, allows treating set of sections as * an array and add Nth section. * * @return 0 - Success. * @return EEXIST - Section already exists. * @return ENOSYS - Unknown position value. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_add_section(struct ini_cfgobj *ini_config, const char *section, const char *comments[], size_t count_comment, int position, const char *other_section, int idx); /** * @brief Function to update a comment for a section. * * Function finds a section and updates or removes its comment. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to change the comment for. * @param[in] comments Array of comments. Can be NULL if no comment is * needed for the section. It is expected that * comment lines start with the correct comment * symbol. Function does not check this. * @param[in] count_comment Count of comments in the array. If 0 * the array is expected to be NULL terminated * and function will traverse array until its end. * * @return 0 - Success. * @return ENOENT - Section is not found. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_comment_section(struct ini_cfgobj *ini_config, const char *section, const char *comments[], size_t count_comment); /** * @brief Function to rename a section. * * Function finds a section and renames it. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to find. * @param[in] newname New section name. * * @return 0 - Success. * @return ENOENT - Section is not found. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_rename_section(struct ini_cfgobj *ini_config, const char *section, const char *newname); /** * @brief Function to delete a section by name. * * Function is a convenience wrapper around * \ref ini_config_delete_section_by_position function. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to delete. * * @return 0 - Success. * @return ENOENT - Section is not found. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_delete_section_by_name(struct ini_cfgobj *ini_config, const char *section); /** * @brief Function to delete a section by position or name. * * Function allows removing a specific section by its relative position * in the list of sections or by its name. * * @param[in] ini_config Configuration object to modify. * @param[in] position A constant that specifies the way the * section should be deleted. For more information * see "disposition constants" section of * the collection interface. The value is used * only in deletion so see the explanation * in the "delete" paragraph. * There can't be duplicate sections. However * function respects all of the listed constants. * To find and delete a particular section * one can use COL_DSP_FIRSTDUP constant. * One should just expect that there is only * one instance of every section if any. * @param[in] section Used in conjunction with position constant. * In some cases it is convenient to add * a section immediately before * or after another value. While position defines * where it should be added this parameter defines * the section to relate to. * @param[in] idx Index of the position. * For example one can specify * that the third section should be deleted. * * @return 0 - Success. * @return ENOENT - Section is not found. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_delete_section_by_position(struct ini_cfgobj *ini_config, int position, const char *section, int idx); /** * @brief Function to a add string value to a particular section. * * Depending on the flags function adds, or deletes and adds, or just modifies * the configuration value stored in the configuration object. * * NOTE: all other ini_config_add_xxx_value functions are implemented * as wrappers around this function so they have same behavior and logic. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to modify. * @param[in] key Key of the value to add or modify. * @param[in] value String that represents value. * @param[in] comments Array of comments. Can be NULL if no comment is * needed for the value. It is expected that * comment lines start with the correct comment * symbol. Function does not check this. * @param[in] count_comment Count of comments in the array. If 0 * the array is expected to be NULL terminated * and function will traverse array until its end. * @param[in] border The boundary the value should be wrapped at. * The usual value is 80 characters. * @param[in] position A constant that specifies the way the * value should be added. For more information * see "disposition constants" section of * the collection interface. The value is used * only in addition so see the explanation * in the "insert" paragraph. * @param[in] other_key Used in conjunction with position constant. * In some cases it is convenient to add * a value that should be placed immediately before * or after another value. While position defines * where it should be added this parameter defines * the key to relate to. * @param[in] idx Index in the whole section or among * duplicates. For example one can specify * that the value should be added as a third * duplicate. This is convenient if INI file allows * duplicate keys. * @param[in] flags These constants define the main behavior of * the function. The function can thus be used * to build configuration object from scratch * (in this case no checks would be needed), * to modify a specific key which can be identified * by index among duplicate keys in the same * section. For more information see \ref insflags. * * @return 0 - Success. * @return EEXIST - The value already exists. * @return ENOENT - The value not found. * @return ENOSYS - Unknown flag or position value. * @return ENOMEM - No memory to add value. * @return EINVAL - Invalid argument. */ int ini_config_add_str_value(struct ini_cfgobj *ini_config, const char *section, const char *key, const char *value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an integer value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an integer argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_int_value(struct ini_cfgobj *ini_config, const char *section, const char *key, int value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a long value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a long integer argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_long_value(struct ini_cfgobj *ini_config, const char *section, const char *key, long value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an unsigned long value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an unsigned long integer argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_ulong_value(struct ini_cfgobj *ini_config, const char *section, const char *key, unsigned long value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an unsigned value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an unsigned argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_unsigned_value(struct ini_cfgobj *ini_config, const char *section, const char *key, unsigned value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an int32 value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an int32 argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_int32_value(struct ini_cfgobj *ini_config, const char *section, const char *key, int32_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an uint32 value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an uint32 argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_uint32_value(struct ini_cfgobj *ini_config, const char *section, const char *key, uint32_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an int64 value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an int64 argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_int64_value(struct ini_cfgobj *ini_config, const char *section, const char *key, int64_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add an uint64 value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * an uint64 argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_uint64_value(struct ini_cfgobj *ini_config, const char *section, const char *key, uint64_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a double value to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a double argument for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_double_value(struct ini_cfgobj *ini_config, const char *section, const char *key, double value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a binary value to a particular section. * * Binary values are represented by a HEX string where two HEX digits * represent one byte of the source data. The value is surrounded * by a pair of single quotes. * * Function is similar to \ref ini_config_add_str_value except it uses * a void argument for the value input. The length of the data is specified by * by the value_len argument. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_bin_value(struct ini_cfgobj *ini_config, const char *section, const char *key, void *value, size_t value_len, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a value that consists of an array of strings * to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a string array argument and a count for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_str_arr_value(struct ini_cfgobj *ini_config, const char *section, const char *key, const char *value_str_arr[], size_t count_str, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a value that consists of an array of integers * to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a integer array argument and a count for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_int_arr_value(struct ini_cfgobj *ini_config, const char *section, const char *key, int *value_int_arr, size_t count_int, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a value that consists of an array of long integers * to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a long integer array argument and a count for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_long_arr_value(struct ini_cfgobj *ini_config, const char *section, const char *key, long *value_long_arr, size_t count_long, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to add a value that consists of an array of doubles * to a particular section. * * Function is similar to \ref ini_config_add_str_value except it uses * a double array argument and a count for the value input. * * For logic, behavior and return values see \ref ini_config_add_str_value. */ int ini_config_add_double_arr_value(struct ini_cfgobj *ini_config, const char *section, const char *key, double *value_double_arr, size_t count_double, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, unsigned flags); /** * @brief Function to delete a value. * * Function deletes a value specified either by key or by position. * For example the caller can remove first or last key of the section as well * as first, last or specific instance of a specific key. If key is searched * by index and index is out of range the function would return ENOENT * indicating that specifically requested key is not found. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to remove the key from. * @param[in] position A constant that specifies the way the * key should be removed. For more information * see "disposition constants" section of * the collection interface.See the "delete" * paragraph for more information. * @param[in] key Used in conjunction with position constant. * Depending on the value of the position * argument the key argument can specify * the key to delete or the key that the delete * operation should be relative to. * @param[in] idx Index of duplicates. For example one can specify * that he wants to delete the third duplicate * of a specific key. If there are less duplicates, * i.e. the index is out of range, the function * will return ENOENT. * * @return 0 - Value was removed. * @return ENOENT - The value not found. */ int ini_config_delete_value(struct ini_cfgobj *ini_config, const char *section, int position, const char *key, int idx); /** * @brief Function to update a comment. * * Function can be used to find and modify a comment for a specific * key in a specific section. * * @param[in] ini_config Configuration object to modify. * @param[in] section Name of the section to find the key. * @param[in] key The key to find. * @param[in] comments The array of comments. Can be NULL. If NULL, * the existing comment will be removed if any. * The comment lines are expected to start with a * standard comment symbol. * @param[in] count_comment Count of comments. If 0 the comment is * constructed using array of strings above. * It is expected to be NULL terminated. * @param[in] idx Index of duplicates. For example one can specify * that he wants to find the third duplicate * of a specific key. If there are less duplicates, * i.e. the index is out of range, the function * will return ENOENT. * * @return 0 - Value was removed. * @return ENOENT - The value not found. */ int ini_config_update_comment(struct ini_cfgobj *ini_config, const char *section, const char *key, const char *comments[], size_t count_comment, int idx);