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