X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_configuration_lib.h;h=a0e73f474667aa1755c43ccc45e45e350b20eeda;hb=0d4f151374efb1972361c40b6624bf4fd0e3fcaa;hp=3cdd54c8f815c1396d9eddc6e7e078ba6f9bbda0;hpb=569b8f3bc3c2e4f076f5ddf8ff4045b52775b8f9;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_configuration_lib.h b/src/include/gnunet_configuration_lib.h index 3cdd54c8f..a0e73f474 100644 --- a/src/include/gnunet_configuration_lib.h +++ b/src/include/gnunet_configuration_lib.h @@ -1,33 +1,37 @@ /* This file is part of GNUnet. - (C) 2006, 2008, 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2006, 2008, 2009, 2018 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet 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 - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_configuration_lib.h - * @brief configuration API - * * @author Christian Grothoff + * + * @file + * Configuration API + * + * @defgroup configuration Configuration library + * Configuration management + * @{ */ - #ifndef GNUNET_CONFIGURATION_LIB_H #define GNUNET_CONFIGURATION_LIB_H +#include "gnunet_time_lib.h" #ifdef __cplusplus extern "C" @@ -37,9 +41,6 @@ extern "C" #endif #endif -#include "gnunet_common.h" -#include "gnunet_time_lib.h" - /** * A configuration object. */ @@ -49,7 +50,8 @@ struct GNUNET_CONFIGURATION_Handle; * Create a new configuration object. * @return fresh configuration object */ -struct GNUNET_CONFIGURATION_Handle *GNUNET_CONFIGURATION_create (void); +struct GNUNET_CONFIGURATION_Handle * +GNUNET_CONFIGURATION_create (void); /** @@ -67,7 +69,8 @@ GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *cfg); * * @param cfg configuration to destroy */ -void GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg); +void +GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg); /** @@ -77,10 +80,24 @@ void GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg); * * @param cfg configuration to update * @param filename name of the configuration file, NULL to load defaults - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *filename); +int +GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *filename); + + +/** + * Load default configuration. This function will parse the + * defaults from the given @a defaults_d directory. + * + * @param cfg configuration to update + * @param defaults_d directory with the defaults + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_CONFIGURATION_load_from (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *defaults_d); /** @@ -89,10 +106,42 @@ int GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, * * @param cfg configuration to update * @param filename name of the configuration file - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *filename); + + +/** + * Serializes the given configuration. + * + * @param cfg configuration to serialize + * @param size will be set to the size of the serialized memory block + * @return the memory block where the serialized configuration is + * present. This memory should be freed by the caller + */ +char * +GNUNET_CONFIGURATION_serialize (const struct GNUNET_CONFIGURATION_Handle *cfg, + size_t *size); + + +/** + * De-serializes configuration + * + * @param cfg configuration to update + * @param mem the memory block of serialized configuration + * @param size the size of the memory block + * @param allow_inline set to the base directory if we recursively load configuration + * from inlined configurations; NULL if not and raise warnings + * when we come across them + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *filename); +int +GNUNET_CONFIGURATION_deserialize (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *mem, + size_t size, + const char *basedir); /** @@ -100,31 +149,76 @@ int GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg, * * @param cfg configuration to write * @param filename where to write the configuration - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *filename); +int +GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *filename); + /** * Write only configuration entries that have been changed to configuration file - * @param cfgDefault default configuration - * @param cfgNew new configuration + * @param cfg_default default configuration + * @param cfg_new new configuration * @param filename where to write the configuration diff between default and new - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ int -GNUNET_CONFIGURATION_write_diffs(const struct GNUNET_CONFIGURATION_Handle *cfgDefault, - const struct GNUNET_CONFIGURATION_Handle *cfgNew, - const char* filename); +GNUNET_CONFIGURATION_write_diffs (const struct GNUNET_CONFIGURATION_Handle *cfg_default, + const struct GNUNET_CONFIGURATION_Handle *cfg_new, + const char *filename); + + +/** + * Compute configuration with only entries that have been changed + * + * @param cfg_default original configuration + * @param cfg_new new configuration + * @return configuration with only the differences, never NULL + */ +struct GNUNET_CONFIGURATION_Handle * +GNUNET_CONFIGURATION_get_diff (const struct GNUNET_CONFIGURATION_Handle *cfg_default, + const struct GNUNET_CONFIGURATION_Handle *cfg_new); + /** * Test if there are configuration options that were * changed since the last save. * * @param cfg configuration to inspect - * @return GNUNET_NO if clean, GNUNET_YES if dirty, GNUNET_SYSERR on error (i.e. last save failed) + * @return #GNUNET_NO if clean, #GNUNET_YES if dirty, #GNUNET_SYSERR on error (i.e. last save failed) */ -int GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg); +int +GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Signature of a function to be run with a configuration. + * + * @param cls closure + * @param cfg the configuration + * @return status code + */ +typedef int +(*GNUNET_CONFIGURATION_Callback)(void *cls, + const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Parse a configuration file @a filename and run the function + * @a cb with the resulting configuration object. Then free the + * configuration object and return the status value from @a cb. + * + * @param filename configuration to parse, NULL for "default" + * @param cb function to run + * @param cb_cls closure for @a cb + * @return #GNUNET_SYSERR if parsing the configuration failed, + * otherwise return value from @a cb. + */ +int +GNUNET_CONFIGURATION_parse_and_run (const char *filename, + GNUNET_CONFIGURATION_Callback cb, + void *cb_cls); /** @@ -135,10 +229,11 @@ int GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg * @param option name of the option * @param value value of the option */ -typedef void (*GNUNET_CONFIGURATION_Iterator)(void *cls, - const char *section, - const char *option, - const char *value); +typedef void +(*GNUNET_CONFIGURATION_Iterator) (void *cls, + const char *section, + const char *option, + const char *value); /** @@ -147,8 +242,9 @@ typedef void (*GNUNET_CONFIGURATION_Iterator)(void *cls, * @param cls closure * @param section name of the section */ -typedef void (*GNUNET_CONFIGURATION_Section_Iterator)(void *cls, - const char *section); +typedef void +(*GNUNET_CONFIGURATION_Section_Iterator) (void *cls, + const char *section); /** @@ -156,11 +252,12 @@ typedef void (*GNUNET_CONFIGURATION_Section_Iterator)(void *cls, * * @param cfg configuration to inspect * @param iter function to call on each option - * @param iter_cls closure for iter + * @param iter_cls closure for @a iter */ -void GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_CONFIGURATION_Iterator iter, - void *iter_cls); +void +GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_CONFIGURATION_Iterator iter, + void *iter_cls); /** @@ -168,11 +265,12 @@ void GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg * * @param cfg configuration to inspect * @param iter function to call on each section - * @param iter_cls closure for iter + * @param iter_cls closure for @a iter */ -void GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_CONFIGURATION_Section_Iterator iter, - void *iter_cls); +void +GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_CONFIGURATION_Section_Iterator iter, + void *iter_cls); /** @@ -181,8 +279,10 @@ void GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Ha * @param cfg configuration to inspect * @param section name of the section to remove */ -void GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *section); +void +GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section); + /** * Get a configuration value that should be a number. @@ -191,12 +291,29 @@ void GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cf * @param section section of interest * @param option option of interest * @param number where to store the numeric value of the option - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option, - unsigned long long *number); +int +GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + unsigned long long *number); + + +/** + * Get a configuration value that should be a floating point number. + * + * @param cfg configuration to inspect + * @param section section of interest + * @param option option of interest + * @param number where to store the floating value of the option + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_CONFIGURATION_get_value_float (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + float *number); /** @@ -206,12 +323,30 @@ int GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Han * @param section section of interest * @param option option of interest * @param time set to the time value stored in the configuration - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option, - struct GNUNET_TIME_Relative *time); +int +GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + struct GNUNET_TIME_Relative *time); + + + +/** + * Get a configuration value that should be a size in bytes. + * + * @param cfg configuration to inspect + * @param section section of interest + * @param option option of interest + * @param size set to the size in bytes as stored in the configuration + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + unsigned long long *size); /** @@ -220,10 +355,12 @@ int GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handl * @param cfg configuration to inspect * @param section section of interest * @param option option of interest - * @return GNUNET_YES if so, GNUNET_NO if not. + * @return #GNUNET_YES if so, #GNUNET_NO if not. */ -int GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg, - const char *section, const char *option); +int +GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option); /** @@ -234,11 +371,13 @@ int GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *c * @param option option of interest * @param value will be set to a freshly allocated configuration * value, or NULL if option is not specified - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option, char **value); +int +GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + char **value); /** @@ -250,13 +389,14 @@ int GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Han * @param option option of interest * @param value will be set to a freshly allocated configuration * value, or NULL if option is not specified - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_get_value_filename (const struct - GNUNET_CONFIGURATION_Handle *cfg, - const char *section, - const char *option, - char **value); +int +GNUNET_CONFIGURATION_get_value_filename (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + char **value); + /** * Iterate over the set of filenames stored in a configuration value. @@ -265,16 +405,29 @@ int GNUNET_CONFIGURATION_get_value_filename (const struct * @param section section of interest * @param option option of interest * @param cb function to call on each filename - * @param cb_cls closure for cb + * @param cb_cls closure for @a cb * @return number of filenames iterated over, -1 on error */ -int GNUNET_CONFIGURATION_iterate_value_filenames (const struct - GNUNET_CONFIGURATION_Handle - *cfg, - const char *section, - const char *option, - GNUNET_FileNameCallback - cb, void *cb_cls); +int +GNUNET_CONFIGURATION_iterate_value_filenames (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + GNUNET_FileNameCallback cb, + void *cb_cls); + +/** + * Iterate over values of a section in the configuration. + * + * @param cfg configuration to inspect + * @param section the section + * @param iter function to call on each option + * @param iter_cls closure for @a iter + */ +void +GNUNET_CONFIGURATION_iterate_section_values (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + GNUNET_CONFIGURATION_Iterator iter, + void *iter_cls); /** * Get a configuration value that should be in a set of @@ -286,13 +439,14 @@ int GNUNET_CONFIGURATION_iterate_value_filenames (const struct * @param choices NULL-terminated list of legal values * @param value will be set to an entry in the legal list, * or NULL if option is not specified and no default given - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option, - const char **choices, - const char **value); +int +GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + const char *const *choices, + const char **value); /** * Get a configuration value that should be in a set of @@ -301,23 +455,53 @@ int GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Han * @param cfg configuration to inspect * @param section section of interest * @param option option of interest - * @return GNUNET_YES, GNUNET_NO or if option has no valid value, GNUNET_SYSERR + * @return #GNUNET_YES, #GNUNET_NO or if option has no valid value, #GNUNET_SYSERR + */ +int +GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option); + + +/** + * Get Crockford32-encoded fixed-size binary data from a configuration. + * + * @param cfg configuration to access + * @param section section to access + * @param option option to access + * @param buf where to store the decoded binary result + * @param buf_size exact number of bytes to store in @a buf + * @return #GNUNET_OK on success + * #GNUNET_NO is the value does not exist + * #GNUNET_SYSERR on decoding error */ -int GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option); +int +GNUNET_CONFIGURATION_get_data (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + void *buf, + size_t buf_size); + /** * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR" - * where either in the "PATHS" section or the environtment - * "FOO" is set to "DIRECTORY". + * where either in the "PATHS" section or the environtment "FOO" is + * set to "DIRECTORY". We also support default expansion, + * i.e. ${VARIABLE:-default} will expand to $VARIABLE if VARIABLE is + * set in PATHS or the environment, and otherwise to "default". Note + * that "default" itself can also be a $-expression, thus + * "${VAR1:-{$VAR2}}" will expand to VAR1 and if that is not defined + * to VAR2. * * @param cfg configuration to use for path expansion - * @param orig string to $-expand (will be freed!) + * @param orig string to $-expand (will be freed!) Note that multiple + * $-expressions can be present in this string. They will all be + * $-expanded. * @return $-expanded string */ -char *GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle - *cfg, char *orig); +char * +GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle *cfg, + char *orig); /** @@ -329,8 +513,7 @@ char *GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Hand * @param number value to set */ void -GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle - *cfg, +GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, const char *option, unsigned long long number); @@ -345,10 +528,11 @@ GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle * @param value value to set */ void -GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle - *cfg, +GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, - const char *option, const char *value); + const char *option, + const char *value); + /** * Remove a filename from a configuration value that @@ -358,15 +542,15 @@ GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle * @param section section of interest * @param option option of interest * @param value filename to remove - * @return GNUNET_OK on success, - * GNUNET_SYSERR if the filename is not in the list + * @return #GNUNET_OK on success, + * #GNUNET_SYSERR if the filename is not in the list */ -int GNUNET_CONFIGURATION_remove_value_filename (struct - GNUNET_CONFIGURATION_Handle - *cfg, - const char *section, - const char *option, - const char *value); +int +GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + const char *value); + /** * Append a filename to a configuration value that @@ -376,15 +560,14 @@ int GNUNET_CONFIGURATION_remove_value_filename (struct * @param section section of interest * @param option option of interest * @param value filename to append - * @return GNUNET_OK on success, - * GNUNET_SYSERR if the filename already in the list + * @return #GNUNET_OK on success, + * #GNUNET_SYSERR if the filename already in the list */ -int GNUNET_CONFIGURATION_append_value_filename (struct - GNUNET_CONFIGURATION_Handle - *cfg, const char *section, - const char *option, - const char *value); - +int +GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + const char *value); #if 0 /* keep Emacsens' auto-indent happy */ { @@ -394,3 +577,5 @@ int GNUNET_CONFIGURATION_append_value_filename (struct #endif #endif + +/** @} */ /* end of group configuration */