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
  42 /**
  43  * A configuration object.
  44  */
  45 struct GNUNET_CONFIGURATION_Handle;
  46
  47 /**
  48  * Create a new configuration object.
  49  *
  50  * @param component name of responsible component
  51  */
  52 struct GNUNET_CONFIGURATION_Handle *GNUNET_CONFIGURATION_create (void);
  53
  54 /**
  55  * Destroy configuration object.
  56  */
  57 void GNUNET_CONFIGURATION_destroy (struct GNUNET_CONFIGURATION_Handle *cfg);
  58
  59 /**
  60  * Load configuration.  This function will first parse the
  61  * defaults and then parse the specific configuration file
  62  * to overwrite the defaults.
  63  *
  64  * @param filename name of the configuration file
  65  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  66  */
  67 int GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg,
  68                                const char *filename);
  69
  70 /**
  71  * Parse a configuration file, add all of the options in the
  72  * file to the configuration environment.
  73  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  74  */
  75 int GNUNET_CONFIGURATION_parse (struct GNUNET_CONFIGURATION_Handle *cfg,
  76                                 const char *filename);
  77
  78 /**
  79  * Write configuration file.
  80  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  81  */
  82 int GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
  83                                 const char *filename);
  84
  85 /**
  86  * Test if there are configuration options that were
  87  * changed since the last save.
  88  * @return GNUNET_NO if clean, GNUNET_YES if dirty, GNUNET_SYSERR on error (i.e. last save failed)
  89  */
  90 int GNUNET_CONFIGURATION_is_dirty (struct GNUNET_CONFIGURATION_Handle *cfg);
  91
  92 /**
  93  * Get a configuration value that should be a number.
  94  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  95  */
  96 int GNUNET_CONFIGURATION_get_value_number (struct GNUNET_CONFIGURATION_Handle
  97                                            *cfg, const char *section,
  98                                            const char *option,
  99                                            unsigned long long *number);
 100
 101 /**
 102  * Test if we have a value for a particular option
 103  * @return GNUNET_YES if so, GNUNET_NO if not.
 104  */
 105 int GNUNET_CONFIGURATION_have_value (struct GNUNET_CONFIGURATION_Handle *cfg,
 106                                      const char *section, const char *option);
 107
 108 /**
 109  * Get a configuration value that should be a string.
 110  * @param value will be set to a freshly allocated configuration
 111  *        value, or NULL if option is not specified
 112  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 113  */
 114 int GNUNET_CONFIGURATION_get_value_string (struct GNUNET_CONFIGURATION_Handle
 115                                            *cfg, const char *section,
 116                                            const char *option, char **value);
 117
 118 /**
 119  * Get a configuration value that should be the name of a file
 120  * or directory.
 121  *
 122  * @param value will be set to a freshly allocated configuration
 123  *        value, or NULL if option is not specified
 124  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 125  */
 126 int GNUNET_CONFIGURATION_get_value_filename (struct
 127                                              GNUNET_CONFIGURATION_Handle *cfg,
 128                                              const char *section,
 129                                              const char *option,
 130                                              char **value);
 131
 132 /**
 133  * Iterate over the set of filenames stored in a configuration value.
 134  *
 135  * @return number of filenames iterated over, -1 on error
 136  */
 137 int GNUNET_CONFIGURATION_iterate_value_filenames (struct
 138                                                   GNUNET_CONFIGURATION_Handle
 139                                                   *cfg,
 140                                                   const char *section,
 141                                                   const char *option,
 142                                                   GNUNET_FileNameCallback
 143                                                   cb, void *cls);
 144
 145 /**
 146  * Get a configuration value that should be in a set of
 147  * predefined strings
 148  *
 149  * @param choices NULL-terminated list of legal values
 150  * @param value will be set to an entry in the legal list,
 151  *        or NULL if option is not specified and no default given
 152  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 153  */
 154 int GNUNET_CONFIGURATION_get_value_choice (struct GNUNET_CONFIGURATION_Handle
 155                                            *cfg, const char *section,
 156                                            const char *option,
 157                                            const char **choices,
 158                                            const char **value);
 159
 160 /**
 161  * Get a configuration value that should be in a set of
 162  * "YES" or "NO".
 163  *
 164  * @return GNUNET_YES, GNUNET_NO or if option has no valid value, GNUNET_SYSERR
 165  */
 166 int GNUNET_CONFIGURATION_get_value_yesno (struct GNUNET_CONFIGURATION_Handle
 167                                           *cfg, const char *section,
 168                                           const char *option);
 169
 170 /**
 171  * Expand an expression of the form "$FOO/BAR" to "DIRECTORY/BAR"
 172  * where either in the "PATHS" section or the environtment
 173  * "FOO" is set to "DIRECTORY".
 174
 175  * @param old string to $-expand (will be freed!)
 176  * @return $-expanded string
 177  */
 178 char *GNUNET_CONFIGURATION_expand_dollar (struct GNUNET_CONFIGURATION_Handle
 179                                           *cfg, char *old);
 180
 181 /**
 182  * Set a configuration value that should be a number.
 183  */
 184 void
 185 GNUNET_CONFIGURATION_set_value_number (struct GNUNET_CONFIGURATION_Handle
 186                                        *cfg,
 187                                        const char *section,
 188                                        const char *option,
 189                                        unsigned long long number);
 190
 191
 192 /**
 193  * Set a configuration value that should be a string.
 194  * @param value
 195  */
 196 void
 197 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle
 198                                        *cfg,
 199                                        const char *section,
 200                                        const char *option, const char *value);
 201
 202 /**
 203  * Remove a filename from a configuration value that
 204  * represents a list of filenames
 205  *
 206  * @param value filename to remove
 207  * @return GNUNET_OK on success,
 208  *         GNUNET_SYSERR if the filename is not in the list
 209  */
 210 int GNUNET_CONFIGURATION_remove_value_filename (struct
 211                                                 GNUNET_CONFIGURATION_Handle
 212                                                 *cfg,
 213                                                 const char *section,
 214                                                 const char *option,
 215                                                 const char *value);
 216
 217 /**
 218  * Append a filename to a configuration value that
 219  * represents a list of filenames
 220  *
 221  * @param value filename to append
 222  * @return GNUNET_OK on success,
 223  *         GNUNET_SYSERR if the filename already in the list
 224  */
 225 int GNUNET_CONFIGURATION_append_value_filename (struct
 226                                                 GNUNET_CONFIGURATION_Handle
 227                                                 *cfg, const char *section,
 228                                                 const char *option,
 229                                                 const char *value);
 230
 231 #if 0                           /* keep Emacsens' auto-indent happy */
 232 {
 233 #endif
 234 #ifdef __cplusplus
 235 }
 236 #endif
 237
 238 #endif