X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_configuration_lib.h;h=a0e73f474667aa1755c43ccc45e45e350b20eeda;hb=6e626937fd5133188d2bd06f280a1b889219eef2;hp=77d6d5552f0025b2753734fa9a1ed3834453cfe0;hpb=722980c056f396b25b5b15d6a805654d02b3c5ef;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_configuration_lib.h b/src/include/gnunet_configuration_lib.h index 77d6d5552..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. */ @@ -79,7 +80,7 @@ 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, @@ -88,11 +89,11 @@ GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg, /** * Load default configuration. This function will parse the - * defaults from the given defaults_d directory. + * 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 + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ int GNUNET_CONFIGURATION_load_from (struct GNUNET_CONFIGURATION_Handle *cfg, @@ -105,7 +106,7 @@ GNUNET_CONFIGURATION_load_from (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, @@ -131,16 +132,16 @@ GNUNET_CONFIGURATION_serialize (const struct GNUNET_CONFIGURATION_Handle *cfg, * @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 GNUNET_YES if we recursively load configuration - * from inlined configurations; GNUNET_NO if not and raise warnings + * @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_ERROR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ int GNUNET_CONFIGURATION_deserialize (struct GNUNET_CONFIGURATION_Handle *cfg, const char *mem, - const size_t size, - int allow_inline); + size_t size, + const char *basedir); /** @@ -148,36 +149,78 @@ GNUNET_CONFIGURATION_deserialize (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); + /** * 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); +/** + * 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); + + /** * Function to iterate over options. * @@ -186,9 +229,11 @@ 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); /** @@ -197,8 +242,9 @@ typedef void (*GNUNET_CONFIGURATION_Iterator) (void *cls, const char *section, * @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); /** @@ -206,7 +252,7 @@ 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, @@ -219,13 +265,12 @@ 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); +GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_CONFIGURATION_Section_Iterator iter, + void *iter_cls); /** @@ -238,6 +283,7 @@ void GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg, const char *section); + /** * Get a configuration value that should be a number. * @@ -245,15 +291,31 @@ GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg, * @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, +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); + + /** * Get a configuration value that should be a relative time. * @@ -261,11 +323,11 @@ GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle * @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, +GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, const char *option, struct GNUNET_TIME_Relative *time); @@ -278,11 +340,11 @@ GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle * @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 + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ int -GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle - *cfg, const char *section, +GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, const char *option, unsigned long long *size); @@ -293,11 +355,12 @@ GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle * @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); + const char *section, + const char *option); /** @@ -308,12 +371,13 @@ GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg, * @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); +GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + char **value); /** @@ -325,13 +389,14 @@ GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle * @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, +GNUNET_CONFIGURATION_get_value_filename (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, - const char *option, char **value); + const char *option, + char **value); + /** * Iterate over the set of filenames stored in a configuration value. @@ -340,12 +405,11 @@ 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, +GNUNET_CONFIGURATION_iterate_value_filenames (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, const char *option, GNUNET_FileNameCallback cb, @@ -357,11 +421,10 @@ GNUNET_CONFIGURATION_iterate_value_filenames (const struct * @param cfg configuration to inspect * @param section the section * @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_section_values (const struct - GNUNET_CONFIGURATION_Handle *cfg, +GNUNET_CONFIGURATION_iterate_section_values (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, GNUNET_CONFIGURATION_Iterator iter, void *iter_cls); @@ -376,12 +439,13 @@ GNUNET_CONFIGURATION_iterate_section_values (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, +GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *section, + const char *option, + const char *const *choices, const char **value); /** @@ -391,26 +455,53 @@ GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle * @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, +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_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); +GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle *cfg, + char *orig); /** @@ -423,7 +514,8 @@ GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle */ void GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *section, const char *option, + const char *section, + const char *option, unsigned long long number); @@ -437,7 +529,8 @@ GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg, */ void GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg, - const char *section, const char *option, + const char *section, + const char *option, const char *value); @@ -449,15 +542,16 @@ GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg, * @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, +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 * represents a list of filenames @@ -466,16 +560,15 @@ GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle * @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, +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 */ { #endif @@ -484,3 +577,5 @@ GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle #endif #endif + +/** @} */ /* end of group configuration */