Annotation of embedaddon/strongswan/src/libstrongswan/settings/settings.h, revision 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