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