Fix some Doxygen issues
[strongswan.git] / src / libcharon / plugins / vici / vici_message.h
1 /*
2 * Copyright (C) 2015 Tobias Brunner
3 * Hochschule fuer Technik Rapperswil
4 *
5 * Copyright (C) 2014 Martin Willi
6 * Copyright (C) 2014 revosec AG
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU General Public License as published by the
10 * Free Software Foundation; either version 2 of the License, or (at your
11 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12 *
13 * This program is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 * for more details.
17 */
18
19 /**
20 * @defgroup vici_message vici_message
21 * @{ @ingroup vici
22 */
23
24 #ifndef VICI_MESSAGE_H_
25 #define VICI_MESSAGE_H_
26
27 #include <library.h>
28
29 typedef struct vici_message_t vici_message_t;
30 typedef struct vici_parse_context_t vici_parse_context_t;
31 typedef enum vici_type_t vici_type_t;
32
33 /**
34 * Vici message encoding types
35 */
36 enum vici_type_t {
37 /** never used in an argument list, needed by dump as initial value */
38 VICI_START = 0,
39
40 /** begin of new section, argument is section name as char* */
41 VICI_SECTION_START = 1,
42 /** end of current section, no arguments */
43 VICI_SECTION_END = 2,
44 /** key/value, arguments are key as char*, value as chunk_t */
45 VICI_KEY_VALUE = 3,
46 /** list start, argument is list name as char* */
47 VICI_LIST_START = 4,
48 /** list item, argument is item value as chunk_t */
49 VICI_LIST_ITEM = 5,
50 /** end of list, no arguments */
51 VICI_LIST_END = 6,
52
53 /** end of argument list, no arguments (never encoded) */
54 VICI_END = 7
55 };
56
57 /**
58 * Callback function for key/value and list items, invoked by parse().
59 *
60 * @param user user data, as passed to parse()
61 * @param message message currently parsing
62 * @param name name of key or list
63 * @param value parsed value
64 * @return TRUE if parsed successfully
65 */
66 typedef bool (*vici_value_cb_t)(void *user, vici_message_t *message,
67 char *name, chunk_t value);
68
69 /**
70 * Callback function for sections, invoked by parse().
71 *
72 * @param user user data, as passed to parse()
73 * @param message message currently parsing
74 * @param ctx parse context, to pass to recursive parse() invocations.
75 * @param name name of the section
76 * @return TRUE if parsed successfully
77 */
78 typedef bool (*vici_section_cb_t)(void *user, vici_message_t *message,
79 vici_parse_context_t *ctx, char *name);
80
81 /**
82 * Names for vici encoding types
83 */
84 extern enum_name_t *vici_type_names;
85
86 /**
87 * Vici message representation, encoding/decoding routines.
88 */
89 struct vici_message_t {
90
91 /**
92 * Create an enumerator over message contents.
93 *
94 * The enumerator takes a fixed list of arguments, but depending on the
95 * type may set not all of them. It returns VICI_END as last argument
96 * to indicate the message end, and returns FALSE if parsing the message
97 * failed.
98 *
99 * @return enumerator over (vici_type_t, char*, chunk_t)
100 */
101 enumerator_t* (*create_enumerator)(vici_message_t *this);
102
103 /**
104 * Get the value of a key/value pair as a string.
105 *
106 * @param def default value if not found
107 * @param fmt printf style format string for key, with sections
108 * @param ... arguments to fmt string
109 * @return string
110 */
111 char* (*get_str)(vici_message_t *this, char *def, char *fmt, ...);
112
113 /**
114 * Get the value of a key/value pair as a string, va_list variant.
115 *
116 * @param def default value if not found
117 * @param fmt printf style format string for key, with sections
118 * @param args arguments to fmt string
119 * @return string
120 */
121 char* (*vget_str)(vici_message_t *this, char *def, char *fmt, va_list args);
122
123 /**
124 * Get the value of a key/value pair as integer.
125 *
126 * @param def default value if not found
127 * @param fmt printf style format string for key, with sections
128 * @param ... arguments to fmt string
129 * @return value
130 */
131 int (*get_int)(vici_message_t *this, int def, char *fmt, ...);
132
133 /**
134 * Get the value of a key/value pair as integer, va_list variant
135 *
136 * @param def default value if not found
137 * @param fmt printf style format string for key, with sections
138 * @param args arguments to fmt string
139 * @return value
140 */
141 int (*vget_int)(vici_message_t *this, int def, char *fmt, va_list args);
142
143 /**
144 * Get the value of a key/value pair as boolean.
145 *
146 * @param def default value if not found
147 * @param fmt printf style format string for key, with sections
148 * @param ... arguments to fmt string
149 * @return value
150 */
151 bool (*get_bool)(vici_message_t *this, bool def, char *fmt, ...);
152
153 /**
154 * Get the value of a key/value pair as boolean, va_list variant
155 *
156 * @param def default value if not found
157 * @param fmt printf style format string for key, with sections
158 * @param args arguments to fmt string
159 * @return value
160 */
161 bool (*vget_bool)(vici_message_t *this, bool def, char *fmt, va_list args);
162
163 /**
164 * Get the raw value of a key/value pair.
165 *
166 * @param def default value if not found
167 * @param fmt printf style format string for key, with sections
168 * @param ... arguments to fmt string
169 * @return value
170 */
171 chunk_t (*get_value)(vici_message_t *this, chunk_t def, char *fmt, ...);
172
173 /**
174 * Get the raw value of a key/value pair, va_list variant.
175 *
176 * @param def default value if not found
177 * @param fmt printf style format string for key, with sections
178 * @param args arguments to fmt string
179 * @return value
180 */
181 chunk_t (*vget_value)(vici_message_t *this, chunk_t def,
182 char *fmt, va_list args);
183
184 /**
185 * Get encoded message.
186 *
187 * @return message data, points to internal data
188 */
189 chunk_t (*get_encoding)(vici_message_t *this);
190
191 /**
192 * Parse a message using callback functions.
193 *
194 * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
195 * invoked for the current section level only. To descent into sections,
196 * call parse() from within a section callback using the provided parse
197 * context.
198 *
199 * @param ctx parse context, NULL for root level
200 * @param section callback invoked for each section
201 * @param kv callback invoked for key/value pairs
202 * @param li callback invoked for list items
203 * @param user user data to pass to callbacks
204 * @return TRUE if parsed successfully
205 */
206 bool (*parse)(vici_message_t *this, vici_parse_context_t *ctx,
207 vici_section_cb_t section, vici_value_cb_t kv,
208 vici_value_cb_t li, void *user);
209
210 /**
211 * Dump a message text representation to a FILE stream.
212 *
213 * @param label label to print for message
214 * @param pretty use pretty print with indentation
215 * @param out FILE stream to dump to
216 * @return TRUE if message valid
217 */
218 bool (*dump)(vici_message_t *this, char *label, bool pretty, FILE *out);
219
220 /**
221 * Destroy a vici_message_t.
222 */
223 void (*destroy)(vici_message_t *this);
224 };
225
226 /**
227 * Create a vici_message from encoded data.
228 *
229 * @param data message encoding
230 * @param cleanup TRUE to free data during
231 * @return message representation
232 */
233 vici_message_t *vici_message_create_from_data(chunk_t data, bool cleanup);
234
235 /**
236 * Create a vici_message from an enumerator.
237 *
238 * The enumerator uses the same signature as the enumerator returned
239 * by create_enumerator(), and gets destroyed by this function. It should
240 * return VICI_END to close the message, return FALSE to indicate a failure.
241 *
242 * @param enumerator enumerator over (vici_type_t, char*, chunk_t)
243 * @return message representation, NULL on error
244 */
245 vici_message_t *vici_message_create_from_enumerator(enumerator_t *enumerator);
246
247 /**
248 * Create vici message from a variable argument list.
249 *
250 * @param type first type beginning message
251 * @param ... vici_type_t and args, terminated by VICI_END
252 * @return message representation, NULL on error
253 */
254 vici_message_t *vici_message_create_from_args(vici_type_t type, ...);
255
256 /**
257 * Check if a chunk has a printable string, and print it to buf.
258 *
259 * @param chunk chunk containing potential string
260 * @param buf buffer to write string to
261 * @param size size of buf
262 * @return TRUE if printable and string written to buf
263 */
264 bool vici_stringify(chunk_t chunk, char *buf, size_t size);
265
266 /**
267 * Verify the occurrence of a given type for given section/list nesting
268 */
269 bool vici_verify_type(vici_type_t type, u_int section, bool list);
270
271 #endif /** VICI_MESSAGE_H_ @}*/