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  * @author Christian Grothoff
  25  * @defgroup configuration Configuration management
  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  * Load default configuration.  This function will parse the
  91  * defaults from the given defaults_d directory.
  92  *
  93  * @param cfg configuration to update
  94  * @param defaults_d directory with the defaults
  95  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  96  */
  97 int
  98 GNUNET_CONFIGURATION_load_from (struct GNUNET_CONFIGURATION_Handle *cfg,
  99                                 const char *defaults_d);
 100
 101
 102 /**
 103  * Parse a configuration file, add all of the options in the
 104  * file to the configuration environment.
 105  *
 106  * @param cfg configuration to update
 107  * @param filename name of the configuration file
 108  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 109  */
 110 int
 111 GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg,
 112                             const char *filename);
 113
 114
 115 /**
 116  * Serializes the given configuration.
 117  *
 118  * @param cfg configuration to serialize
 119  * @param size will be set to the size of the serialized memory block
 120  * @return the memory block where the serialized configuration is
 121  *           present. This memory should be freed by the caller
 122  */
 123 char *
 124 GNUNET_CONFIGURATION_serialize (const struct GNUNET_CONFIGURATION_Handle *cfg,
 125                                 size_t *size);
 126
 127
 128 /**
 129  * De-serializes configuration
 130  *
 131  * @param cfg configuration to update
 132  * @param mem the memory block of serialized configuration
 133  * @param size the size of the memory block
 134  * @param allow_inline set to #GNUNET_YES if we recursively load configuration
 135  *          from inlined configurations; #GNUNET_NO if not and raise warnings
 136  *          when we come across them
 137  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 138  */
 139 int
 140 GNUNET_CONFIGURATION_deserialize (struct GNUNET_CONFIGURATION_Handle *cfg,
 141                                   const char *mem,
 142                                   const size_t size,
 143                                   int allow_inline);
 144
 145
 146 /**
 147  * Write configuration file.
 148  *
 149  * @param cfg configuration to write
 150  * @param filename where to write the configuration
 151  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 152  */
 153 int
 154 GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
 155                             const char *filename);
 156
 157
 158 /**
 159  * Write only configuration entries that have been changed to configuration file
 160  * @param cfgDefault default configuration
 161  * @param cfgNew new configuration
 162  * @param filename where to write the configuration diff between default and new
 163  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 164  */
 165 int
 166 GNUNET_CONFIGURATION_write_diffs (const struct GNUNET_CONFIGURATION_Handle
 167                                   *cfgDefault,
 168                                   const struct GNUNET_CONFIGURATION_Handle
 169                                   *cfgNew, const char *filename);
 170
 171
 172 /**
 173  * Compute configuration with only entries that have been changed
 174  *
 175  * @param cfgDefault original configuration
 176  * @param cfgNew new configuration
 177  * @return configuration with only the differences, never NULL
 178  */
 179 struct GNUNET_CONFIGURATION_Handle *
 180 GNUNET_CONFIGURATION_get_diff (const struct GNUNET_CONFIGURATION_Handle
 181                                *cfgDefault,
 182                                const struct GNUNET_CONFIGURATION_Handle
 183                                *cfgNew);
 184
 185
 186 /**
 187  * Test if there are configuration options that were
 188  * changed since the last save.
 189  *
 190  * @param cfg configuration to inspect
 191  * @return #GNUNET_NO if clean, #GNUNET_YES if dirty, #GNUNET_SYSERR on error (i.e. last save failed)
 192  */
 193 int
 194 GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg);
 195
 196
 197 /**
 198  * Function to iterate over options.
 199  *
 200  * @param cls closure
 201  * @param section name of the section
 202  * @param option name of the option
 203  * @param value value of the option
 204  */
 205 typedef void (*GNUNET_CONFIGURATION_Iterator) (void *cls, const char *section,
 206                                                const char *option,
 207                                                const char *value);
 208
 209
 210 /**
 211  * Function to iterate over section.
 212  *
 213  * @param cls closure
 214  * @param section name of the section
 215  */
 216 typedef void (*GNUNET_CONFIGURATION_Section_Iterator) (void *cls,
 217                                                        const char *section);
 218
 219
 220 /**
 221  * Iterate over all options in the configuration.
 222  *
 223  * @param cfg configuration to inspect
 224  * @param iter function to call on each option
 225  * @param iter_cls closure for iter
 226  */
 227 void
 228 GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 229                               GNUNET_CONFIGURATION_Iterator iter,
 230                               void *iter_cls);
 231
 232
 233 /**
 234  * Iterate over all sections in the configuration.
 235  *
 236  * @param cfg configuration to inspect
 237  * @param iter function to call on each section
 238  * @param iter_cls closure for iter
 239  */
 240 void
 241 GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle
 242                                        *cfg,
 243                                        GNUNET_CONFIGURATION_Section_Iterator
 244                                        iter, void *iter_cls);
 245
 246
 247 /**
 248  * Remove the given section and all options in it.
 249  *
 250  * @param cfg configuration to inspect
 251  * @param section name of the section to remove
 252  */
 253 void
 254 GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg,
 255                                      const char *section);
 256
 257 /**
 258  * Get a configuration value that should be a number.
 259  *
 260  * @param cfg configuration to inspect
 261  * @param section section of interest
 262  * @param option option of interest
 263  * @param number where to store the numeric value of the option
 264  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 265  */
 266 int
 267 GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle
 268                                        *cfg, const char *section,
 269                                        const char *option,
 270                                        unsigned long long *number);
 271
 272
 273 /**
 274  * Get a configuration value that should be a relative time.
 275  *
 276  * @param cfg configuration to inspect
 277  * @param section section of interest
 278  * @param option option of interest
 279  * @param time set to the time value stored in the configuration
 280  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 281  */
 282 int
 283 GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle
 284                                      *cfg, const char *section,
 285                                      const char *option,
 286                                      struct GNUNET_TIME_Relative *time);
 287
 288
 289
 290 /**
 291  * Get a configuration value that should be a size in bytes.
 292  *
 293  * @param cfg configuration to inspect
 294  * @param section section of interest
 295  * @param option option of interest
 296  * @param size set to the size in bytes as stored in the configuration
 297  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 298  */
 299 int
 300 GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle
 301                                      *cfg, const char *section,
 302                                      const char *option,
 303                                      unsigned long long *size);
 304
 305
 306 /**
 307  * Test if we have a value for a particular option
 308  *
 309  * @param cfg configuration to inspect
 310  * @param section section of interest
 311  * @param option option of interest
 312  * @return #GNUNET_YES if so, #GNUNET_NO if not.
 313  */
 314 int
 315 GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 316                                  const char *section, const char *option);
 317
 318
 319 /**
 320  * Get a configuration value that should be a string.
 321  *
 322  * @param cfg configuration to inspect
 323  * @param section section of interest
 324  * @param option option of interest
 325  * @param value will be set to a freshly allocated configuration
 326  *        value, or NULL if option is not specified
 327  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 328  */
 329 int
 330 GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle
 331                                        *cfg, const char *section,
 332                                        const char *option, char **value);
 333
 334
 335 /**
 336  * Get a configuration value that should be the name of a file
 337  * or directory.
 338  *
 339  * @param cfg configuration to inspect
 340  * @param section section of interest
 341  * @param option option of interest
 342  * @param value will be set to a freshly allocated configuration
 343  *        value, or NULL if option is not specified
 344  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 345  */
 346 int
 347 GNUNET_CONFIGURATION_get_value_filename (const struct
 348                                          GNUNET_CONFIGURATION_Handle *cfg,
 349                                          const char *section,
 350                                          const char *option, char **value);
 351
 352 /**
 353  * Iterate over the set of filenames stored in a configuration value.
 354  *
 355  * @param cfg configuration to inspect
 356  * @param section section of interest
 357  * @param option option of interest
 358  * @param cb function to call on each filename
 359  * @param cb_cls closure for @a cb
 360  * @return number of filenames iterated over, -1 on error
 361  */
 362 int
 363 GNUNET_CONFIGURATION_iterate_value_filenames (const struct
 364                                               GNUNET_CONFIGURATION_Handle *cfg,
 365                                               const char *section,
 366                                               const char *option,
 367                                               GNUNET_FileNameCallback cb,
 368                                               void *cb_cls);
 369
 370 /**
 371  * Iterate over values of a section in the configuration.
 372  *
 373  * @param cfg configuration to inspect
 374  * @param section the section
 375  * @param iter function to call on each option
 376  * @param iter_cls closure for @a iter
 377  */
 378 void
 379 GNUNET_CONFIGURATION_iterate_section_values (const struct
 380                                              GNUNET_CONFIGURATION_Handle *cfg,
 381                                              const char *section,
 382                                              GNUNET_CONFIGURATION_Iterator iter,
 383                                              void *iter_cls);
 384
 385 /**
 386  * Get a configuration value that should be in a set of
 387  * predefined strings
 388  *
 389  * @param cfg configuration to inspect
 390  * @param section section of interest
 391  * @param option option of interest
 392  * @param choices NULL-terminated list of legal values
 393  * @param value will be set to an entry in the legal list,
 394  *        or NULL if option is not specified and no default given
 395  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 396  */
 397 int
 398 GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle
 399                                        *cfg, const char *section,
 400                                        const char *option, const char **choices,
 401                                        const char **value);
 402
 403 /**
 404  * Get a configuration value that should be in a set of
 405  * "YES" or "NO".
 406  *
 407  * @param cfg configuration to inspect
 408  * @param section section of interest
 409  * @param option option of interest
 410  * @return #GNUNET_YES, #GNUNET_NO or if option has no valid value, #GNUNET_SYSERR
 411  */
 412 int
 413 GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle
 414                                       *cfg, const char *section,
 415                                       const char *option);
 416
 417
 418 /**
 419  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 420  * where either in the "PATHS" section or the environtment
 421  * "FOO" is set to "DIRECTORY".
 422  *
 423  * @param cfg configuration to use for path expansion
 424  * @param orig string to $-expand (will be freed!)
 425  * @return $-expanded string
 426  */
 427 char *
 428 GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle
 429                                     *cfg, char *orig);
 430
 431
 432 /**
 433  * Set a configuration value that should be a number.
 434  *
 435  * @param cfg configuration to update
 436  * @param section section of interest
 437  * @param option option of interest
 438  * @param number value to set
 439  */
 440 void
 441 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg,
 442                                        const char *section, const char *option,
 443                                        unsigned long long number);
 444
 445
 446 /**
 447  * Set a configuration value that should be a string.
 448  *
 449  * @param cfg configuration to update
 450  * @param section section of interest
 451  * @param option option of interest
 452  * @param value value to set
 453  */
 454 void
 455 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg,
 456                                        const char *section, const char *option,
 457                                        const char *value);
 458
 459
 460 /**
 461  * Remove a filename from a configuration value that
 462  * represents a list of filenames
 463  *
 464  * @param cfg configuration to update
 465  * @param section section of interest
 466  * @param option option of interest
 467  * @param value filename to remove
 468  * @return #GNUNET_OK on success,
 469  *         #GNUNET_SYSERR if the filename is not in the list
 470  */
 471 int
 472 GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle
 473                                             *cfg, const char *section,
 474                                             const char *option,
 475                                             const char *value);
 476
 477 /**
 478  * Append a filename to a configuration value that
 479  * represents a list of filenames
 480  *
 481  * @param cfg configuration to update
 482  * @param section section of interest
 483  * @param option option of interest
 484  * @param value filename to append
 485  * @return #GNUNET_OK on success,
 486  *         #GNUNET_SYSERR if the filename already in the list
 487  */
 488 int
 489 GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle
 490                                             *cfg, const char *section,
 491                                             const char *option,
 492                                             const char *value);
 493
 494 /** @} */ /* end of group configuration */
 495
 496 #if 0                           /* keep Emacsens' auto-indent happy */
 497 {
 498 #endif
 499 #ifdef __cplusplus
 500 }
 501 #endif
 502
 503 #endif