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