Annotation of embedaddon/strongswan/src/libstrongswan/settings/settings.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (C) 2010-2018 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 Additional arguments will be applied to both section format
292: * strings so they must be compatible. And they are evaluated immediately,
293: * so arguments can't contain dots.
294: *
295: * @param section section for which a fallback is configured, printf style
296: * @param fallback fallback section, printf style
297: * @param ... argument list for section and fallback
298: */
299: void (*add_fallback)(settings_t *this, const char *section,
300: const char *fallback, ...);
301:
302: /**
303: * Load settings from the files matching the given pattern.
304: *
305: * If merge is TRUE, existing sections are extended, existing values
306: * replaced, by those found in the loaded files. If it is FALSE, existing
307: * sections are purged before reading the new config.
308: *
309: * @note If any of the files matching the pattern fails to load, no settings
310: * are added at all. So, it's all or nothing.
311: *
312: * @param pattern file pattern
313: * @param merge TRUE to merge config with existing values
314: * @return TRUE, if settings were loaded successfully
315: */
316: bool (*load_files)(settings_t *this, char *pattern, bool merge);
317:
318: /**
319: * Load settings from the files matching the given pattern.
320: *
321: * If merge is TRUE, existing sections are extended, existing values
322: * replaced, by those found in the loaded files. If it is FALSE, existing
323: * sections are purged before reading the new config.
324: *
325: * All settings are loaded relative to the given section. The section is
326: * created, if it does not yet exist.
327: *
328: * @note If any of the files matching the pattern fails to load, no settings
329: * are added at all. So, it's all or nothing.
330: *
331: * @param pattern file pattern
332: * @param merge TRUE to merge config with existing values
333: * @param section section name of parent section, printf style
334: * @param ... argument list for section
335: * @return TRUE, if settings were loaded successfully
336: */
337: bool (*load_files_section)(settings_t *this, char *pattern, bool merge,
338: char *section, ...);
339:
340: /**
341: * Load settings from the given string.
342: *
343: * If merge is TRUE, existing sections are extended, existing values
344: * replaced, by those found in the string. If it is FALSE, existing
345: * sections are purged before reading the new config.
346: *
347: * @note If the string contains _include_ statements they should be
348: * absolute paths.
349: *
350: * @note If any failures occur, no settings are added at all. So, it's all
351: * or nothing.
352: *
353: * @param settings string to parse
354: * @param merge TRUE to merge config with existing values
355: * @return TRUE, if settings were loaded successfully
356: */
357: bool (*load_string)(settings_t *this, char *settings, bool merge);
358:
359: /**
360: * Load settings from the given string.
361: *
362: * If merge is TRUE, existing sections are extended, existing values
363: * replaced, by those found in the string. If it is FALSE, existing
364: * sections are purged before reading the new config.
365: *
366: * All settings are loaded relative to the given section. The section is
367: * created, if it does not yet exist.
368: *
369: * @note If the string contains _include_ statements they should be
370: * absolute paths.
371: *
372: * @note If any failures occur, no settings are added at all. So, it's all
373: * or nothing.
374: *
375: * @param settings string to parse
376: * @param merge TRUE to merge config with existing values
377: * @param section section name of parent section, printf style
378: * @param ... argument list for section
379: * @return TRUE, if settings were loaded successfully
380: */
381: bool (*load_string_section)(settings_t *this, char *settings, bool merge,
382: char *section, ...);
383:
384: /**
385: * Destroy a settings instance.
386: */
387: void (*destroy)(settings_t *this);
388: };
389:
390: /**
391: * Load settings from a file.
392: *
393: * @note If parsing the file fails the object is still created.
394: *
395: * @param file optional file to read settings from
396: * @return settings object
397: */
398: settings_t *settings_create(char *file);
399:
400: /**
401: * Load settings from a string.
402: *
403: * @note If parsing the file fails the object is still created.
404: *
405: * @param settings string to read settings from
406: * @return settings object, or NULL
407: */
408: settings_t *settings_create_string(char *settings);
409:
410: /**
411: * Remove the given key/value.
412: *
413: * Compared to setting a key to NULL, which makes it appear to be unset (i.e.
414: * default values will apply) this removes the given key (if found) and
415: * references/fallbacks will apply when looking for that key. This is mainly
416: * usefuls for the unit tests.
417: *
418: * @param settings settings to remove key/value from
419: * @param key key including sections, printf style format
420: * @param ... argument list for key
421: */
422: void settings_remove_value(settings_t *settings, char *key, ...);
423:
424: #endif /** SETTINGS_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to settings.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / settings