src/include/gnunet_configuration_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2006, 2008, 2009, 2018 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  * Signature of a function to be run with a configuration.
 195  *
 196  * @param cls closure
 197  * @param cfg the configuration
 198  * @return status code
 199  */
 200 typedef int
 201 (*GNUNET_CONFIGURATION_Callback)(void *cls,
 202                                  const struct GNUNET_CONFIGURATION_Handle *cfg);
 203
 204
 205 /**
 206  * Parse a configuration file @a filename and run the function
 207  * @a cb with the resulting configuration object. Then free the
 208  * configuration object and return the status value from @a cb.
 209  *
 210  * @param filename configuration to parse, NULL for "default"
 211  * @param cb function to run
 212  * @param cb_cls closure for @a cb
 213  * @return #GNUNET_SYSERR if parsing the configuration failed,
 214  *   otherwise return value from @a cb.
 215  */
 216 int
 217 GNUNET_CONFIGURATION_parse_and_run (const char *filename,
 218                                     GNUNET_CONFIGURATION_Callback cb,
 219                                     void *cb_cls);
 220
 221
 222 /**
 223  * Function to iterate over options.
 224  *
 225  * @param cls closure
 226  * @param section name of the section
 227  * @param option name of the option
 228  * @param value value of the option
 229  */
 230 typedef void
 231 (*GNUNET_CONFIGURATION_Iterator) (void *cls,
 232                                   const char *section,
 233                                   const char *option,
 234                                   const char *value);
 235
 236
 237 /**
 238  * Function to iterate over section.
 239  *
 240  * @param cls closure
 241  * @param section name of the section
 242  */
 243 typedef void
 244 (*GNUNET_CONFIGURATION_Section_Iterator) (void *cls,
 245                                           const char *section);
 246
 247
 248 /**
 249  * Iterate over all options in the configuration.
 250  *
 251  * @param cfg configuration to inspect
 252  * @param iter function to call on each option
 253  * @param iter_cls closure for @a iter
 254  */
 255 void
 256 GNUNET_CONFIGURATION_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 257                               GNUNET_CONFIGURATION_Iterator iter,
 258                               void *iter_cls);
 259
 260
 261 /**
 262  * Iterate over all sections in the configuration.
 263  *
 264  * @param cfg configuration to inspect
 265  * @param iter function to call on each section
 266  * @param iter_cls closure for @a iter
 267  */
 268 void
 269 GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle *cfg,
 270                                        GNUNET_CONFIGURATION_Section_Iterator iter,
 271                                        void *iter_cls);
 272
 273
 274 /**
 275  * Remove the given section and all options in it.
 276  *
 277  * @param cfg configuration to inspect
 278  * @param section name of the section to remove
 279  */
 280 void
 281 GNUNET_CONFIGURATION_remove_section (struct GNUNET_CONFIGURATION_Handle *cfg,
 282                                      const char *section);
 283
 284
 285 /**
 286  * Get a configuration value that should be a number.
 287  *
 288  * @param cfg configuration to inspect
 289  * @param section section of interest
 290  * @param option option of interest
 291  * @param number where to store the numeric value of the option
 292  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 293  */
 294 int
 295 GNUNET_CONFIGURATION_get_value_number (const struct GNUNET_CONFIGURATION_Handle *cfg,
 296                                        const char *section,
 297                                        const char *option,
 298                                        unsigned long long *number);
 299
 300
 301 /**
 302  * Get a configuration value that should be a floating point number.
 303  *
 304  * @param cfg configuration to inspect
 305  * @param section section of interest
 306  * @param option option of interest
 307  * @param number where to store the floating value of the option
 308  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 309  */
 310 int
 311 GNUNET_CONFIGURATION_get_value_float  (const struct GNUNET_CONFIGURATION_Handle *cfg,
 312                                        const char *section,
 313                                        const char *option,
 314                                        float *number);
 315
 316
 317 /**
 318  * Get a configuration value that should be a relative time.
 319  *
 320  * @param cfg configuration to inspect
 321  * @param section section of interest
 322  * @param option option of interest
 323  * @param time set to the time value stored in the configuration
 324  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 325  */
 326 int
 327 GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle *cfg,
 328                                      const char *section,
 329                                      const char *option,
 330                                      struct GNUNET_TIME_Relative *time);
 331
 332
 333
 334 /**
 335  * Get a configuration value that should be a size in bytes.
 336  *
 337  * @param cfg configuration to inspect
 338  * @param section section of interest
 339  * @param option option of interest
 340  * @param size set to the size in bytes as stored in the configuration
 341  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 342  */
 343 int
 344 GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle *cfg,
 345                                      const char *section,
 346                                      const char *option,
 347                                      unsigned long long *size);
 348
 349
 350 /**
 351  * Test if we have a value for a particular option
 352  *
 353  * @param cfg configuration to inspect
 354  * @param section section of interest
 355  * @param option option of interest
 356  * @return #GNUNET_YES if so, #GNUNET_NO if not.
 357  */
 358 int
 359 GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 360                                  const char *section,
 361                                  const char *option);
 362
 363
 364 /**
 365  * Get a configuration value that should be a string.
 366  *
 367  * @param cfg configuration to inspect
 368  * @param section section of interest
 369  * @param option option of interest
 370  * @param value will be set to a freshly allocated configuration
 371  *        value, or NULL if option is not specified
 372  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 373  */
 374 int
 375 GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
 376                                        const char *section,
 377                                        const char *option,
 378                                        char **value);
 379
 380
 381 /**
 382  * Get a configuration value that should be the name of a file
 383  * or directory.
 384  *
 385  * @param cfg configuration to inspect
 386  * @param section section of interest
 387  * @param option option of interest
 388  * @param value will be set to a freshly allocated configuration
 389  *        value, or NULL if option is not specified
 390  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 391  */
 392 int
 393 GNUNET_CONFIGURATION_get_value_filename (const struct GNUNET_CONFIGURATION_Handle *cfg,
 394                                          const char *section,
 395                                          const char *option,
 396                                          char **value);
 397
 398
 399 /**
 400  * Iterate over the set of filenames stored in a configuration value.
 401  *
 402  * @param cfg configuration to inspect
 403  * @param section section of interest
 404  * @param option option of interest
 405  * @param cb function to call on each filename
 406  * @param cb_cls closure for @a cb
 407  * @return number of filenames iterated over, -1 on error
 408  */
 409 int
 410 GNUNET_CONFIGURATION_iterate_value_filenames (const struct GNUNET_CONFIGURATION_Handle *cfg,
 411                                               const char *section,
 412                                               const char *option,
 413                                               GNUNET_FileNameCallback cb,
 414                                               void *cb_cls);
 415
 416 /**
 417  * Iterate over values of a section in the configuration.
 418  *
 419  * @param cfg configuration to inspect
 420  * @param section the section
 421  * @param iter function to call on each option
 422  * @param iter_cls closure for @a iter
 423  */
 424 void
 425 GNUNET_CONFIGURATION_iterate_section_values (const struct GNUNET_CONFIGURATION_Handle *cfg,
 426                                              const char *section,
 427                                              GNUNET_CONFIGURATION_Iterator iter,
 428                                              void *iter_cls);
 429
 430 /**
 431  * Get a configuration value that should be in a set of
 432  * predefined strings
 433  *
 434  * @param cfg configuration to inspect
 435  * @param section section of interest
 436  * @param option option of interest
 437  * @param choices NULL-terminated list of legal values
 438  * @param value will be set to an entry in the legal list,
 439  *        or NULL if option is not specified and no default given
 440  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 441  */
 442 int
 443 GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle *cfg,
 444                                        const char *section,
 445                                        const char *option,
 446                                        const char *const *choices,
 447                                        const char **value);
 448
 449 /**
 450  * Get a configuration value that should be in a set of
 451  * "YES" or "NO".
 452  *
 453  * @param cfg configuration to inspect
 454  * @param section section of interest
 455  * @param option option of interest
 456  * @return #GNUNET_YES, #GNUNET_NO or if option has no valid value, #GNUNET_SYSERR
 457  */
 458 int
 459 GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle *cfg,
 460                                       const char *section,
 461                                       const char *option);
 462
 463
 464 /**
 465  * Get Crockford32-encoded fixed-size binary data from a configuration.
 466  *
 467  * @param cfg configuration to access
 468  * @param section section to access
 469  * @param option option to access
 470  * @param buf where to store the decoded binary result
 471  * @param buf_size exact number of bytes to store in @a buf
 472  * @return #GNUNET_OK on success
 473  *         #GNUNET_NO is the value does not exist
 474  *         #GNUNET_SYSERR on decoding error
 475  */
 476 int
 477 GNUNET_CONFIGURATION_get_data (const struct GNUNET_CONFIGURATION_Handle *cfg,
 478                                const char *section,
 479                                const char *option,
 480                                void *buf,
 481                                size_t buf_size);
 482
 483
 484 /**
 485  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 486  * where either in the "PATHS" section or the environtment "FOO" is
 487  * set to "DIRECTORY".  We also support default expansion,
 488  * i.e. ${VARIABLE:-default} will expand to $VARIABLE if VARIABLE is
 489  * set in PATHS or the environment, and otherwise to "default".  Note
 490  * that "default" itself can also be a $-expression, thus
 491  * "${VAR1:-{$VAR2}}" will expand to VAR1 and if that is not defined
 492  * to VAR2.
 493  *
 494  * @param cfg configuration to use for path expansion
 495  * @param orig string to $-expand (will be freed!)  Note that multiple
 496  *          $-expressions can be present in this string.  They will all be
 497  *          $-expanded.
 498  * @return $-expanded string
 499  */
 500 char *
 501 GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle *cfg,
 502                                     char *orig);
 503
 504
 505 /**
 506  * Set a configuration value that should be a number.
 507  *
 508  * @param cfg configuration to update
 509  * @param section section of interest
 510  * @param option option of interest
 511  * @param number value to set
 512  */
 513 void
 514 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg,
 515                                        const char *section,
 516                                        const char *option,
 517                                        unsigned long long number);
 518
 519
 520 /**
 521  * Set a configuration value that should be a string.
 522  *
 523  * @param cfg configuration to update
 524  * @param section section of interest
 525  * @param option option of interest
 526  * @param value value to set
 527  */
 528 void
 529 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg,
 530                                        const char *section,
 531                                        const char *option,
 532                                        const char *value);
 533
 534
 535 /**
 536  * Remove a filename from a configuration value that
 537  * represents a list of filenames
 538  *
 539  * @param cfg configuration to update
 540  * @param section section of interest
 541  * @param option option of interest
 542  * @param value filename to remove
 543  * @return #GNUNET_OK on success,
 544  *         #GNUNET_SYSERR if the filename is not in the list
 545  */
 546 int
 547 GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg,
 548                                             const char *section,
 549                                             const char *option,
 550                                             const char *value);
 551
 552
 553 /**
 554  * Append a filename to a configuration value that
 555  * represents a list of filenames
 556  *
 557  * @param cfg configuration to update
 558  * @param section section of interest
 559  * @param option option of interest
 560  * @param value filename to append
 561  * @return #GNUNET_OK on success,
 562  *         #GNUNET_SYSERR if the filename already in the list
 563  */
 564 int
 565 GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle *cfg,
 566                                             const char *section,
 567                                             const char *option,
 568                                             const char *value);
 569
 570 #if 0                           /* keep Emacsens' auto-indent happy */
 571 {
 572 #endif
 573 #ifdef __cplusplus
 574 }
 575 #endif
 576
 577 #endif
 578
 579 /** @} */ /* end of group configuration */