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  * @return fresh configuration object
  51  */
  52 struct GNUNET_CONFIGURATION_Handle *
  53 GNUNET_CONFIGURATION_create (void);
  54
  55
  56 /**
  57  * Duplicate an existing configuration object.
  58  *
  59  * @param cfg configuration to duplicate
  60  * @return duplicate configuration
  61  */
  62 struct GNUNET_CONFIGURATION_Handle *
  63 GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *cfg);
  64
  65
  66 /**
  67  * Destroy configuration object.
  68  *
  69  * @param cfg configuration to destroy
  70  */
  71 void
  72 GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg);
  73
  74
  75 /**
  76  * Load configuration.  This function will first parse the
  77  * defaults and then parse the specific configuration file
  78  * to overwrite the defaults.
  79  *
  80  * @param cfg configuration to update
  81  * @param filename name of the configuration file, NULL to load defaults
  82  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  83  */
  84 int
  85 GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg,
  86                            const char *filename);
  87
  88
  89 /**
  90  * Parse a configuration file, add all of the options in the
  91  * file to the configuration environment.
  92  *
  93  * @param cfg configuration to update
  94  * @param filename name of the configuration file
  95  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  96  */
  97 int
  98 GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg,
  99                             const char *filename);
 100
 101
 102 /**
 103  * Write configuration file.
 104  *
 105  * @param cfg configuration to write
 106  * @param filename where to write the configuration
 107  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 108  */
 109 int
 110 GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
 111                             const char *filename);
 112
 113 /**
 114  * Write only configuration entries that have been changed to configuration file
 115  * @param cfgDefault default configuration
 116  * @param cfgNew new configuration
 117  * @param filename where to write the configuration diff between default and new
 118  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 119  */
 120 int
 121 GNUNET_CONFIGURATION_write_diffs (const struct GNUNET_CONFIGURATION_Handle
 122                                   *cfgDefault,
 123                                   const struct GNUNET_CONFIGURATION_Handle
 124                                   *cfgNew, const char *filename);
 125
 126 /**
 127  * Test if there are configuration options that were
 128  * changed since the last save.
 129  *
 130  * @param cfg configuration to inspect
 131  * @return GNUNET_NO if clean, GNUNET_YES if dirty, GNUNET_SYSERR on error (i.e. last save failed)
 132  */
 133 int
 134 GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg);
 135
 136
 137 /**
 138  * Function to iterate over options.
 139  *
 140  * @param cls closure
 141  * @param section name of the section
 142  * @param option name of the option
 143  * @param value value of the option
 144  */
 145 typedef void (*GNUNET_CONFIGURATION_Iterator) (void *cls, const char *section,
 146                                                const char *option,
 147                                                const char *value);
 148
 149
 150 /**
 151  * Function to iterate over section.
 152  *
 153  * @param cls closure
 154  * @param section name of the section
 155  */
 156 typedef void (*GNUNET_CONFIGURATION_Section_Iterator) (void *cls,
 157                                                        const char *section);
 158
 159
 160 /**
 161  * Iterate over all options in the configuration.
 162  *
 163  * @param cfg configuration to inspect
 164  * @param iter function to call on each option
 165  * @param iter_cls closure for iter
 166  */
 167 void
 168 GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 169                               GNUNET_CONFIGURATION_Iterator iter,
 170                               void *iter_cls);
 171
 172
 173 /**
 174  * Iterate over all sections in the configuration.
 175  *
 176  * @param cfg configuration to inspect
 177  * @param iter function to call on each section
 178  * @param iter_cls closure for iter
 179  */
 180 void
 181 GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle
 182                                        *cfg,
 183                                        GNUNET_CONFIGURATION_Section_Iterator
 184                                        iter, void *iter_cls);
 185
 186
 187 /**
 188  * Remove the given section and all options in it.
 189  *
 190  * @param cfg configuration to inspect
 191  * @param section name of the section to remove
 192  */
 193 void
 194 GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg,
 195                                      const char *section);
 196
 197 /**
 198  * Get a configuration value that should be a number.
 199  *
 200  * @param cfg configuration to inspect
 201  * @param section section of interest
 202  * @param option option of interest
 203  * @param number where to store the numeric value of the option
 204  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 205  */
 206 int
 207 GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle
 208                                        *cfg, const char *section,
 209                                        const char *option,
 210                                        unsigned long long *number);
 211
 212
 213 /**
 214  * Get a configuration value that should be a relative time.
 215  *
 216  * @param cfg configuration to inspect
 217  * @param section section of interest
 218  * @param option option of interest
 219  * @param time set to the time value stored in the configuration
 220  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 221  */
 222 int
 223 GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle
 224                                      *cfg, const char *section,
 225                                      const char *option,
 226                                      struct GNUNET_TIME_Relative *time);
 227
 228
 229
 230 /**
 231  * Get a configuration value that should be a size in bytes.
 232  *
 233  * @param cfg configuration to inspect
 234  * @param section section of interest
 235  * @param option option of interest
 236  * @param size set to the size in bytes as stored in the configuration
 237  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 238  */
 239 int
 240 GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle
 241                                      *cfg, const char *section,
 242                                      const char *option,
 243                                      unsigned long long *size);
 244
 245
 246 /**
 247  * Test if we have a value for a particular option
 248  *
 249  * @param cfg configuration to inspect
 250  * @param section section of interest
 251  * @param option option of interest
 252  * @return GNUNET_YES if so, GNUNET_NO if not.
 253  */
 254 int
 255 GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 256                                  const char *section, const char *option);
 257
 258
 259 /**
 260  * Get a configuration value that should be a string.
 261  *
 262  * @param cfg configuration to inspect
 263  * @param section section of interest
 264  * @param option option of interest
 265  * @param value will be set to a freshly allocated configuration
 266  *        value, or NULL if option is not specified
 267  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 268  */
 269 int
 270 GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle
 271                                        *cfg, const char *section,
 272                                        const char *option, char **value);
 273
 274
 275 /**
 276  * Get a configuration value that should be the name of a file
 277  * or directory.
 278  *
 279  * @param cfg configuration to inspect
 280  * @param section section of interest
 281  * @param option option of interest
 282  * @param value will be set to a freshly allocated configuration
 283  *        value, or NULL if option is not specified
 284  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 285  */
 286 int
 287 GNUNET_CONFIGURATION_get_value_filename (const struct
 288                                          GNUNET_CONFIGURATION_Handle *cfg,
 289                                          const char *section,
 290                                          const char *option, char **value);
 291
 292 /**
 293  * Iterate over the set of filenames stored in a configuration value.
 294  *
 295  * @param cfg configuration to inspect
 296  * @param section section of interest
 297  * @param option option of interest
 298  * @param cb function to call on each filename
 299  * @param cb_cls closure for cb
 300  * @return number of filenames iterated over, -1 on error
 301  */
 302 int
 303 GNUNET_CONFIGURATION_iterate_value_filenames (const struct
 304                                               GNUNET_CONFIGURATION_Handle *cfg,
 305                                               const char *section,
 306                                               const char *option,
 307                                               GNUNET_FileNameCallback cb,
 308                                               void *cb_cls);
 309
 310 /**
 311  * Iterate over values of a section in the configuration.
 312  *
 313  * @param cfg configuration to inspect
 314  * @param section the section
 315  * @param iter function to call on each option
 316  * @param iter_cls closure for iter
 317  */
 318 void
 319 GNUNET_CONFIGURATION_iterate_section_values (const struct
 320                                              GNUNET_CONFIGURATION_Handle *cfg,
 321                                              const char *section,
 322                                              GNUNET_CONFIGURATION_Iterator iter,
 323                                              void *iter_cls);
 324
 325 /**
 326  * Get a configuration value that should be in a set of
 327  * predefined strings
 328  *
 329  * @param cfg configuration to inspect
 330  * @param section section of interest
 331  * @param option option of interest
 332  * @param choices NULL-terminated list of legal values
 333  * @param value will be set to an entry in the legal list,
 334  *        or NULL if option is not specified and no default given
 335  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 336  */
 337 int
 338 GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle
 339                                        *cfg, const char *section,
 340                                        const char *option, const char **choices,
 341                                        const char **value);
 342
 343 /**
 344  * Get a configuration value that should be in a set of
 345  * "YES" or "NO".
 346  *
 347  * @param cfg configuration to inspect
 348  * @param section section of interest
 349  * @param option option of interest
 350  * @return GNUNET_YES, GNUNET_NO or if option has no valid value, GNUNET_SYSERR
 351  */
 352 int
 353 GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle
 354                                       *cfg, const char *section,
 355                                       const char *option);
 356
 357
 358 /**
 359  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 360  * where either in the "PATHS" section or the environtment
 361  * "FOO" is set to "DIRECTORY".
 362  *
 363  * @param cfg configuration to use for path expansion
 364  * @param orig string to $-expand (will be freed!)
 365  * @return $-expanded string
 366  */
 367 char *
 368 GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle
 369                                     *cfg, char *orig);
 370
 371
 372 /**
 373  * Set a configuration value that should be a number.
 374  *
 375  * @param cfg configuration to update
 376  * @param section section of interest
 377  * @param option option of interest
 378  * @param number value to set
 379  */
 380 void
 381 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg,
 382                                        const char *section, const char *option,
 383                                        unsigned long long number);
 384
 385
 386 /**
 387  * Set a configuration value that should be a string.
 388  *
 389  * @param cfg configuration to update
 390  * @param section section of interest
 391  * @param option option of interest
 392  * @param value value to set
 393  */
 394 void
 395 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg,
 396                                        const char *section, const char *option,
 397                                        const char *value);
 398
 399
 400 /**
 401  * Remove a filename from a configuration value that
 402  * represents a list of filenames
 403  *
 404  * @param cfg configuration to update
 405  * @param section section of interest
 406  * @param option option of interest
 407  * @param value filename to remove
 408  * @return GNUNET_OK on success,
 409  *         GNUNET_SYSERR if the filename is not in the list
 410  */
 411 int
 412 GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle
 413                                             *cfg, const char *section,
 414                                             const char *option,
 415                                             const char *value);
 416
 417 /**
 418  * Append a filename to a configuration value that
 419  * represents a list of filenames
 420  *
 421  * @param cfg configuration to update
 422  * @param section section of interest
 423  * @param option option of interest
 424  * @param value filename to append
 425  * @return GNUNET_OK on success,
 426  *         GNUNET_SYSERR if the filename already in the list
 427  */
 428 int
 429 GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle
 430                                             *cfg, const char *section,
 431                                             const char *option,
 432                                             const char *value);
 433
 434
 435 #if 0                           /* keep Emacsens' auto-indent happy */
 436 {
 437 #endif
 438 #ifdef __cplusplus
 439 }
 440 #endif
 441
 442 #endif