src/include/gnunet_configuration_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2006, 2008, 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_configuration_lib.h
  23  * @brief configuration API
  24  *
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef GNUNET_CONFIGURATION_LIB_H
  29 #define GNUNET_CONFIGURATION_LIB_H
  30
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_common.h"
  41 #include "gnunet_time_lib.h"
  42
  43 /**
  44  * A configuration object.
  45  */
  46 struct GNUNET_CONFIGURATION_Handle;
  47
  48 /**
  49  * Create a new configuration object.
  50  *
  51  * @param component name of responsible component
  52  */
  53 struct GNUNET_CONFIGURATION_Handle *GNUNET_CONFIGURATION_create (void);
  54
  55 /**
  56  * Destroy configuration object.
  57  */
  58 void GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg);
  59
  60 /**
  61  * Load configuration.  This function will first parse the
  62  * defaults and then parse the specific configuration file
  63  * to overwrite the defaults.
  64  *
  65  * @param filename name of the configuration file
  66  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  67  */
  68 int GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg,
  69                                const char *filename);
  70
  71 /**
  72  * Parse a configuration file, add all of the options in the
  73  * file to the configuration environment.
  74  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  75  */
  76 int GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg,
  77                                 const char *filename);
  78
  79 /**
  80  * Write configuration file.
  81  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  82  */
  83 int GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
  84                                 const char *filename);
  85
  86 /**
  87  * Test if there are configuration options that were
  88  * changed since the last save.
  89  * @return GNUNET_NO if clean, GNUNET_YES if dirty, GNUNET_SYSERR on error (i.e. last save failed)
  90  */
  91 int GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg);
  92
  93 /**
  94  * Get a configuration value that should be a number.
  95  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  96  */
  97 int GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle
  98                                            *cfg, const char *section,
  99                                            const char *option,
 100                                            unsigned long long *number);
 101
 102 /**
 103  * Get a configuration value that should be a relative time.
 104  *
 105  * @param time set to the time value stored in the configuration
 106  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 107  */
 108 int GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle
 109                                          *cfg, const char *section,
 110                                          const char *option,
 111                                          struct GNUNET_TIME_Relative *time);
 112
 113 /**
 114  * Test if we have a value for a particular option
 115  * @return GNUNET_YES if so, GNUNET_NO if not.
 116  */
 117 int GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 118                                      const char *section, const char *option);
 119
 120 /**
 121  * Get a configuration value that should be a string.
 122  * @param value will be set to a freshly allocated configuration
 123  *        value, or NULL if option is not specified
 124  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 125  */
 126 int GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle
 127                                            *cfg, const char *section,
 128                                            const char *option, char **value);
 129
 130 /**
 131  * Get a configuration value that should be the name of a file
 132  * or directory.
 133  *
 134  * @param value will be set to a freshly allocated configuration
 135  *        value, or NULL if option is not specified
 136  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 137  */
 138 int GNUNET_CONFIGURATION_get_value_filename (const struct
 139                                              GNUNET_CONFIGURATION_Handle *cfg,
 140                                              const char *section,
 141                                              const char *option,
 142                                              char **value);
 143
 144 /**
 145  * Iterate over the set of filenames stored in a configuration value.
 146  *
 147  * @return number of filenames iterated over, -1 on error
 148  */
 149 int GNUNET_CONFIGURATION_iterate_value_filenames (const struct
 150                                                   GNUNET_CONFIGURATION_Handle
 151                                                   *cfg,
 152                                                   const char *section,
 153                                                   const char *option,
 154                                                   GNUNET_FileNameCallback
 155                                                   cb, void *cls);
 156
 157 /**
 158  * Get a configuration value that should be in a set of
 159  * predefined strings
 160  *
 161  * @param choices NULL-terminated list of legal values
 162  * @param value will be set to an entry in the legal list,
 163  *        or NULL if option is not specified and no default given
 164  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 165  */
 166 int GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle
 167                                            *cfg, const char *section,
 168                                            const char *option,
 169                                            const char **choices,
 170                                            const char **value);
 171
 172 /**
 173  * Get a configuration value that should be in a set of
 174  * "YES" or "NO".
 175  *
 176  * @return GNUNET_YES, GNUNET_NO or if option has no valid value, GNUNET_SYSERR
 177  */
 178 int GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle
 179                                           *cfg, const char *section,
 180                                           const char *option);
 181
 182 /**
 183  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 184  * where either in the "PATHS" section or the environtment
 185  * "FOO" is set to "DIRECTORY".
 186
 187  * @param old string to $-expand (will be freed!)
 188  * @return $-expanded string
 189  */
 190 char *GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle
 191                                           *cfg, char *old);
 192
 193 /**
 194  * Set a configuration value that should be a number.
 195  */
 196 void
 197 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle
 198                                        *cfg,
 199                                        const char *section,
 200                                        const char *option,
 201                                        unsigned long long number);
 202
 203
 204 /**
 205  * Set a configuration value that should be a string.
 206  * @param value
 207  */
 208 void
 209 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle
 210                                        *cfg,
 211                                        const char *section,
 212                                        const char *option, const char *value);
 213
 214 /**
 215  * Remove a filename from a configuration value that
 216  * represents a list of filenames
 217  *
 218  * @param value filename to remove
 219  * @return GNUNET_OK on success,
 220  *         GNUNET_SYSERR if the filename is not in the list
 221  */
 222 int GNUNET_CONFIGURATION_remove_value_filename (struct
 223                                                 GNUNET_CONFIGURATION_Handle
 224                                                 *cfg,
 225                                                 const char *section,
 226                                                 const char *option,
 227                                                 const char *value);
 228
 229 /**
 230  * Append a filename to a configuration value that
 231  * represents a list of filenames
 232  *
 233  * @param value filename to append
 234  * @return GNUNET_OK on success,
 235  *         GNUNET_SYSERR if the filename already in the list
 236  */
 237 int GNUNET_CONFIGURATION_append_value_filename (struct
 238                                                 GNUNET_CONFIGURATION_Handle
 239                                                 *cfg, const char *section,
 240                                                 const char *option,
 241                                                 const char *value);
 242
 243 #if 0                           /* keep Emacsens' auto-indent happy */
 244 {
 245 #endif
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249
 250 #endif