2 * Copyright (C) 2015 Tobias Brunner
3 * Copyright (C) 2014 Martin Willi
5 * Copyright (C) secunet Security Networks AG
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19 * @defgroup vici_message vici_message
23 #ifndef VICI_MESSAGE_H_
24 #define VICI_MESSAGE_H_
28 typedef struct vici_message_t vici_message_t
;
29 typedef struct vici_parse_context_t vici_parse_context_t
;
30 typedef enum vici_type_t vici_type_t
;
33 * Vici message encoding types
36 /** never used in an argument list, needed by dump as initial value */
39 /** begin of new section, argument is section name as char* */
40 VICI_SECTION_START
= 1,
41 /** end of current section, no arguments */
43 /** key/value, arguments are key as char*, value as chunk_t */
45 /** list start, argument is list name as char* */
47 /** list item, argument is item value as chunk_t */
49 /** end of list, no arguments */
52 /** end of argument list, no arguments (never encoded) */
57 * Callback function for key/value and list items, invoked by parse().
59 * @param user user data, as passed to parse()
60 * @param message message currently parsing
61 * @param name name of key or list
62 * @param value parsed value
63 * @return TRUE if parsed successfully
65 typedef bool (*vici_value_cb_t
)(void *user
, vici_message_t
*message
,
66 char *name
, chunk_t value
);
69 * Callback function for sections, invoked by parse().
71 * @param user user data, as passed to parse()
72 * @param message message currently parsing
73 * @param ctx parse context, to pass to recursive parse() invocations.
74 * @param name name of the section
75 * @return TRUE if parsed successfully
77 typedef bool (*vici_section_cb_t
)(void *user
, vici_message_t
*message
,
78 vici_parse_context_t
*ctx
, char *name
);
81 * Names for vici encoding types
83 extern enum_name_t
*vici_type_names
;
86 * Vici message representation, encoding/decoding routines.
88 struct vici_message_t
{
91 * Create an enumerator over message contents.
93 * The enumerator takes a fixed list of arguments, but depending on the
94 * type may set not all of them. It returns VICI_END as last argument
95 * to indicate the message end, and returns FALSE if parsing the message
98 * @return enumerator over (vici_type_t, char*, chunk_t)
100 enumerator_t
* (*create_enumerator
)(vici_message_t
*this);
103 * Get the value of a key/value pair as a string.
105 * @param def default value if not found
106 * @param fmt printf style format string for key, with sections
107 * @param ... arguments to fmt string
110 char* (*get_str
)(vici_message_t
*this, char *def
, char *fmt
, ...);
113 * Get the value of a key/value pair as a string, va_list variant.
115 * @param def default value if not found
116 * @param fmt printf style format string for key, with sections
117 * @param args arguments to fmt string
120 char* (*vget_str
)(vici_message_t
*this, char *def
, char *fmt
, va_list args
);
123 * Get the value of a key/value pair as integer.
125 * @param def default value if not found
126 * @param fmt printf style format string for key, with sections
127 * @param ... arguments to fmt string
130 int (*get_int
)(vici_message_t
*this, int def
, char *fmt
, ...);
133 * Get the value of a key/value pair as integer, va_list variant
135 * @param def default value if not found
136 * @param fmt printf style format string for key, with sections
137 * @param args arguments to fmt string
140 int (*vget_int
)(vici_message_t
*this, int def
, char *fmt
, va_list args
);
143 * Get the value of a key/value pair as boolean.
145 * @param def default value if not found
146 * @param fmt printf style format string for key, with sections
147 * @param ... arguments to fmt string
150 bool (*get_bool
)(vici_message_t
*this, bool def
, char *fmt
, ...);
153 * Get the value of a key/value pair as boolean, va_list variant
155 * @param def default value if not found
156 * @param fmt printf style format string for key, with sections
157 * @param args arguments to fmt string
160 bool (*vget_bool
)(vici_message_t
*this, bool def
, char *fmt
, va_list args
);
163 * Get the raw value of a key/value pair.
165 * @param def default value if not found
166 * @param fmt printf style format string for key, with sections
167 * @param ... arguments to fmt string
170 chunk_t (*get_value
)(vici_message_t
*this, chunk_t def
, char *fmt
, ...);
173 * Get the raw value of a key/value pair, va_list variant.
175 * @param def default value if not found
176 * @param fmt printf style format string for key, with sections
177 * @param args arguments to fmt string
180 chunk_t (*vget_value
)(vici_message_t
*this, chunk_t def
,
181 char *fmt
, va_list args
);
184 * Get encoded message.
186 * @return message data, points to internal data
188 chunk_t (*get_encoding
)(vici_message_t
*this);
191 * Parse a message using callback functions.
193 * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
194 * invoked for the current section level only. To descent into sections,
195 * call parse() from within a section callback using the provided parse
198 * @param ctx parse context, NULL for root level
199 * @param section callback invoked for each section
200 * @param kv callback invoked for key/value pairs
201 * @param li callback invoked for list items
202 * @param user user data to pass to callbacks
203 * @return TRUE if parsed successfully
205 bool (*parse
)(vici_message_t
*this, vici_parse_context_t
*ctx
,
206 vici_section_cb_t section
, vici_value_cb_t kv
,
207 vici_value_cb_t li
, void *user
);
210 * Dump a message text representation to a FILE stream.
212 * @param label label to print for message
213 * @param pretty use pretty print with indentation
214 * @param out FILE stream to dump to
215 * @return TRUE if message valid
217 bool (*dump
)(vici_message_t
*this, char *label
, bool pretty
, FILE *out
);
220 * Destroy a vici_message_t.
222 void (*destroy
)(vici_message_t
*this);
226 * Create a vici_message from encoded data.
228 * @param data message encoding
229 * @param cleanup TRUE to free data during
230 * @return message representation
232 vici_message_t
*vici_message_create_from_data(chunk_t data
, bool cleanup
);
235 * Create a vici_message from an enumerator.
237 * The enumerator uses the same signature as the enumerator returned
238 * by create_enumerator(), and gets destroyed by this function. It should
239 * return VICI_END to close the message, return FALSE to indicate a failure.
241 * @param enumerator enumerator over (vici_type_t, char*, chunk_t)
242 * @return message representation, NULL on error
244 vici_message_t
*vici_message_create_from_enumerator(enumerator_t
*enumerator
);
247 * Create vici message from a variable argument list.
249 * @param type first type beginning message
250 * @param ... vici_type_t and args, terminated by VICI_END
251 * @return message representation, NULL on error
253 vici_message_t
*vici_message_create_from_args(vici_type_t type
, ...);
256 * Check if a chunk has a printable string, and print it to buf.
258 * @param chunk chunk containing potential string
259 * @param buf buffer to write string to
260 * @param size size of buf
261 * @return TRUE if printable and string written to buf
263 bool vici_stringify(chunk_t chunk
, char *buf
, size_t size
);
266 * Verify the occurrence of a given type for given section/list nesting
268 bool vici_verify_type(vici_type_t type
, u_int section
, bool list
);
270 #endif /** VICI_MESSAGE_H_ @}*/