2 * Copyright (C) 2014 Martin Willi
3 * Copyright (C) 2014 revosec AG
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.
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:
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
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
28 * @defgroup libvici libvici
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.
36 * This interface provides the following basic functions:
38 * - vici_init()/vici_deinit(): Library initialization functions
39 * - vici_connect(): Connect to a vici service
40 * - vici_disconnect(): Disconnect from a vici service
42 * Library initialization implicitly initializes libstrongswan and a small
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.
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:
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
61 * Once the request message is complete, it can be sent or cancelled with:
66 * If submitting a message is successful, a response message is returned. It
67 * can be processed using the following functions:
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
76 * Usually vici_parse() is called in a loop, and depending on the returned
77 * type the name and value can be inspected.
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.
90 * Opaque vici connection contex.
92 typedef struct vici_conn_t vici_conn_t
;
95 * Opaque vici request message.
97 typedef struct vici_req_t vici_req_t
;
100 * Opaque vici response/event message.
102 typedef struct vici_res_t vici_res_t
;
105 * Vici parse result, as returned by vici_parse().
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 */
118 /** encountered a key/value pair, has a name and a value */
119 VICI_PARSE_KEY_VALUE
,
120 /** encountered valid end of message */
127 * Callback function invoked for received event messages.
129 * It is not allowed to call vici_submit() from this callback.
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
135 typedef void (*vici_event_cb_t
)(void *user
, char *name
, vici_res_t
*msg
);
138 * Callback function for key/value and list items, invoked by vici_parse_cb().
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
147 typedef int (*vici_parse_value_cb_t
)(void *user
, vici_res_t
*res
, char *name
,
148 void *value
, int len
);
151 * Callback function for sections, invoked by vici_parse_cb().
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
158 typedef int (*vici_parse_section_cb_t
)(void *user
, vici_res_t
*res
, char *name
);
161 * Open a new vici connection.
163 * On error, NULL is returned and errno is set appropriately.
165 * @param uri URI to connect to, NULL to use system default
166 * @return opaque vici connection context, NULL on error
168 vici_conn_t
* vici_connect(char *uri
);
171 * Close a vici connection.
173 * @param conn connection context
175 void vici_disconnect(vici_conn_t
*conn
);
178 * Begin a new vici message request.
180 * This function always succeeds.
182 * @param name name of request command
183 * @return request message, to add contents
185 vici_req_t
* vici_begin(char *name
);
188 * Begin a new section in a vici request message.
190 * @param req request message to create a new section in
191 * @param name name of section to create
193 void vici_begin_section(vici_req_t
*req
, char *name
);
196 * End a previously opened section.
198 * @param req request message to close an open section in
200 void vici_end_section(vici_req_t
*req
);
203 * Add a key/value pair, using an as-is blob as value.
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
210 void vici_add_key_value(vici_req_t
*req
, char *key
, void *buf
, int len
);
213 * Add a key/value pair, setting value from a printf() format string.
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
220 void vici_add_key_valuef(vici_req_t
*req
, char *key
, char *fmt
, ...);
223 * Begin a list in a request message.
225 * After starting a list, only list items can be added until the list gets
226 * closed by vici_end_list().
228 * @param req request message to begin list in
229 * @param name name of list to begin
231 void vici_begin_list(vici_req_t
*req
, char *name
);
234 * Add a list item to a currently open list, using an as-is blob.
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
240 void vici_add_list_item(vici_req_t
*req
, void *buf
, int len
);
243 * Add a list item to a currently open list, using a printf() format string.
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
249 void vici_add_list_itemf(vici_req_t
*req
, char *fmt
, ...);
252 * End a previously opened list in a request message.
254 * @param req request message to end list in
256 void vici_end_list(vici_req_t
*req
);
259 * Submit a request message, and wait for response.
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
268 * @param req request message to send
269 * @param conn connection context to send message over
270 * @return response message, NULL on error
272 vici_res_t
* vici_submit(vici_req_t
*req
, vici_conn_t
*conn
);
275 * Cancel a request message started.
277 * If a request created by vici_begin() does not get submitted using
278 * vici_submit(), it has to get freed using this call.
280 * @param req request message to clean up
282 void vici_free_req(vici_req_t
*req
);
285 * Dump a message text representation to a FILE stream.
287 * On error, errno is set to:
288 * - EBADMSG if the message is invalid
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
296 int vici_dump(vici_res_t
*res
, char *label
, int pretty
, FILE *out
);
299 * Parse next element from a vici response message.
301 * @param res response message to parse
302 * @return parse result
304 vici_parse_t
vici_parse(vici_res_t
*res
);
307 * Parse name tag / key of a previously parsed element.
309 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
310 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
312 * The string is valid until vici_free_res() is called.
314 * On error, errno is set to:
315 *- EINVAL if not in valid parser state
317 * @param res response message to parse
318 * @return name tag / key, NULL on error
320 char* vici_parse_name(vici_res_t
*res
);
323 * Compare name tag / key of a previusly parsed element.
325 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
326 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
328 * @param res response message to parse
329 * @param name string to compare
330 * @return 1 if name equals, 0 if not
332 int vici_parse_name_eq(vici_res_t
*res
, char *name
);
335 * Parse value of a previously parsed element, as a blob.
337 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
338 * VICI_PARSE_LIST_ITEM.
340 * The string is valid until vici_free_res() is called.
342 * On error, errno is set to:
343 * - EINVAL if not in valid parser state
345 * @param res response message to parse
346 * @param len pointer receiving value length
347 * @return pointer to value, NULL on error
349 void* vici_parse_value(vici_res_t
*res
, int *len
);
352 * Parse value of a previously parsed element, as a string.
354 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
355 * VICI_PARSE_LIST_ITEM.
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.
360 * On error, errno is set to:
361 * - EBADMSG if value is not a printable string
362 * - EINVAL if not in valid parser state
364 * @param res response message to parse
365 * @return value as string, NULL on error
367 char* vici_parse_value_str(vici_res_t
*res
);
370 * Parse a complete message with callbacks.
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.
376 * On error, errno is set to:
377 * - EBADMSG if message encoding invalid
378 * - Any other errno set by the invoked callbacks
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
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
,
392 * Find a blob value in a message for a given key.
394 * Sections can be selected by prefixing them separated by dots.
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
402 void *vici_find(vici_res_t
*res
, int *len
, char *fmt
, ...);
405 * Find a string value in a message for a given key.
407 * Sections can be selected by prefixing them separated by dots.
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
415 char* vici_find_str(vici_res_t
*res
, char *def
, char *fmt
, ...);
418 * Find an integer value in a message for a given key.
420 * Sections can be selected by prefixing them separated by dots.
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
428 int vici_find_int(vici_res_t
*res
, int def
, char *fmt
, ...);
431 * Clean up a received response message.
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.
436 * @param res response message to free
438 void vici_free_res(vici_res_t
*res
);
441 * (Un-)Register for events of a given kind.
443 * Events callbacks get invoked by a different thread from the libstrongswan
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
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
456 int vici_register(vici_conn_t
*conn
, char *name
, vici_event_cb_t cb
, void *user
);
459 * Initialize libvici before first time use.
464 * Deinitialize libvici after use.
468 #endif /** LIBVICI_H_ @}*/