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