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