src/include/gnunet_configuration_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (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
 164                                   *cfg_default,
 165                                   const struct GNUNET_CONFIGURATION_Handle
 166                                   *cfg_new, 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
 178                                *cfg_default,
 179                                const struct GNUNET_CONFIGURATION_Handle
 180                                *cfg_new);
 181
 182
 183 /**
 184  * Test if there are configuration options that were
 185  * changed since the last save.
 186  *
 187  * @param cfg configuration to inspect
 188  * @return #GNUNET_NO if clean, #GNUNET_YES if dirty, #GNUNET_SYSERR on error (i.e. last save failed)
 189  */
 190 int
 191 GNUNET_CONFIGURATION_is_dirty (const struct GNUNET_CONFIGURATION_Handle *cfg);
 192
 193
 194 /**
 195  * Function to iterate over options.
 196  *
 197  * @param cls closure
 198  * @param section name of the section
 199  * @param option name of the option
 200  * @param value value of the option
 201  */
 202 typedef void (*GNUNET_CONFIGURATION_Iterator) (void *cls, 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 (*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 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 iter
 236  */
 237 void
 238 GNUNET_CONFIGURATION_iterate_sections (const struct GNUNET_CONFIGURATION_Handle
 239                                        *cfg,
 240                                        GNUNET_CONFIGURATION_Section_Iterator
 241                                        iter, 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  * 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
 265                                        *cfg, const char *section,
 266                                        const char *option,
 267                                        unsigned long long *number);
 268
 269
 270 /**
 271  * Get a configuration value that should be a relative time.
 272  *
 273  * @param cfg configuration to inspect
 274  * @param section section of interest
 275  * @param option option of interest
 276  * @param time set to the time value stored in the configuration
 277  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 278  */
 279 int
 280 GNUNET_CONFIGURATION_get_value_time (const struct GNUNET_CONFIGURATION_Handle
 281                                      *cfg, const char *section,
 282                                      const char *option,
 283                                      struct GNUNET_TIME_Relative *time);
 284
 285
 286
 287 /**
 288  * Get a configuration value that should be a size in bytes.
 289  *
 290  * @param cfg configuration to inspect
 291  * @param section section of interest
 292  * @param option option of interest
 293  * @param size set to the size in bytes as stored in the configuration
 294  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 295  */
 296 int
 297 GNUNET_CONFIGURATION_get_value_size (const struct GNUNET_CONFIGURATION_Handle
 298                                      *cfg, const char *section,
 299                                      const char *option,
 300                                      unsigned long long *size);
 301
 302
 303 /**
 304  * Test if we have a value for a particular option
 305  *
 306  * @param cfg configuration to inspect
 307  * @param section section of interest
 308  * @param option option of interest
 309  * @return #GNUNET_YES if so, #GNUNET_NO if not.
 310  */
 311 int
 312 GNUNET_CONFIGURATION_have_value (const struct GNUNET_CONFIGURATION_Handle *cfg,
 313                                  const char *section, const char *option);
 314
 315
 316 /**
 317  * Get a configuration value that should be a string.
 318  *
 319  * @param cfg configuration to inspect
 320  * @param section section of interest
 321  * @param option option of interest
 322  * @param value will be set to a freshly allocated configuration
 323  *        value, or NULL if option is not specified
 324  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 325  */
 326 int
 327 GNUNET_CONFIGURATION_get_value_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
 328                                        const char *section,
 329                                        const char *option,
 330                                        char **value);
 331
 332
 333 /**
 334  * Get a configuration value that should be the name of a file
 335  * or directory.
 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_filename (const struct GNUNET_CONFIGURATION_Handle *cfg,
 346                                          const char *section,
 347                                          const char *option, char **value);
 348
 349
 350 /**
 351  * Iterate over the set of filenames stored in a configuration value.
 352  *
 353  * @param cfg configuration to inspect
 354  * @param section section of interest
 355  * @param option option of interest
 356  * @param cb function to call on each filename
 357  * @param cb_cls closure for @a cb
 358  * @return number of filenames iterated over, -1 on error
 359  */
 360 int
 361 GNUNET_CONFIGURATION_iterate_value_filenames (const struct
 362                                               GNUNET_CONFIGURATION_Handle *cfg,
 363                                               const char *section,
 364                                               const char *option,
 365                                               GNUNET_FileNameCallback cb,
 366                                               void *cb_cls);
 367
 368 /**
 369  * Iterate over values of a section in the configuration.
 370  *
 371  * @param cfg configuration to inspect
 372  * @param section the section
 373  * @param iter function to call on each option
 374  * @param iter_cls closure for @a iter
 375  */
 376 void
 377 GNUNET_CONFIGURATION_iterate_section_values (const struct
 378                                              GNUNET_CONFIGURATION_Handle *cfg,
 379                                              const char *section,
 380                                              GNUNET_CONFIGURATION_Iterator iter,
 381                                              void *iter_cls);
 382
 383 /**
 384  * Get a configuration value that should be in a set of
 385  * predefined strings
 386  *
 387  * @param cfg configuration to inspect
 388  * @param section section of interest
 389  * @param option option of interest
 390  * @param choices NULL-terminated list of legal values
 391  * @param value will be set to an entry in the legal list,
 392  *        or NULL if option is not specified and no default given
 393  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 394  */
 395 int
 396 GNUNET_CONFIGURATION_get_value_choice (const struct GNUNET_CONFIGURATION_Handle
 397                                        *cfg, const char *section,
 398                                        const char *option, const char *const *choices,
 399                                        const char **value);
 400
 401 /**
 402  * Get a configuration value that should be in a set of
 403  * "YES" or "NO".
 404  *
 405  * @param cfg configuration to inspect
 406  * @param section section of interest
 407  * @param option option of interest
 408  * @return #GNUNET_YES, #GNUNET_NO or if option has no valid value, #GNUNET_SYSERR
 409  */
 410 int
 411 GNUNET_CONFIGURATION_get_value_yesno (const struct GNUNET_CONFIGURATION_Handle
 412                                       *cfg, const char *section,
 413                                       const char *option);
 414
 415
 416 /**
 417  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 418  * where either in the "PATHS" section or the environtment "FOO" is
 419  * set to "DIRECTORY".  We also support default expansion,
 420  * i.e. ${VARIABLE:-default} will expand to $VARIABLE if VARIABLE is
 421  * set in PATHS or the environment, and otherwise to "default".  Note
 422  * that "default" itself can also be a $-expression, thus
 423  * "${VAR1:-{$VAR2}}" will expand to VAR1 and if that is not defined
 424  * to VAR2.
 425  *
 426  * @param cfg configuration to use for path expansion
 427  * @param orig string to $-expand (will be freed!)  Note that multiple
 428  *          $-expressions can be present in this string.  They will all be
 429  *          $-expanded.
 430  * @return $-expanded string
 431  */
 432 char *
 433 GNUNET_CONFIGURATION_expand_dollar (const struct GNUNET_CONFIGURATION_Handle
 434                                     *cfg, char *orig);
 435
 436
 437 /**
 438  * Set a configuration value that should be a number.
 439  *
 440  * @param cfg configuration to update
 441  * @param section section of interest
 442  * @param option option of interest
 443  * @param number value to set
 444  */
 445 void
 446 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle *cfg,
 447                                        const char *section, const char *option,
 448                                        unsigned long long number);
 449
 450
 451 /**
 452  * Set a configuration value that should be a string.
 453  *
 454  * @param cfg configuration to update
 455  * @param section section of interest
 456  * @param option option of interest
 457  * @param value value to set
 458  */
 459 void
 460 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle *cfg,
 461                                        const char *section, const char *option,
 462                                        const char *value);
 463
 464
 465 /**
 466  * Remove a filename from a configuration value that
 467  * represents a list of filenames
 468  *
 469  * @param cfg configuration to update
 470  * @param section section of interest
 471  * @param option option of interest
 472  * @param value filename to remove
 473  * @return #GNUNET_OK on success,
 474  *         #GNUNET_SYSERR if the filename is not in the list
 475  */
 476 int
 477 GNUNET_CONFIGURATION_remove_value_filename (struct GNUNET_CONFIGURATION_Handle
 478                                             *cfg, const char *section,
 479                                             const char *option,
 480                                             const char *value);
 481
 482 /**
 483  * Append a filename to a configuration value that
 484  * represents a list of filenames
 485  *
 486  * @param cfg configuration to update
 487  * @param section section of interest
 488  * @param option option of interest
 489  * @param value filename to append
 490  * @return #GNUNET_OK on success,
 491  *         #GNUNET_SYSERR if the filename already in the list
 492  */
 493 int
 494 GNUNET_CONFIGURATION_append_value_filename (struct GNUNET_CONFIGURATION_Handle
 495                                             *cfg, const char *section,
 496                                             const char *option,
 497                                             const char *value);
 498
 499 /** @} */ /* end of group configuration */
 500
 501 #if 0                           /* keep Emacsens' auto-indent happy */
 502 {
 503 #endif
 504 #ifdef __cplusplus
 505 }
 506 #endif
 507
 508 #endif