2689b39e176fc5b5b09ade783ff7dee7bc0ad0f2
[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 is basically required to set up libstrongswan and
32 * a small thread pool. Initialize libstrongswan manually instead.
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 * @param res response message to dump
273 * @param label a label to print for this message
274 * @param out FILE to dump to
275 * @return 0 if dumped complete message, 1 on error
276 */
277 int vici_dump(vici_res_t *res, char *label, FILE *out);
278
279 /**
280 * Parse next element from a vici response message.
281 *
282 * @param res response message to parse
283 * @return parse result
284 */
285 vici_parse_t vici_parse(vici_res_t *res);
286
287 /**
288 * Parse name tag / key of a previously parsed element.
289 *
290 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
291 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
292 *
293 * The string is valid until vici_free_res() is called.
294 *
295 * @param res response message to parse
296 * @return name tag / key, NULL on error
297 */
298 char* vici_parse_name(vici_res_t *res);
299
300 /**
301 * Compare name tag / key of a previusly parsed element.
302 *
303 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
304 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
305 *
306 * @param res response message to parse
307 * @param name string to compare
308 * @return 1 if name equals, 0 if not
309 */
310 int vici_parse_name_eq(vici_res_t *res, char *name);
311
312 /**
313 * Parse value of a previously parsed element, as a blob.
314 *
315 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
316 * VICI_PARSE_LIST_ITEM.
317 * The string is valid until vici_free_res() is called.
318 */
319 void* vici_parse_value(vici_res_t *res, int *len);
320
321 /**
322 * Parse value of a previously parsed element, as a string.
323 *
324 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
325 * VICI_PARSE_LIST_ITEM.
326 * This call is successful only if the value contains no non-printable
327 * characters. The string is valid until vici_free_res() is called.
328 *
329 * @param res response message to parse
330 * @return value as string, NULL on error
331 */
332 char* vici_parse_value_str(vici_res_t *res);
333
334 /**
335 * Parse a complete message with callbacks.
336 *
337 * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
338 * invoked for the current section level only. To descent into sections, call
339 * vici_parse_cb() from within a section callback.
340 *
341 * @param res message to parse
342 * @param section callback invoked for each section
343 * @param kv callback invoked for key/value pairs
344 * @param li callback invoked for list items
345 * @param user user data to pass to callbacks
346 * @return 0 if parsing successful
347 */
348 int vici_parse_cb(vici_res_t *res, vici_parse_section_cb_t section,
349 vici_parse_value_cb_t kv, vici_parse_value_cb_t li,
350 void *user);
351
352 /*
353 * Find a blob value in a message for a given key.
354 *
355 * Sections can be selected by prefixing them separated by dots.
356 *
357 * @param res response message to parse
358 * @param len length of returned object
359 * @param fmt printf format string of key and sections
360 * @param ... arguments to format string
361 * @return blob value, having *len bytes, NULL if not found
362 */
363 void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
364
365 /**
366 * Find a string value in a message for a given key.
367 *
368 * Sections can be selected by prefixing them separated by dots.
369 *
370 * @param res response message to parse
371 * @param def default value, if key not found
372 * @param fmt printf format string of key and sections
373 * @param ... arguments to format string
374 * @return string, def if not found
375 */
376 char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
377
378 /**
379 * Find an integer value in a message for a given key.
380 *
381 * Sections can be selected by prefixing them separated by dots.
382 *
383 * @param res response message to parse
384 * @param def default value, if key not found
385 * @param fmt printf format string of key and sections
386 * @param ... arguments to format string
387 * @return integer value, def if not found
388 */
389 int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
390
391 /**
392 * Clean up a received response message.
393 *
394 * Event messages get cleaned up by the library, it is not allowed to call
395 * vici_free_res() from within a vici_event_cb_t.
396 *
397 * @param res response message to free
398 */
399 void vici_free_res(vici_res_t *res);
400
401 /**
402 * (Un-)Register for events of a given kind.
403 *
404 * Events callbacks get invoked by a different thread from the libstrongswan
405 * thread pool. On failure, errno is set appropriately.
406 *
407 * @param conn connection context
408 * @param name name of event messages to register to
409 * @param cb callback function to register, NULL to unregister
410 * @param user user data passed to callback invocations
411 * @return 0 if registered successfully
412 */
413 int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
414
415 /**
416 * Initialize libvici before first time use.
417 */
418 void vici_init();
419
420 /**
421 * Deinitialize libvici after use.
422 */
423 void vici_deinit();
424
425 #endif /** LIBVICI_H_ @}*/