src/libstrongswan/utils/settings.h

   1 /*
   2  * Copyright (C) 2010 Tobias Brunner
   3  * Copyright (C) 2008 Martin Willi
   4  * Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup settings settings
  19  * @{ @ingroup utils
  20  */
  21
  22 #ifndef SETTINGS_H_
  23 #define SETTINGS_H_
  24
  25 typedef struct settings_t settings_t;
  26
  27 #include "../utils.h"
  28 #include "collections/enumerator.h"
  29
  30 /**
  31  * Convert a string value returned by a key/value enumerator to a boolean.
  32  *
  33  * @see settings_t.create_key_value_enumerator()
  34  * @see settings_t.get_bool()
  35  * @param value                 the string value
  36  * @param def                   the default value, if value is NULL or invalid
  37  */
  38 bool settings_value_as_bool(char *value, bool def);
  39
  40 /**
  41  * Convert a string value returned by a key/value enumerator to an integer.
  42  *
  43  * @see settings_t.create_key_value_enumerator()
  44  * @see settings_t.get_int()
  45  * @param value                 the string value
  46  * @param def                   the default value, if value is NULL or invalid
  47  */
  48 int settings_value_as_int(char *value, int def);
  49
  50 /**
  51  * Convert a string value returned by a key/value enumerator to a double.
  52  *
  53  * @see settings_t.create_key_value_enumerator()
  54  * @see settings_t.get_double()
  55  * @param value                 the string value
  56  * @param def                   the default value, if value is NULL or invalid
  57  */
  58 double settings_value_as_double(char *value, double def);
  59
  60 /**
  61  * Convert a string value returned by a key/value enumerator to a time value.
  62  *
  63  * @see settings_t.create_key_value_enumerator()
  64  * @see settings_t.get_time()
  65  * @param value                 the string value
  66  * @param def                   the default value, if value is NULL or invalid
  67  */
  68 u_int32_t settings_value_as_time(char *value, u_int32_t def);
  69
  70 /**
  71  * Generic configuration options read from a config file.
  72  *
  73  * The syntax is quite simple:
  74  * @code
  75  * settings := (section|keyvalue)*
  76  * section  := name { settings }
  77  * keyvalue := key = value\n
  78  * @endcode
  79  * E.g.:
  80  * @code
  81         a = b
  82         section-one {
  83                 somevalue = asdf
  84                 subsection {
  85                         othervalue = xxx
  86                 }
  87                 yetanother = zz
  88         }
  89         section-two {
  90         }
  91         @endcode
  92  *
  93  * The values are accessed using the get() functions using dotted keys, e.g.
  94  *   section-one.subsection.othervalue
  95  *
  96  * Currently only a limited set of printf format specifiers are supported
  97  * (namely %s, %d and %N, see implementation for details).
  98  *
  99  * \section includes Including other files
 100  * Other files can be included, using the include statement e.g.
 101  * @code
 102  *   include /somepath/subconfig.conf
 103  * @endcode
 104  * Shell patterns like *.conf are possible.
 105  *
 106  * If the path is relative, the directory of the file containing the include
 107  * statement is used as base.
 108  *
 109  * Sections loaded from included files extend previously loaded sections,
 110  * already existing values are replaced.
 111  *
 112  * All settings included from files are added relative to the section the
 113  * include statement is in.
 114  *
 115  * The following files result in the same final config as above:
 116  *
 117  * @code
 118         a = b
 119         section-one {
 120                 somevalue = before include
 121                 include include.conf
 122         }
 123         include two.conf
 124         @endcode
 125  * include.conf
 126  * @code
 127         somevalue = asdf
 128         subsection {
 129                 othervalue = yyy
 130         }
 131         yetanother = zz
 132         @endcode
 133  * two.conf
 134  * @code
 135         section-one {
 136                 subsection {
 137                         othervalue = xxx
 138                 }
 139         }
 140         section-two {
 141         }
 142         @endcode
 143  */
 144 struct settings_t {
 145
 146         /**
 147          * Get a settings value as a string.
 148          *
 149          * @param key           key including sections, printf style format
 150          * @param def           value returned if key not found
 151          * @param ...           argument list for key
 152          * @return                      value pointing to internal string
 153          */
 154         char* (*get_str)(settings_t *this, char *key, char *def, ...);
 155
 156         /**
 157          * Get a boolean yes|no, true|false value.
 158          *
 159          * @param key           key including sections, printf style format
 160          * @param def           value returned if key not found
 161          * @param ...           argument list for key
 162          * @return                      value of the key
 163          */
 164         bool (*get_bool)(settings_t *this, char *key, bool def, ...);
 165
 166         /**
 167          * Get an integer value.
 168          *
 169          * @param key           key including sections, printf style format
 170          * @param def           value returned if key not found
 171          * @param ...           argument list for key
 172          * @return                      value of the key
 173          */
 174         int (*get_int)(settings_t *this, char *key, int def, ...);
 175
 176         /**
 177          * Get an double value.
 178          *
 179          * @param key           key including sections, printf style format
 180          * @param def           value returned if key not found
 181          * @param ...           argument list for key
 182          * @return                      value of the key
 183          */
 184         double (*get_double)(settings_t *this, char *key, double def, ...);
 185
 186         /**
 187          * Get a time value.
 188          *
 189          * @param key           key including sections, printf style format
 190          * @param def           value returned if key not found
 191          * @param ...           argument list for key
 192          * @return                      value of the key (in seconds)
 193          */
 194         u_int32_t (*get_time)(settings_t *this, char *key, u_int32_t def, ...);
 195
 196         /**
 197          * Set a string value.
 198          *
 199          * @param key           key including sections, printf style format
 200          * @param value         value to set (gets cloned)
 201          * @param ...           argument list for key
 202          */
 203         void (*set_str)(settings_t *this, char *key, char *value, ...);
 204
 205         /**
 206          * Set a boolean value.
 207          *
 208          * @param key           key including sections, printf style format
 209          * @param value         value to set
 210          * @param ...           argument list for key
 211          */
 212         void (*set_bool)(settings_t *this, char *key, bool value, ...);
 213
 214         /**
 215          * Set an integer value.
 216          *
 217          * @param key           key including sections, printf style format
 218          * @param value         value to set
 219          * @param ...           argument list for key
 220          */
 221         void (*set_int)(settings_t *this, char *key, int value, ...);
 222
 223         /**
 224          * Set an double value.
 225          *
 226          * @param key           key including sections, printf style format
 227          * @param value         value to set
 228          * @param ...           argument list for key
 229          */
 230         void (*set_double)(settings_t *this, char *key, double value, ...);
 231
 232         /**
 233          * Set a time value.
 234          *
 235          * @param key           key including sections, printf style format
 236          * @param def           value to set
 237          * @param ...           argument list for key
 238          */
 239         void (*set_time)(settings_t *this, char *key, u_int32_t value, ...);
 240
 241         /**
 242          * Create an enumerator over subsection names of a section.
 243          *
 244          * @param section       section including parents, printf style format
 245          * @param ...           argument list for key
 246          * @return                      enumerator over subsection names
 247          */
 248         enumerator_t* (*create_section_enumerator)(settings_t *this,
 249                                                                                            char *section, ...);
 250
 251         /**
 252          * Create an enumerator over key/value pairs in a section.
 253          *
 254          * @param section       section name to list key/value pairs of, printf style
 255          * @param ...           argument list for section
 256          * @return                      enumerator over (char *key, char *value)
 257          */
 258         enumerator_t* (*create_key_value_enumerator)(settings_t *this,
 259                                                                                                  char *section, ...);
 260
 261         /**
 262          * Load settings from the files matching the given pattern.
 263          *
 264          * If merge is TRUE, existing sections are extended, existing values
 265          * replaced, by those found in the loaded files. If it is FALSE, existing
 266          * sections are purged before reading the new config.
 267          *
 268          * @note If any of the files matching the pattern fails to load, no settings
 269          * are added at all. So, it's all or nothing.
 270          *
 271          * @param pattern       file pattern
 272          * @param merge         TRUE to merge config with existing values
 273          * @return                      TRUE, if settings were loaded successfully
 274          */
 275         bool (*load_files)(settings_t *this, char *pattern, bool merge);
 276
 277         /**
 278          * Load settings from the files matching the given pattern.
 279          *
 280          * If merge is TRUE, existing sections are extended, existing values
 281          * replaced, by those found in the loaded files. If it is FALSE, existing
 282          * sections are purged before reading the new config.
 283          *
 284          * All settings are loaded relative to the given section. The section is
 285          * created, if it does not yet exist.
 286          *
 287          * @note If any of the files matching the pattern fails to load, no settings
 288          * are added at all. So, it's all or nothing.
 289          *
 290          * @param pattern       file pattern
 291          * @param merge         TRUE to merge config with existing values
 292          * @param section       section name of parent section, printf style
 293          * @param ...           argument list for section
 294          * @return                      TRUE, if settings were loaded successfully
 295          */
 296         bool (*load_files_section)(settings_t *this, char *pattern, bool merge,
 297                                                            char *section, ...);
 298
 299         /**
 300          * Destroy a settings instance.
 301          */
 302         void (*destroy)(settings_t *this);
 303 };
 304
 305 /**
 306  * Load settings from a file.
 307  *
 308  * @param file                  file to read settings from, NULL for default
 309  * @return                              settings object
 310  */
 311 settings_t *settings_create(char *file);
 312
 313 #endif /** SETTINGS_H_ @}*/