Config Files ============ The configuration file functions are a simple implementation of the INI file format, with the addition of default values. .. code:: cpp #include .. type:: config_t Config File Functions --------------------- .. function:: config_t *config_create(const char *file) Creates a new configuration object and associates it with the specified file name. :param file: Path to the new configuration file :return: A new configuration file object ---------------------- .. function:: int config_open(config_t **config, const char *file, enum config_open_type open_type) Opens a configuration file. :param config: Pointer that receives a pointer to a new configuration file object (if successful) :param file: Path to the configuration file :param open_type: Can be one of the following values: - CONFIG_OPEN_EXISTING - Fail if the file doesn't exist. - CONFIG_OPEN_ALWAYS - Try to open the file. If the file doesn't exist, create it. :return: Can return the following values: - CONFIG_SUCCESS - Successful - CONFIG_FILENOTFOUND - File not found - CONFIG_ERROR - Generic error ---------------------- .. function:: int config_open_string(config_t **config, const char *str) Opens configuration data via a string rather than a file. :param config: Pointer that receives a pointer to a new configuration file object (if successful) :param str: Configuration string :return: Can return the following values: - CONFIG_SUCCESS - Successful - CONFIG_FILENOTFOUND - File not found - CONFIG_ERROR - Generic error ---------------------- .. function:: int config_save(config_t *config) Saves configuration data to a file (if associated with a file). :param config: Configuration object :return: Can return the following values: - CONFIG_SUCCESS - Successful - CONFIG_FILENOTFOUND - File not found - CONFIG_ERROR - Generic error ---------------------- .. function:: int config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext) Saves configuration data and minimizes overwrite corruption risk. Saves the file with the file name :param config: Configuration object :param temp_ext: Temporary extension for the new file :param backup_ext: Backup extension for the old file. Can be *NULL* if no backup is desired. :return: Can return the following values: - CONFIG_SUCCESS - Successful - CONFIG_FILENOTFOUND - File not found - CONFIG_ERROR - Generic error ---------------------- .. function:: void config_close(config_t *config) Closes the configuration object. :param config: Configuration object ---------------------- .. function:: size_t config_num_sections(config_t *config) Returns the number of sections. :param config: Configuration object :return: Number of configuration sections ---------------------- .. function:: const char *config_get_section(config_t *config, size_t idx) Returns a section name based upon its index. :param config: Configuration object :param idx: Index of the section :return: The section's name Set/Get Functions ----------------- .. function:: void config_set_string(config_t *config, const char *section, const char *name, const char *value) Sets a string value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The string value ---------------------- .. function:: void config_set_int(config_t *config, const char *section, const char *name, int64_t value) Sets an integer value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The integer value ---------------------- .. function:: void config_set_uint(config_t *config, const char *section, const char *name, uint64_t value) Sets an unsigned integer value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The unsigned integer value ---------------------- .. function:: void config_set_bool(config_t *config, const char *section, const char *name, bool value) Sets a boolean value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The boolean value ---------------------- .. function:: void config_set_double(config_t *config, const char *section, const char *name, double value) Sets a floating point value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The floating point value ---------------------- .. function:: const char *config_get_string(config_t *config, const char *section, const char *name) Gets a string value. If the value is not set, it will use the default value. If there is no default value, it will return *NULL*. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The string value ---------------------- .. function:: int64_t config_get_int(config_t *config, const char *section, const char *name) Gets an integer value. If the value is not set, it will use the default value. If there is no default value, it will return 0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The integer value ---------------------- .. function:: uint64_t config_get_uint(config_t *config, const char *section, const char *name) Gets an unsigned integer value. If the value is not set, it will use the default value. If there is no default value, it will return 0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The unsigned integer value ---------------------- .. function:: bool config_get_bool(config_t *config, const char *section, const char *name) Gets a boolean value. If the value is not set, it will use the default value. If there is no default value, it will return false. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The boolean value ---------------------- .. function:: double config_get_double(config_t *config, const char *section, const char *name) Gets a floating point value. If the value is not set, it will use the default value. If there is no default value, it will return 0.0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The floating point value ---------------------- .. function:: bool config_remove_value(config_t *config, const char *section, const char *name) Removes a value. Does not remove the default value if any. :param config: Configuration object :param section: The section of the value :param name: The value name Default Value Functions ----------------------- .. function:: int config_open_defaults(config_t *config, const char *file) Opens a file and uses it for default values. :param config: Configuration object :param file: The file to open for default values ---------------------- .. function:: void config_set_default_string(config_t *config, const char *section, const char *name, const char *value) Sets a default string value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The string value ---------------------- .. function:: void config_set_default_int(config_t *config, const char *section, const char *name, int64_t value) Sets a default integer value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The integer value ---------------------- .. function:: void config_set_default_uint(config_t *config, const char *section, const char *name, uint64_t value) Sets a default unsigned integer value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The unsigned integer value ---------------------- .. function:: void config_set_default_bool(config_t *config, const char *section, const char *name, bool value) Sets a default boolean value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The boolean value ---------------------- .. function:: void config_set_default_double(config_t *config, const char *section, const char *name, double value) Sets a default floating point value. :param config: Configuration object :param section: The section of the value :param name: The value name :param value: The floating point value ---------------------- .. function:: const char *config_get_default_string(config_t *config, const char *section, const char *name) Gets a default string value. If there is no default value, it will return *NULL*. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The default string value ---------------------- .. function:: int64_t config_get_default_int(config_t *config, const char *section, const char *name) Gets a default integer value. If there is no default value, it will return 0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The integer value ---------------------- .. function:: uint64_t config_get_default_uint(config_t *config, const char *section, const char *name) Gets a default unsigned integer value. If there is no default value, it will return 0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The unsigned integer value ---------------------- .. function:: bool config_get_default_bool(config_t *config, const char *section, const char *name) Gets a default boolean value. If there is no default value, it will return false. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The boolean value ---------------------- .. function:: double config_get_default_double(config_t *config, const char *section, const char *name) Gets a default floating point value. If there is no default value, it will return 0.0. :param config: Configuration object :param section: The section of the value :param name: The value name :return: The floating point value ----------------------- .. function:: bool config_has_user_value(config_t *config, const char *section, const char *name) Returns whether a value is user-set (true) or default/none (false). :param config: Configuration object :param section: The section of the value :param name: The value name :return: Whether a user value exists ----------------------- .. function:: bool config_has_default_value(config_t *config, const char *section, const char *name) Returns whether a value has a default set. :param config: Configuration object :param section: The section of the value :param name: The value name :return: Whether a user value exists