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