]>
Commit | Line | Data |
---|---|---|
eb4fd014 MW |
1 | /* |
2 | * Copyright (C) 2014 Martin Willi | |
3 | * Copyright (C) 2014 revosec AG | |
4 | * | |
f17861dc MW |
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. | |
eb4fd014 | 7 | * |
f17861dc MW |
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. | |
eb4fd014 MW |
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 | * | |
021a14b7 MW |
42 | * Library initialization implicitly initializes libstrongswan and a small |
43 | * thread pool. | |
eb4fd014 MW |
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 | ||
993bfe95 MW |
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 | ||
eb4fd014 MW |
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 | * | |
e0a34ee4 MW |
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 | |
eb4fd014 MW |
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 | * | |
e0a34ee4 MW |
287 | * On error, errno is set to: |
288 | * - EBADMSG if the message is invalid | |
021a14b7 | 289 | * |
eb4fd014 | 290 | * @param res response message to dump |
045bdf52 | 291 | * @param label a label to print for this message |
dacb75f5 | 292 | * @param pretty use pretty print with indentation |
eb4fd014 MW |
293 | * @param out FILE to dump to |
294 | * @return 0 if dumped complete message, 1 on error | |
295 | */ | |
046b547a | 296 | int vici_dump(vici_res_t *res, char *label, int pretty, FILE *out); |
eb4fd014 MW |
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 | * | |
e0a34ee4 MW |
314 | * On error, errno is set to: |
315 | *- EINVAL if not in valid parser state | |
021a14b7 | 316 | * |
eb4fd014 MW |
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. | |
021a14b7 | 339 | * |
eb4fd014 | 340 | * The string is valid until vici_free_res() is called. |
021a14b7 | 341 | * |
e0a34ee4 MW |
342 | * On error, errno is set to: |
343 | * - EINVAL if not in valid parser state | |
021a14b7 | 344 | * |
3b16c2b5 | 345 | * @param res response message to parse |
021a14b7 MW |
346 | * @param len pointer receiving value length |
347 | * @return pointer to value, NULL on error | |
eb4fd014 MW |
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. | |
021a14b7 | 356 | * |
eb4fd014 MW |
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 | * | |
e0a34ee4 MW |
360 | * On error, errno is set to: |
361 | * - EBADMSG if value is not a printable string | |
362 | * - EINVAL if not in valid parser state | |
021a14b7 | 363 | * |
eb4fd014 MW |
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 | ||
7f4cfdff | 369 | /** |
993bfe95 MW |
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 | * | |
e0a34ee4 MW |
376 | * On error, errno is set to: |
377 | * - EBADMSG if message encoding invalid | |
378 | * - Any other errno set by the invoked callbacks | |
021a14b7 | 379 | * |
993bfe95 MW |
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 | /* | |
7f4cfdff MW |
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 | ||
eb4fd014 MW |
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 | |
e0a34ee4 MW |
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 | |
eb4fd014 MW |
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_ @}*/ |