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