Added documentation about new features of settings_t.
[strongswan.git] / 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_ @}*/