src/include/gnunet_configuration_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2006, 2008, 2009 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14 */
  15
  16 /**
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * Configuration API
  21  *
  22  * @defgroup configuration  Configuration library
  23  * Configuration management
  24  * @{
  25  */
  26 #ifndef GNUNET_CONFIGURATION_LIB_H
  27 #define GNUNET_CONFIGURATION_LIB_H
  28
  29 #include "gnunet_time_lib.h"
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 /**
  40  * A configuration object.
  41  */
  42 struct GNUNET_CONFIGURATION_Handle;
  43
  44 /**
  45  * Create a new configuration object.
  46  * @return fresh configuration object
  47  */
  48 struct GNUNET_CONFIGURATION_Handle *
  49 GNUNET_CONFIGURATION_create (void);
  50
  51
  52 /**
  53  * Duplicate an existing configuration object.
  54  *
  55  * @param cfg configuration to duplicate
  56  * @return duplicate configuration
  57  */
  58 struct GNUNET_CONFIGURATION_Handle *
  59 GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *cfg);
  60
  61
  62 /**
  63  * Destroy configuration object.
  64  *
  65  * @param cfg configuration to destroy
  66  */
  67 void
  68 GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg);
  69
  70
  71 /**
  72  * Load configuration.  This function will first parse the
  73  * defaults and then parse the specific configuration file
  74  * to overwrite the defaults.
  75  *
  76  * @param cfg configuration to update
  77  * @param filename name of the configuration file, NULL to load defaults
  78  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  79  */
  80 int
  81 GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg,
  82                            const char *filename);
  83
  84
  85 /**
  86  * Load default configuration.  This function will parse the
  87  * defaults from the given @a defaults_d directory.
  88  *
  89  * @param cfg configuration to update
  90  * @param defaults_d directory with the defaults
  91  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  92  */
  93 int
  94 GNUNET_CONFIGURATION_load_from (struct GNUNET_CONFIGURATION_Handle *cfg,
  95                                 const char *defaults_d);
  96
  97
  98 /**
  99  * Parse a configuration file, add all of the options in the
 100  * file to the configuration environment.
 101  *
 102  * @param cfg configuration to update
 103  * @param filename name of the configuration file
 104  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 105  */
 106 int
 107 GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg,
 108                             const char *filename);
 109
 110
 111 /**
 112  * Serializes the given configuration.
 113  *
 114  * @param cfg configuration to serialize
 115  * @param size will be set to the size of the serialized memory block
 116  * @return the memory block where the serialized configuration is
 117  *           present. This memory should be freed by the caller
 118  */
 119 char *
 120 GNUNET_CONFIGURATION_serialize (const struct GNUNET_CONFIGURATION_Handle *cfg,
 121                                 size_t *size);
 122
 123
 124 /**
 125  * De-serializes configuration
 126  *
 127  * @param cfg configuration to update
 128  * @param mem the memory block of serialized configuration
 129  * @param size the size of the memory block
 130  * @param allow_inline set to the base directory if we recursively load configuration
 131  *          from inlined configurations; NULL if not and raise warnings
 132  *          when we come across them
 133  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 134  */
 135 int
 136 GNUNET_CONFIGURATION_deserialize (struct GNUNET_CONFIGURATION_Handle *cfg,
 137                                   const char *mem,
 138                                   size_t size,
 139                                   const char *basedir);
 140
 141
 142 /**
 143  * Write configuration file.
 144  *
 145  * @param cfg configuration to write
 146  * @param filename where to write the configuration
 147  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 148  */
 149 int
 150 GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
 151                             const char *filename);
 152
 153
 154 /**
 155  * Write only configuration entries that have been changed to configuration file
 156  * @param cfg_default default configuration
 157  * @param cfg_new new configuration
 158  * @param filename where to write the configuration diff between default and new
 159  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 160  */
 161 int
 162 GNUNET_CONFIGURATION_write_diffs (const struct GNUNET_CONFIGURATION_Handle *cfg_default,
 163                                   const struct GNUNET_CONFIGURATION_Handle *cfg_new,
 164                                   const char *filename);
 165
 166
 167 /**
 168  * Compute configuration with only entries that have been changed
 169  *
 170  * @param cfg_default original configuration
 171  * @param cfg_new new configuration
 172  * @return configuration with only the differences, never NULL
 173  */
 174 struct GNUNET_CONFIGURATION_Handle *
 175 GNUNET_CONFIGURATION_get_diff (const struct GNUNET_CONFIGURATION_Handle *cfg_default,
 176                                const struct GNUNET_CONFIGURATION_Handle *cfg_new);
 177
 178
 179 /**
 180  * Test if there are configuration options that were
 181  * changed since the last save.
 182  *
 183  * @param cfg configuration to inspect
 184  * @return #GNUNET_NO if clean, #GNUNET_YES if dirty, #GNUNET_SYSERR on error (i.e. last save failed)
 185  */
 186 int
 187 GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg);
 188
 189
 190 /**
 191  * Function to iterate over options.
 192  *
 193  * @param cls closure
 194  * @param section name of the section
 195  * @param option name of the option
 196  * @param value value of the option
 197  */
 198 typedef void
 199 (*GNUNET_CONFIGURATION_Iterator) (void *cls,
 200                                   const char *section,
 201                                   const char *option,
 202                                   const char *value);
 203
 204
 205 /**
 206  * Function to iterate over section.
 207  *
 208  * @param cls closure
 209  * @param section name of the section
 210  */
 211 typedef void
 212 (*GNUNET_CONFIGURATION_Section_Iterator) (void *cls,
 213                                           const char *section);
 214
 215
 216 /**
 217  * Iterate over all options in the configuration.
 218  *
 219  * @param cfg configuration to inspect
 220  * @param iter function to call on each option
 221  * @param iter_cls closure for @a iter
 222  */
 223 void
 224 GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 225                               GNUNET_CONFIGURATION_Iterator iter,
 226                               void *iter_cls);
 227
 228
 229 /**
 230  * Iterate over all sections in the configuration.
 231  *
 232  * @param cfg configuration to inspect
 233  * @param iter function to call on each section
 234  * @param iter_cls closure for @a iter
 235  */
 236 void
 237 GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle *cfg,
 238                                        GNUNET_CONFIGURATION_Section_Iterator iter,
 239                                        void *iter_cls);
 240
 241
 242 /**
 243  * Remove the given section and all options in it.
 244  *
 245  * @param cfg configuration to inspect
 246  * @param section name of the section to remove
 247  */
 248 void
 249 GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg,
 250                                      const char *section);
 251
 252
 253 /**
 254  * Get a configuration value that should be a number.
 255  *
 256  * @param cfg configuration to inspect
 257  * @param section section of interest
 258  * @param option option of interest
 259  * @param number where to store the numeric value of the option
 260  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 261  */
 262 int
 263 GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle *cfg,
 264                                        const char *section,
 265                                        const char *option,
 266                                        unsigned long long *number);
 267
 268
 269 /**
 270  * Get a configuration value that should be a floating point number.
 271  *
 272  * @param cfg configuration to inspect
 273  * @param section section of interest
 274  * @param option option of interest
 275  * @param number where to store the floating value of the option
 276  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 277  */
 278 int
 279 GNUNET_CONFIGURATION_get_value_float  (const struct GNUNET_CONFIGURATION_Handle *cfg,
 280                                        const char *section,
 281                                        const char *option,
 282                                        float *number);
 283
 284
 285 /**
 286  * Get a configuration value that should be a relative time.
 287  *
 288  * @param cfg configuration to inspect
 289  * @param section section of interest
 290  * @param option option of interest
 291  * @param time set to the time value stored in the configuration
 292  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 293  */
 294 int
 295 GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle *cfg,
 296                                      const char *section,
 297                                      const char *option,
 298                                      struct GNUNET_TIME_Relative *time);
 299
 300
 301
 302 /**
 303  * Get a configuration value that should be a size in bytes.
 304  *
 305  * @param cfg configuration to inspect
 306  * @param section section of interest
 307  * @param option option of interest
 308  * @param size set to the size in bytes as stored in the configuration
 309  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 310  */
 311 int
 312 GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle *cfg,
 313                                      const char *section,
 314                                      const char *option,
 315                                      unsigned long long *size);
 316
 317
 318 /**
 319  * Test if we have a value for a particular option
 320  *
 321  * @param cfg configuration to inspect
 322  * @param section section of interest
 323  * @param option option of interest
 324  * @return #GNUNET_YES if so, #GNUNET_NO if not.
 325  */
 326 int
 327 GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 328                                  const char *section,
 329                                  const char *option);
 330
 331
 332 /**
 333  * Get a configuration value that should be a string.
 334  *
 335  * @param cfg configuration to inspect
 336  * @param section section of interest
 337  * @param option option of interest
 338  * @param value will be set to a freshly allocated configuration
 339  *        value, or NULL if option is not specified
 340  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 341  */
 342 int
 343 GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
 344                                        const char *section,
 345                                        const char *option,
 346                                        char **value);
 347
 348
 349 /**
 350  * Get a configuration value that should be the name of a file
 351  * or directory.
 352  *
 353  * @param cfg configuration to inspect
 354  * @param section section of interest
 355  * @param option option of interest
 356  * @param value will be set to a freshly allocated configuration
 357  *        value, or NULL if option is not specified
 358  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 359  */
 360 int
 361 GNUNET_CONFIGURATION_get_value_filename (const struct GNUNET_CONFIGURATION_Handle *cfg,
 362                                          const char *section,
 363                                          const char *option,
 364                                          char **value);
 365
 366
 367 /**
 368  * Iterate over the set of filenames stored in a configuration value.
 369  *
 370  * @param cfg configuration to inspect
 371  * @param section section of interest
 372  * @param option option of interest
 373  * @param cb function to call on each filename
 374  * @param cb_cls closure for @a cb
 375  * @return number of filenames iterated over, -1 on error
 376  */
 377 int
 378 GNUNET_CONFIGURATION_iterate_value_filenames (const struct GNUNET_CONFIGURATION_Handle *cfg,
 379                                               const char *section,
 380                                               const char *option,
 381                                               GNUNET_FileNameCallback cb,
 382                                               void *cb_cls);
 383
 384 /**
 385  * Iterate over values of a section in the configuration.
 386  *
 387  * @param cfg configuration to inspect
 388  * @param section the section
 389  * @param iter function to call on each option
 390  * @param iter_cls closure for @a iter
 391  */
 392 void
 393 GNUNET_CONFIGURATION_iterate_section_values (const struct GNUNET_CONFIGURATION_Handle *cfg,
 394                                              const char *section,
 395                                              GNUNET_CONFIGURATION_Iterator iter,
 396                                              void *iter_cls);
 397
 398 /**
 399  * Get a configuration value that should be in a set of
 400  * predefined strings
 401  *
 402  * @param cfg configuration to inspect
 403  * @param section section of interest
 404  * @param option option of interest
 405  * @param choices NULL-terminated list of legal values
 406  * @param value will be set to an entry in the legal list,
 407  *        or NULL if option is not specified and no default given
 408  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 409  */
 410 int
 411 GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle *cfg,
 412                                        const char *section,
 413                                        const char *option,
 414                                        const char *const *choices,
 415                                        const char **value);
 416
 417 /**
 418  * Get a configuration value that should be in a set of
 419  * "YES" or "NO".
 420  *
 421  * @param cfg configuration to inspect
 422  * @param section section of interest
 423  * @param option option of interest
 424  * @return #GNUNET_YES, #GNUNET_NO or if option has no valid value, #GNUNET_SYSERR
 425  */
 426 int
 427 GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle *cfg,
 428                                       const char *section,
 429                                       const char *option);
 430
 431
 432 /**
 433  * Get Crockford32-encoded fixed-size binary data from a configuration.
 434  *
 435  * @param cfg configuration to access
 436  * @param section section to access
 437  * @param option option to access
 438  * @param buf where to store the decoded binary result
 439  * @param buf_size exact number of bytes to store in @a buf
 440  * @return #GNUNET_OK on success
 441  *         #GNUNET_NO is the value does not exist
 442  *         #GNUNET_SYSERR on decoding error
 443  */
 444 int
 445 GNUNET_CONFIGURATION_get_data (const struct GNUNET_CONFIGURATION_Handle *cfg,
 446                                const char *section,
 447                                const char *option,
 448                                void *buf,
 449                                size_t buf_size);
 450
 451
 452 /**
 453  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 454  * where either in the "PATHS" section or the environtment "FOO" is
 455  * set to "DIRECTORY".  We also support default expansion,
 456  * i.e. ${VARIABLE:-default} will expand to $VARIABLE if VARIABLE is
 457  * set in PATHS or the environment, and otherwise to "default".  Note
 458  * that "default" itself can also be a $-expression, thus
 459  * "${VAR1:-{$VAR2}}" will expand to VAR1 and if that is not defined
 460  * to VAR2.
 461  *
 462  * @param cfg configuration to use for path expansion
 463  * @param orig string to $-expand (will be freed!)  Note that multiple
 464  *          $-expressions can be present in this string.  They will all be
 465  *          $-expanded.
 466  * @return $-expanded string
 467  */
 468 char *
 469 GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle *cfg,
 470                                     char *orig);
 471
 472
 473 /**
 474  * Set a configuration value that should be a number.
 475  *
 476  * @param cfg configuration to update
 477  * @param section section of interest
 478  * @param option option of interest
 479  * @param number value to set
 480  */
 481 void
 482 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg,
 483                                        const char *section,
 484                                        const char *option,
 485                                        unsigned long long number);
 486
 487
 488 /**
 489  * Set a configuration value that should be a string.
 490  *
 491  * @param cfg configuration to update
 492  * @param section section of interest
 493  * @param option option of interest
 494  * @param value value to set
 495  */
 496 void
 497 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg,
 498                                        const char *section,
 499                                        const char *option,
 500                                        const char *value);
 501
 502
 503 /**
 504  * Remove a filename from a configuration value that
 505  * represents a list of filenames
 506  *
 507  * @param cfg configuration to update
 508  * @param section section of interest
 509  * @param option option of interest
 510  * @param value filename to remove
 511  * @return #GNUNET_OK on success,
 512  *         #GNUNET_SYSERR if the filename is not in the list
 513  */
 514 int
 515 GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg,
 516                                             const char *section,
 517                                             const char *option,
 518                                             const char *value);
 519
 520
 521 /**
 522  * Append a filename to a configuration value that
 523  * represents a list of filenames
 524  *
 525  * @param cfg configuration to update
 526  * @param section section of interest
 527  * @param option option of interest
 528  * @param value filename to append
 529  * @return #GNUNET_OK on success,
 530  *         #GNUNET_SYSERR if the filename already in the list
 531  */
 532 int
 533 GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg,
 534                                             const char *section,
 535                                             const char *option,
 536                                             const char *value);
 537
 538 #if 0                           /* keep Emacsens' auto-indent happy */
 539 {
 540 #endif
 541 #ifdef __cplusplus
 542 }
 543 #endif
 544
 545 #endif
 546
 547 /** @} */ /* end of group configuration */