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