added doxygen comments
[strongswan.git] / src / libstrongswan / enum.h
1 /**
2 * @file enum.h
3 *
4 * @brief enum value to string conversion functions.
5 *
6 */
7
8 /*
9 * Copyright (C) 2006 Martin Willi
10 * Hochschule fuer Technik Rapperswil
11 *
12 * This program is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License as published by the
14 * Free Software Foundation; either version 2 of the License, or (at your
15 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * for more details.
21 */
22
23 #ifndef ENUM_H_
24 #define ENUM_H_
25
26 typedef struct enum_name_t enum_name_t;
27
28 /**
29 * @brief Struct to store names for enums.
30 *
31 * To print the string representation of enumeration values, the strings
32 * are stored in these structures. Every enum_name contains a range
33 * of strings, multiple ranges are linked together.
34 * Use the convenience macros to define these linked ranges.
35 *
36 * For a single range, use:
37 * ENUM(name, first, last, string1, string2, ...)
38 *
39 * For multiple linked ranges, use:
40 * ENUM_BEGIN(name, first, last, string1, string2, ...)
41 * ENUM_NEXT(name, first, last, last_from_previous, string3, ...)
42 * ENUM_NEXT(name, first, last, last_from_previous, string4, ...)
43 * ENUM_END(name, last_from_previous)
44 *
45 * The ENUM and the ENUM_END define a enum_name_t pointer with the name supplied
46 * in "name".
47 *
48 * Resolving of enum names is done using a printf hook. A printf fromat
49 * character %N is replaced by the enum string. Printf needs two arguments to
50 * resolve a %N, the enum_name_t* (the defined name in ENUM_BEGIN) followed
51 * by the numerical enum value.
52 */
53 struct enum_name_t {
54 /** value of the first enum string */
55 int first;
56 /** value of the last enum string */
57 int last;
58 /** next enum_name_t in list */
59 enum_name_t *next;
60 /** array of strings containing names from first to last */
61 char *names[];
62 };
63
64 /**
65 * @brief Begin a new enum_name list.
66 *
67 * @param name name of the enum_name list
68 * @param first enum value of the first enum string
69 * @param last enum value of the last enum string
70 * @param ... a list of strings
71 */
72 #define ENUM_BEGIN(name, first, last, ...) static enum_name_t name##last = {first, last, NULL, { __VA_ARGS__ }}
73
74 /**
75 * @brief Continue a enum name list startetd with ENUM_BEGIN.
76 *
77 * @param name name of the enum_name list
78 * @param first enum value of the first enum string
79 * @param last enum value of the last enum string
80 * @param prev enum value of the "last" defined in ENUM_BEGIN/previous ENUM_NEXT
81 * @param ... a list of strings
82 */
83 #define ENUM_NEXT(name, first, last, prev, ...) static enum_name_t name##last = {first, last, &name##prev, { __VA_ARGS__ }}
84
85 /**
86 * @brief Complete enum name list started with ENUM_BEGIN.
87 *
88 * @param name name of the enum_name list
89 * @param prev enum value of the "last" defined in ENUM_BEGIN/previous ENUM_NEXT
90 */
91 #define ENUM_END(name, prev) enum_name_t *name = &name##prev;
92
93 /**
94 * @brief Define a enum name with only one range.
95 *
96 * This is a convenience macro to use when a enum_name list contains only
97 * one range, and is equal as defining ENUM_BEGIN followed by ENUM_END.
98 *
99 * @param name name of the enum_name list
100 * @param first enum value of the first enum string
101 * @param last enum value of the last enum string
102 * @param ... a list of strings
103 */
104 #define ENUM(name, first, last, ...) ENUM_BEGIN(name, first, last, __VA_ARGS__); ENUM_END(name, last)
105
106 #endif /* ENUM_H_ */