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