src/include/gnunet_configuration_lib.h

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