vici: Complete libvici doxygen comments
[strongswan.git] / src / libcharon / plugins / vici / libvici.h
1 /*
2 * Copyright (C) 2014 Martin Willi
3 * Copyright (C) 2014 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup libvici libvici
18 * @{ @ingroup vici
19 *
20 * libvici is a low-level client library for the "Versatile IKE Control
21 * Interface" protocol. While it uses libstrongswan and its thread-pool for
22 * asynchronous message delivery, this interface does not directly depend on
23 * libstrongswan interfaces and should be stable.
24 *
25 * This interface provides the following basic functions:
26 *
27 * - vici_init()/vici_deinit(): Library initialization functions
28 * - vici_connect(): Connect to a vici service
29 * - vici_disconnect(): Disconnect from a vici service
30 *
31 * Library initialization implicitly initializes libstrongswan and a small
32 * thread pool.
33 *
34 * Connecting requires an uri, which is currently either a UNIX socket path
35 * prefixed with unix://, or a hostname:port touple prefixed with tcp://.
36 * Passing NULL takes the system default socket path.
37 *
38 * After the connection has been established, request messages can be sent.
39 * Only a single thread may operate on a single connection instance
40 * simultaneously. To construct request messages, use the following functions:
41 *
42 * - vici_add_key_value() / vici_add_key_valuef(): Add key/value pairs
43 * - vici_begin(): Start constructing a new request message
44 * - vici_begin_section(): Open a new section to add contents to
45 * - vici_end_section(): Close a previously opened session
46 * - vici_begin_list(): Open a new list to add list items to
47 * - vici_end_list(): Close a previously opened list
48 * - vici_add_list_item() / vici_add_list_itemf(): Add list item
49 *
50 * Once the request message is complete, it can be sent or cancelled with:
51 *
52 * - vici_submit()
53 * - vici_free_req()
54 *
55 * If submitting a message is successful, a response message is returned. It
56 * can be processed using the following functions:
57 *
58 * - vici_parse(): Parse content type
59 * - vici_parse_name(): Parse name if content type provides one
60 * - vici_parse_name_eq(): Parse name and check if matches string
61 * - vici_parse_value() / vici_parse_value_str(): Parse value for content type
62 * - vici_dump(): Dump a full response to a FILE stream
63 * - vici_free_res(): Free response after use
64 *
65 * Usually vici_parse() is called in a loop, and depending on the returned
66 * type the name and value can be inspected.
67 *
68 * To register or unregister for asynchronous event messages vici_register() is
69 * used. The registered callback gets invoked by an asynchronous thread. To
70 * parse the event message, the vici_parse*() functions can be used.
71 */
72
73 #ifndef LIBVICI_H_
74 #define LIBVICI_H_
75
76 #include <stdio.h>
77
78 /**
79 * Opaque vici connection contex.
80 */
81 typedef struct vici_conn_t vici_conn_t;
82
83 /**
84 * Opaque vici request message.
85 */
86 typedef struct vici_req_t vici_req_t;
87
88 /**
89 * Opaque vici response/event message.
90 */
91 typedef struct vici_res_t vici_res_t;
92
93 /**
94 * Vici parse result, as returned by vici_parse().
95 */
96 typedef enum {
97 /** encountered a section start, has a name */
98 VICI_PARSE_BEGIN_SECTION,
99 /** encountered a section end */
100 VICI_PARSE_END_SECTION,
101 /** encountered a list start, has a name */
102 VICI_PARSE_BEGIN_LIST,
103 /** encountered a list element, has a value */
104 VICI_PARSE_LIST_ITEM,
105 /** encountered a list end */
106 VICI_PARSE_END_LIST,
107 /** encountered a key/value pair, has a name and a value */
108 VICI_PARSE_KEY_VALUE,
109 /** encountered valid end of message */
110 VICI_PARSE_END,
111 /** parse error */
112 VICI_PARSE_ERROR,
113 } vici_parse_t;
114
115 /**
116 * Callback function invoked for received event messages.
117 *
118 * It is not allowed to call vici_submit() from this callback.
119 *
120 * @param user user data, as passed to vici_connect
121 * @param name name of received event
122 * @param msg associated event message, destroyed by libvici
123 */
124 typedef void (*vici_event_cb_t)(void *user, char *name, vici_res_t *msg);
125
126 /**
127 * Callback function for key/value and list items, invoked by vici_parse_cb().
128 *
129 * @param user user data, as passed to vici_parse_cb()
130 * @param res message currently parsing
131 * @param name name of key or list
132 * @param value value buffer
133 * @param len length of value buffer
134 * @return 0 if parsed successfully
135 */
136 typedef int (*vici_parse_value_cb_t)(void *user, vici_res_t *res, char *name,
137 void *value, int len);
138
139 /**
140 * Callback function for sections, invoked by vici_parse_cb().
141 *
142 * @param user user data, as passed to vici_parse_cb()
143 * @param res message currently parsing
144 * @param name name of the section
145 * @return 0 if parsed successfully
146 */
147 typedef int (*vici_parse_section_cb_t)(void *user, vici_res_t *res, char *name);
148
149 /**
150 * Open a new vici connection.
151 *
152 * On error, NULL is returned and errno is set appropriately.
153 *
154 * @param uri URI to connect to, NULL to use system default
155 * @return opaque vici connection context, NULL on error
156 */
157 vici_conn_t* vici_connect(char *uri);
158
159 /**
160 * Close a vici connection.
161 *
162 * @param conn connection context
163 */
164 void vici_disconnect(vici_conn_t *conn);
165
166 /**
167 * Begin a new vici message request.
168 *
169 * This function always succeeds.
170 *
171 * @param name name of request command
172 * @return request message, to add contents
173 */
174 vici_req_t* vici_begin(char *name);
175
176 /**
177 * Begin a new section in a vici request message.
178 *
179 * @param req request message to create a new section in
180 * @param name name of section to create
181 */
182 void vici_begin_section(vici_req_t *req, char *name);
183
184 /**
185 * End a previously opened section.
186 *
187 * @param req request message to close an open section in
188 */
189 void vici_end_section(vici_req_t *req);
190
191 /**
192 * Add a key/value pair, using an as-is blob as value.
193 *
194 * @param req request message to add key/value pair to
195 * @param key key name of key/value pair
196 * @param buf pointer to blob to add as value
197 * @param len length of value blob to add
198 */
199 void vici_add_key_value(vici_req_t *req, char *key, void *buf, int len);
200
201 /**
202 * Add a key/value pair, setting value from a printf() format string.
203 *
204 * @param req request message to add key/value pair to
205 * @param key key name of key/value pair
206 * @param fmt format string for value
207 * @param ... arguments to format string
208 */
209 void vici_add_key_valuef(vici_req_t *req, char *key, char *fmt, ...);
210
211 /**
212 * Begin a list in a request message.
213 *
214 * After starting a list, only list items can be added until the list gets
215 * closed by vici_end_list().
216 *
217 * @param req request message to begin list in
218 * @param name name of list to begin
219 */
220 void vici_begin_list(vici_req_t *req, char *name);
221
222 /**
223 * Add a list item to a currently open list, using an as-is blob.
224 *
225 * @param req request message to add list item to
226 * @param buf pointer to blob to add as value
227 * @param len length of value blob to add
228 */
229 void vici_add_list_item(vici_req_t *req, void *buf, int len);
230
231 /**
232 * Add a list item to a currently open list, using a printf() format string.
233 *
234 * @param req request message to add list item to
235 * @param fmt format string to create value from
236 * @param ... arguments to format string
237 */
238 void vici_add_list_itemf(vici_req_t *req, char *fmt, ...);
239
240 /**
241 * End a previously opened list in a request message.
242 *
243 * @param req request message to end list in
244 */
245 void vici_end_list(vici_req_t *req);
246
247 /**
248 * Submit a request message, and wait for response.
249 *
250 * On error, NULL is returned an errno is set appropriately. The request
251 * messages gets cleaned up by this call and gets invalid.
252 *
253 * @param req request message to send
254 * @param conn connection context to send message over
255 * @return response message, NULL on error
256 */
257 vici_res_t* vici_submit(vici_req_t *req, vici_conn_t *conn);
258
259 /**
260 * Cancel a request message started.
261 *
262 * If a request created by vici_begin() does not get submitted using
263 * vici_submit(), it has to get freed using this call.
264 *
265 * @param req request message to clean up
266 */
267 void vici_free_req(vici_req_t *req);
268
269 /**
270 * Dump a message text representation to a FILE stream.
271 *
272 * On error, errno is set appropriately.
273 *
274 * @param res response message to dump
275 * @param label a label to print for this message
276 * @param out FILE to dump to
277 * @return 0 if dumped complete message, 1 on error
278 */
279 int vici_dump(vici_res_t *res, char *label, FILE *out);
280
281 /**
282 * Parse next element from a vici response message.
283 *
284 * @param res response message to parse
285 * @return parse result
286 */
287 vici_parse_t vici_parse(vici_res_t *res);
288
289 /**
290 * Parse name tag / key of a previously parsed element.
291 *
292 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
293 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
294 *
295 * The string is valid until vici_free_res() is called.
296 *
297 * On error, errno is set appropriately.
298 *
299 * @param res response message to parse
300 * @return name tag / key, NULL on error
301 */
302 char* vici_parse_name(vici_res_t *res);
303
304 /**
305 * Compare name tag / key of a previusly parsed element.
306 *
307 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
308 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
309 *
310 * @param res response message to parse
311 * @param name string to compare
312 * @return 1 if name equals, 0 if not
313 */
314 int vici_parse_name_eq(vici_res_t *res, char *name);
315
316 /**
317 * Parse value of a previously parsed element, as a blob.
318 *
319 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
320 * VICI_PARSE_LIST_ITEM.
321 *
322 * The string is valid until vici_free_res() is called.
323 *
324 * On error, errno is set appropriately.
325 *
326 * @param len pointer receiving value length
327 * @return pointer to value, NULL on error
328 */
329 void* vici_parse_value(vici_res_t *res, int *len);
330
331 /**
332 * Parse value of a previously parsed element, as a string.
333 *
334 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
335 * VICI_PARSE_LIST_ITEM.
336 *
337 * This call is successful only if the value contains no non-printable
338 * characters. The string is valid until vici_free_res() is called.
339 *
340 * On error, errno is set appropriately.
341 *
342 * @param res response message to parse
343 * @return value as string, NULL on error
344 */
345 char* vici_parse_value_str(vici_res_t *res);
346
347 /**
348 * Parse a complete message with callbacks.
349 *
350 * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
351 * invoked for the current section level only. To descent into sections, call
352 * vici_parse_cb() from within a section callback.
353 *
354 * On error, errno is set appropriately.
355 *
356 * @param res message to parse
357 * @param section callback invoked for each section
358 * @param kv callback invoked for key/value pairs
359 * @param li callback invoked for list items
360 * @param user user data to pass to callbacks
361 * @return 0 if parsing successful
362 */
363 int vici_parse_cb(vici_res_t *res, vici_parse_section_cb_t section,
364 vici_parse_value_cb_t kv, vici_parse_value_cb_t li,
365 void *user);
366
367 /*
368 * Find a blob value in a message for a given key.
369 *
370 * Sections can be selected by prefixing them separated by dots.
371 *
372 * @param res response message to parse
373 * @param len length of returned object
374 * @param fmt printf format string of key and sections
375 * @param ... arguments to format string
376 * @return blob value, having *len bytes, NULL if not found
377 */
378 void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
379
380 /**
381 * Find a string value in a message for a given key.
382 *
383 * Sections can be selected by prefixing them separated by dots.
384 *
385 * @param res response message to parse
386 * @param def default value, if key not found
387 * @param fmt printf format string of key and sections
388 * @param ... arguments to format string
389 * @return string, def if not found
390 */
391 char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
392
393 /**
394 * Find an integer value in a message for a given key.
395 *
396 * Sections can be selected by prefixing them separated by dots.
397 *
398 * @param res response message to parse
399 * @param def default value, if key not found
400 * @param fmt printf format string of key and sections
401 * @param ... arguments to format string
402 * @return integer value, def if not found
403 */
404 int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
405
406 /**
407 * Clean up a received response message.
408 *
409 * Event messages get cleaned up by the library, it is not allowed to call
410 * vici_free_res() from within a vici_event_cb_t.
411 *
412 * @param res response message to free
413 */
414 void vici_free_res(vici_res_t *res);
415
416 /**
417 * (Un-)Register for events of a given kind.
418 *
419 * Events callbacks get invoked by a different thread from the libstrongswan
420 * thread pool. On failure, errno is set appropriately.
421 *
422 * @param conn connection context
423 * @param name name of event messages to register to
424 * @param cb callback function to register, NULL to unregister
425 * @param user user data passed to callback invocations
426 * @return 0 if registered successfully
427 */
428 int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
429
430 /**
431 * Initialize libvici before first time use.
432 */
433 void vici_init();
434
435 /**
436 * Deinitialize libvici after use.
437 */
438 void vici_deinit();
439
440 #endif /** LIBVICI_H_ @}*/