src/libstrongswan/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 libstrongswan
  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 "utils/enumerator.h"
  29
  30 /**
  31  * Generic configuration options read from a config file.
  32  *
  33  * The syntax is quite simple:
  34  * @code
  35  * settings := (section|keyvalue)*
  36  * section  := name { settings }
  37  * keyvalue := key = value\n
  38  * @endcode
  39  * E.g.:
  40  * @code
  41         a = b
  42         section-one {
  43                 somevalue = asdf
  44                 subsection {
  45                         othervalue = xxx
  46                 }
  47                 yetanother = zz
  48         }
  49         section-two {
  50         }
  51         @endcode
  52  *
  53  * The values are accessed using the get() functions using dotted keys, e.g.
  54  *   section-one.subsection.othervalue
  55  *
  56  * Currently only a limited set of printf format specifiers are supported
  57  * (namely %s, %d and %N, see implementation for details).
  58  *
  59  * \section includes Including other files
  60  * Other files can be included, using the include statement e.g.
  61  * @code
  62  *   include /somepath/subconfig.conf
  63  * @endcode
  64  * Shell patterns like *.conf are possible.
  65  *
  66  * If the path is relative, the directory of the file containing the include
  67  * statement is used as base.
  68  *
  69  * Sections loaded from included files extend previously loaded sections,
  70  * already existing values are replaced.
  71  *
  72  * All settings included from files are added relative to the section the
  73  * include statment is in.
  74  *
  75  * The following files result in the same final config as above:
  76  *
  77  * @code
  78         a = b
  79         section-one {
  80                 somevalue = before include
  81                 include include.conf
  82         }
  83         include two.conf
  84         @endcode
  85  * include.conf
  86  * @code
  87         somevalue = asdf
  88         subsection {
  89                 othervalue = yyy
  90         }
  91         yetanother = zz
  92         @endcode
  93  * two.conf
  94  * @code
  95         section-one {
  96                 subsection {
  97                         othervalue = xxx
  98                 }
  99         }
 100         section-two {
 101         }
 102         @endcode
 103  */
 104 struct settings_t {
 105
 106         /**
 107          * Get a settings value as a string.
 108          *
 109          * @param key           key including sections, printf style format
 110          * @param def           value returned if key not found
 111          * @param ...           argument list for key
 112          * @return                      value pointing to internal string
 113          */
 114         char* (*get_str)(settings_t *this, char *key, char *def, ...);
 115
 116         /**
 117          * Get a boolean yes|no, true|false value.
 118          *
 119          * @param key           key including sections, printf style format
 120          * @param def           value returned if key not found
 121          * @param ...           argument list for key
 122          * @return                      value of the key
 123          */
 124         bool (*get_bool)(settings_t *this, char *key, bool def, ...);
 125
 126         /**
 127          * Get an integer value.
 128          *
 129          * @param key           key including sections, printf style format
 130          * @param def           value returned if key not found
 131          * @param ...           argument list for key
 132          * @return                      value of the key
 133          */
 134         int (*get_int)(settings_t *this, char *key, int def, ...);
 135
 136         /**
 137          * Get an double value.
 138          *
 139          * @param key           key including sections, printf style format
 140          * @param def           value returned if key not found
 141          * @param ...           argument list for key
 142          * @return                      value of the key
 143          */
 144         double (*get_double)(settings_t *this, char *key, double def, ...);
 145
 146         /**
 147          * Get a time value.
 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 of the key
 153          */
 154         u_int32_t (*get_time)(settings_t *this, char *key, u_int32_t def, ...);
 155
 156         /**
 157          * Create an enumerator over subsection names of a section.
 158          *
 159          * @param section       section including parents, printf style format
 160          * @param ...           argument list for key
 161          * @return                      enumerator over subsection names
 162          */
 163         enumerator_t* (*create_section_enumerator)(settings_t *this,
 164                                                                                            char *section, ...);
 165
 166         /**
 167          * Create an enumerator over key/value pairs in a section.
 168          *
 169          * @param section       section name to list key/value pairs of, printf style
 170          * @param ...           argmuent list for section
 171          * @return                      enumerator over (char *key, char *value)
 172          */
 173         enumerator_t* (*create_key_value_enumerator)(settings_t *this,
 174                                                                                                  char *section, ...);
 175
 176         /**
 177          * Load settings from the files matching the given pattern.
 178          *
 179          * Existing sections are extended, existing values replaced, by those found
 180          * in the loaded files.
 181          *
 182          * @note If any of the files matching the pattern fails to load, no settings
 183          * are added at all. So it's all or nothing.
 184          *
 185          * @param pattern       file pattern
 186          * @return                      TRUE, if settings were loaded successfully
 187          */
 188         bool (*load_files)(settings_t *this, char *pattern);
 189
 190         /**
 191          * Load settings from the files matching the given pattern.
 192          *
 193          * Existing sections are extended, existing values replaced, by those found
 194          * in the loaded files.
 195          *
 196          * All settings are loaded relative to the given section.
 197          *
 198          * @note If any of the files matching the pattern fails to load, no settings
 199          * are added at all. So it's all or nothing.
 200          *
 201          * @param pattern       file pattern
 202          * @param section       section name of parent section, printf style
 203          * @param ...           argument list for section
 204          * @return                      TRUE, if section is found and settings were loaded successfully
 205          */
 206         bool (*load_files_section)(settings_t *this, char *pattern,
 207                                                            char *section, ...);
 208
 209         /**
 210          * Destroy a settings instance.
 211          */
 212         void (*destroy)(settings_t *this);
 213 };
 214
 215 /**
 216  * Load settings from a file.
 217  *
 218  * @param file                  file to read settings from, NULL for default
 219  * @return                              settings object
 220  */
 221 settings_t *settings_create(char *file);
 222
 223 #endif /** SETTINGS_H_ @}*/