4ef80d0f6dff52b12b76bb7aa7d0cdd357066593
[strongswan.git] / src / libstrongswan / settings / 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 * @defgroup settings_t settings
22 * @{ @ingroup settings
23 */
24
25 #ifndef SETTINGS_H_
26 #define SETTINGS_H_
27
28 typedef struct settings_t settings_t;
29
30 #include "utils/utils.h"
31 #include "collections/enumerator.h"
32
33 /**
34 * Convert a string value returned by a key/value enumerator to a boolean.
35 *
36 * @see settings_t.create_key_value_enumerator()
37 * @see settings_t.get_bool()
38 * @param value the string value
39 * @param def the default value, if value is NULL or invalid
40 */
41 bool settings_value_as_bool(char *value, bool def);
42
43 /**
44 * Convert a string value returned by a key/value enumerator to an integer.
45 *
46 * @see settings_t.create_key_value_enumerator()
47 * @see settings_t.get_int()
48 * @param value the string value
49 * @param def the default value, if value is NULL or invalid
50 */
51 int settings_value_as_int(char *value, int def);
52
53 /**
54 * Convert a string value returned by a key/value enumerator to a double.
55 *
56 * @see settings_t.create_key_value_enumerator()
57 * @see settings_t.get_double()
58 * @param value the string value
59 * @param def the default value, if value is NULL or invalid
60 */
61 double settings_value_as_double(char *value, double def);
62
63 /**
64 * Convert a string value returned by a key/value enumerator to a time value.
65 *
66 * @see settings_t.create_key_value_enumerator()
67 * @see settings_t.get_time()
68 * @param value the string value
69 * @param def the default value, if value is NULL or invalid
70 */
71 u_int32_t settings_value_as_time(char *value, u_int32_t def);
72
73 /**
74 * Generic configuration options read from a config file.
75 *
76 * The syntax is quite simple:
77 * @code
78 * settings := (section|keyvalue)*
79 * section := name { settings }
80 * keyvalue := key = value\n
81 * @endcode
82 * E.g.:
83 * @code
84 a = b
85 section-one {
86 somevalue = asdf
87 subsection {
88 othervalue = xxx
89 }
90 yetanother = zz
91 }
92 section-two {
93 }
94 @endcode
95 *
96 * The values are accessed using the get() functions using dotted keys, e.g.
97 * section-one.subsection.othervalue
98 *
99 * Currently only a limited set of printf format specifiers are supported
100 * (namely %s, %d and %N, see implementation for details).
101 *
102 * \section includes Including other files
103 * Other files can be included, using the include statement e.g.
104 * @code
105 * include /somepath/subconfig.conf
106 * @endcode
107 * Shell patterns like *.conf are possible.
108 *
109 * If the path is relative, the directory of the file containing the include
110 * statement is used as base.
111 *
112 * Sections loaded from included files extend previously loaded sections,
113 * already existing values are replaced.
114 *
115 * All settings included from files are added relative to the section the
116 * include statement is in.
117 *
118 * The following files result in the same final config as above:
119 *
120 * @code
121 a = b
122 section-one {
123 somevalue = before include
124 include include.conf
125 }
126 include two.conf
127 @endcode
128 * include.conf
129 * @code
130 somevalue = asdf
131 subsection {
132 othervalue = yyy
133 }
134 yetanother = zz
135 @endcode
136 * two.conf
137 * @code
138 section-one {
139 subsection {
140 othervalue = xxx
141 }
142 }
143 section-two {
144 }
145 @endcode
146 */
147 struct settings_t {
148
149 /**
150 * Get a settings value as a string.
151 *
152 * @param key key including sections, printf style format
153 * @param def value returned if key not found
154 * @param ... argument list for key
155 * @return value pointing to internal string
156 */
157 char* (*get_str)(settings_t *this, char *key, char *def, ...);
158
159 /**
160 * Get a boolean yes|no, true|false value.
161 *
162 * @param key key including sections, printf style format
163 * @param def value returned if key not found
164 * @param ... argument list for key
165 * @return value of the key
166 */
167 bool (*get_bool)(settings_t *this, char *key, bool def, ...);
168
169 /**
170 * Get an integer value.
171 *
172 * @param key key including sections, printf style format
173 * @param def value returned if key not found
174 * @param ... argument list for key
175 * @return value of the key
176 */
177 int (*get_int)(settings_t *this, char *key, int def, ...);
178
179 /**
180 * Get an double value.
181 *
182 * @param key key including sections, printf style format
183 * @param def value returned if key not found
184 * @param ... argument list for key
185 * @return value of the key
186 */
187 double (*get_double)(settings_t *this, char *key, double def, ...);
188
189 /**
190 * Get a time value.
191 *
192 * @param key key including sections, printf style format
193 * @param def value returned if key not found
194 * @param ... argument list for key
195 * @return value of the key (in seconds)
196 */
197 u_int32_t (*get_time)(settings_t *this, char *key, u_int32_t def, ...);
198
199 /**
200 * Set a string value.
201 *
202 * @param key key including sections, printf style format
203 * @param value value to set (gets cloned)
204 * @param ... argument list for key
205 */
206 void (*set_str)(settings_t *this, char *key, char *value, ...);
207
208 /**
209 * Set a boolean value.
210 *
211 * @param key key including sections, printf style format
212 * @param value value to set
213 * @param ... argument list for key
214 */
215 void (*set_bool)(settings_t *this, char *key, bool value, ...);
216
217 /**
218 * Set an integer value.
219 *
220 * @param key key including sections, printf style format
221 * @param value value to set
222 * @param ... argument list for key
223 */
224 void (*set_int)(settings_t *this, char *key, int value, ...);
225
226 /**
227 * Set an double value.
228 *
229 * @param key key including sections, printf style format
230 * @param value value to set
231 * @param ... argument list for key
232 */
233 void (*set_double)(settings_t *this, char *key, double value, ...);
234
235 /**
236 * Set a time value.
237 *
238 * @param key key including sections, printf style format
239 * @param def value to set
240 * @param ... argument list for key
241 */
242 void (*set_time)(settings_t *this, char *key, u_int32_t value, ...);
243
244 /**
245 * Set a default for string value.
246 *
247 * @param key key including sections, printf style format
248 * @param def value to set if unconfigured
249 * @param ... argument list for key
250 * @return TRUE if a new default value for key has been set
251 */
252 bool (*set_default_str)(settings_t *this, char *key, char *value, ...);
253
254 /**
255 * Create an enumerator over subsection names of a section.
256 *
257 * @param section section including parents, printf style format
258 * @param ... argument list for key
259 * @return enumerator over subsection names
260 */
261 enumerator_t* (*create_section_enumerator)(settings_t *this,
262 char *section, ...);
263
264 /**
265 * Create an enumerator over key/value pairs in a section.
266 *
267 * @param section section name to list key/value pairs of, printf style
268 * @param ... argument list for section
269 * @return enumerator over (char *key, char *value)
270 */
271 enumerator_t* (*create_key_value_enumerator)(settings_t *this,
272 char *section, ...);
273
274 /**
275 * Add a fallback for the given section.
276 *
277 * Example: When the fallback 'section-two' is configured for
278 * 'section-one.two' any failed lookup for a section or key in
279 * 'section-one.two' will result in a lookup for the same section/key
280 * in 'section-two'.
281 *
282 * @note Lookups are depth-first and currently strictly top-down.
283 * For instance, if app.sec had lib1.sec as fallback and lib1 had lib2 as
284 * fallback the keys/sections in lib2.sec would not be considered. But if
285 * app had lib3 as fallback the contents of lib3.sec would (as app is passed
286 * during the initial lookup). In the last example the order during
287 * enumerations would be app.sec, lib1.sec, lib3.sec.
288 *
289 * @note Additional arguments will be applied to both section format
290 * strings so they must be compatible.
291 *
292 * @param section section for which a fallback is configured, printf style
293 * @param fallback fallback section, printf style
294 * @param ... argument list for section and fallback
295 */
296 void (*add_fallback)(settings_t *this, const char *section,
297 const char *fallback, ...);
298
299 /**
300 * Load settings from the files matching the given pattern.
301 *
302 * If merge is TRUE, existing sections are extended, existing values
303 * replaced, by those found in the loaded files. If it is FALSE, existing
304 * sections are purged before reading the new config.
305 *
306 * @note If any of the files matching the pattern fails to load, no settings
307 * are added at all. So, it's all or nothing.
308 *
309 * @param pattern file pattern
310 * @param merge TRUE to merge config with existing values
311 * @return TRUE, if settings were loaded successfully
312 */
313 bool (*load_files)(settings_t *this, char *pattern, bool merge);
314
315 /**
316 * Load settings from the files matching the given pattern.
317 *
318 * If merge is TRUE, existing sections are extended, existing values
319 * replaced, by those found in the loaded files. If it is FALSE, existing
320 * sections are purged before reading the new config.
321 *
322 * All settings are loaded relative to the given section. The section is
323 * created, if it does not yet exist.
324 *
325 * @note If any of the files matching the pattern fails to load, no settings
326 * are added at all. So, it's all or nothing.
327 *
328 * @param pattern file pattern
329 * @param merge TRUE to merge config with existing values
330 * @param section section name of parent section, printf style
331 * @param ... argument list for section
332 * @return TRUE, if settings were loaded successfully
333 */
334 bool (*load_files_section)(settings_t *this, char *pattern, bool merge,
335 char *section, ...);
336
337 /**
338 * Load settings from the given string.
339 *
340 * If merge is TRUE, existing sections are extended, existing values
341 * replaced, by those found in the string. If it is FALSE, existing
342 * sections are purged before reading the new config.
343 *
344 * @note If the string contains _include_ statements they should be
345 * absolute paths.
346 *
347 * @note If any failures occur, no settings are added at all. So, it's all
348 * or nothing.
349 *
350 * @param settings string to parse
351 * @param merge TRUE to merge config with existing values
352 * @return TRUE, if settings were loaded successfully
353 */
354 bool (*load_string)(settings_t *this, char *settings, bool merge);
355
356 /**
357 * Load settings from the given string.
358 *
359 * If merge is TRUE, existing sections are extended, existing values
360 * replaced, by those found in the string. If it is FALSE, existing
361 * sections are purged before reading the new config.
362 *
363 * All settings are loaded relative to the given section. The section is
364 * created, if it does not yet exist.
365 *
366 * @note If the string contains _include_ statements they should be
367 * absolute paths.
368 *
369 * @note If any failures occur, no settings are added at all. So, it's all
370 * or nothing.
371 *
372 * @param settings string to parse
373 * @param merge TRUE to merge config with existing values
374 * @param section section name of parent section, printf style
375 * @param ... argument list for section
376 * @return TRUE, if settings were loaded successfully
377 */
378 bool (*load_string_section)(settings_t *this, char *settings, bool merge,
379 char *section, ...);
380
381 /**
382 * Destroy a settings instance.
383 */
384 void (*destroy)(settings_t *this);
385 };
386
387 /**
388 * Load settings from a file.
389 *
390 * @note If parsing the file fails the object is still created.
391 *
392 * @param file optional file to read settings from
393 * @return settings object
394 */
395 settings_t *settings_create(char *file);
396
397 /**
398 * Load settings from a string.
399 *
400 * @note If parsing the file fails the object is still created.
401 *
402 * @param settings string to read settings from
403 * @return settings object, or NULL
404 */
405 settings_t *settings_create_string(char *settings);
406
407 #endif /** SETTINGS_H_ @}*/