Annotation of embedaddon/strongswan/src/libcharon/plugins/vici/libvici.h, revision 1.1.1.1
1.1 misho 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 tuple 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: #ifdef __cplusplus
90: extern "C" {
91: #endif
92:
93: /**
94: * Opaque vici connection contex.
95: */
96: typedef struct vici_conn_t vici_conn_t;
97:
98: /**
99: * Opaque vici request message.
100: */
101: typedef struct vici_req_t vici_req_t;
102:
103: /**
104: * Opaque vici response/event message.
105: */
106: typedef struct vici_res_t vici_res_t;
107:
108: /**
109: * Vici parse result, as returned by vici_parse().
110: */
111: typedef enum {
112: /** encountered a section start, has a name */
113: VICI_PARSE_BEGIN_SECTION,
114: /** encountered a section end */
115: VICI_PARSE_END_SECTION,
116: /** encountered a list start, has a name */
117: VICI_PARSE_BEGIN_LIST,
118: /** encountered a list element, has a value */
119: VICI_PARSE_LIST_ITEM,
120: /** encountered a list end */
121: VICI_PARSE_END_LIST,
122: /** encountered a key/value pair, has a name and a value */
123: VICI_PARSE_KEY_VALUE,
124: /** encountered valid end of message */
125: VICI_PARSE_END,
126: /** parse error */
127: VICI_PARSE_ERROR,
128: } vici_parse_t;
129:
130: /**
131: * Callback function invoked for received event messages.
132: *
133: * It is not allowed to call vici_submit() from this callback.
134: *
135: * @param user user data, as passed to vici_connect
136: * @param name name of received event
137: * @param msg associated event message, destroyed by libvici
138: */
139: typedef void (*vici_event_cb_t)(void *user, char *name, vici_res_t *msg);
140:
141: /**
142: * Callback function for key/value and list items, invoked by vici_parse_cb().
143: *
144: * @param user user data, as passed to vici_parse_cb()
145: * @param res message currently parsing
146: * @param name name of key or list
147: * @param value value buffer
148: * @param len length of value buffer
149: * @return 0 if parsed successfully
150: */
151: typedef int (*vici_parse_value_cb_t)(void *user, vici_res_t *res, char *name,
152: void *value, int len);
153:
154: /**
155: * Callback function for sections, invoked by vici_parse_cb().
156: *
157: * @param user user data, as passed to vici_parse_cb()
158: * @param res message currently parsing
159: * @param name name of the section
160: * @return 0 if parsed successfully
161: */
162: typedef int (*vici_parse_section_cb_t)(void *user, vici_res_t *res, char *name);
163:
164: /**
165: * Open a new vici connection.
166: *
167: * On error, NULL is returned and errno is set appropriately.
168: *
169: * @param uri URI to connect to, NULL to use system default
170: * @return opaque vici connection context, NULL on error
171: */
172: vici_conn_t* vici_connect(char *uri);
173:
174: /**
175: * Close a vici connection.
176: *
177: * @param conn connection context
178: */
179: void vici_disconnect(vici_conn_t *conn);
180:
181: /**
182: * Begin a new vici message request.
183: *
184: * This function always succeeds.
185: *
186: * @param name name of request command
187: * @return request message, to add contents
188: */
189: vici_req_t* vici_begin(char *name);
190:
191: /**
192: * Begin a new section in a vici request message.
193: *
194: * @param req request message to create a new section in
195: * @param name name of section to create
196: */
197: void vici_begin_section(vici_req_t *req, char *name);
198:
199: /**
200: * End a previously opened section.
201: *
202: * @param req request message to close an open section in
203: */
204: void vici_end_section(vici_req_t *req);
205:
206: /**
207: * Add a key/value pair, using an as-is blob as value.
208: *
209: * @param req request message to add key/value pair to
210: * @param key key name of key/value pair
211: * @param buf pointer to blob to add as value
212: * @param len length of value blob to add
213: */
214: void vici_add_key_value(vici_req_t *req, char *key, void *buf, int len);
215:
216: /**
217: * Add a key/value pair, setting value from a printf() format string.
218: *
219: * @param req request message to add key/value pair to
220: * @param key key name of key/value pair
221: * @param fmt format string for value
222: * @param ... arguments to format string
223: */
224: void vici_add_key_valuef(vici_req_t *req, char *key, char *fmt, ...);
225:
226: /**
227: * Begin a list in a request message.
228: *
229: * After starting a list, only list items can be added until the list gets
230: * closed by vici_end_list().
231: *
232: * @param req request message to begin list in
233: * @param name name of list to begin
234: */
235: void vici_begin_list(vici_req_t *req, char *name);
236:
237: /**
238: * Add a list item to a currently open list, using an as-is blob.
239: *
240: * @param req request message to add list item to
241: * @param buf pointer to blob to add as value
242: * @param len length of value blob to add
243: */
244: void vici_add_list_item(vici_req_t *req, void *buf, int len);
245:
246: /**
247: * Add a list item to a currently open list, using a printf() format string.
248: *
249: * @param req request message to add list item to
250: * @param fmt format string to create value from
251: * @param ... arguments to format string
252: */
253: void vici_add_list_itemf(vici_req_t *req, char *fmt, ...);
254:
255: /**
256: * End a previously opened list in a request message.
257: *
258: * @param req request message to end list in
259: */
260: void vici_end_list(vici_req_t *req);
261:
262: /**
263: * Submit a request message, and wait for response.
264: *
265: * The request messages gets cleaned up by this call and gets invalid.
266: * On error, NULL is returned an errno is set to:
267: * - EINVAL if the request is invalid/incomplete
268: * - ENOENT if the command is unknown
269: * - EBADMSG if the response is invalid
270: * - Any other IO related errno
271: *
272: * @param req request message to send
273: * @param conn connection context to send message over
274: * @return response message, NULL on error
275: */
276: vici_res_t* vici_submit(vici_req_t *req, vici_conn_t *conn);
277:
278: /**
279: * Cancel a request message started.
280: *
281: * If a request created by vici_begin() does not get submitted using
282: * vici_submit(), it has to get freed using this call.
283: *
284: * @param req request message to clean up
285: */
286: void vici_free_req(vici_req_t *req);
287:
288: /**
289: * Dump a message text representation to a FILE stream.
290: *
291: * On error, errno is set to:
292: * - EBADMSG if the message is invalid
293: *
294: * @param res response message to dump
295: * @param label a label to print for this message
296: * @param pretty use pretty print with indentation
297: * @param out FILE to dump to
298: * @return 0 if dumped complete message, 1 on error
299: */
300: int vici_dump(vici_res_t *res, char *label, int pretty, FILE *out);
301:
302: /**
303: * Parse next element from a vici response message.
304: *
305: * @param res response message to parse
306: * @return parse result
307: */
308: vici_parse_t vici_parse(vici_res_t *res);
309:
310: /**
311: * Parse name tag / key of a previously parsed element.
312: *
313: * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
314: * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
315: *
316: * The string is valid until vici_free_res() is called.
317: *
318: * On error, errno is set to:
319: *- EINVAL if not in valid parser state
320: *
321: * @param res response message to parse
322: * @return name tag / key, NULL on error
323: */
324: char* vici_parse_name(vici_res_t *res);
325:
326: /**
327: * Compare name tag / key of a previously parsed element.
328: *
329: * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
330: * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
331: *
332: * @param res response message to parse
333: * @param name string to compare
334: * @return 1 if name equals, 0 if not
335: */
336: int vici_parse_name_eq(vici_res_t *res, char *name);
337:
338: /**
339: * Parse value of a previously parsed element, as a blob.
340: *
341: * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
342: * VICI_PARSE_LIST_ITEM.
343: *
344: * The string is valid until vici_free_res() is called.
345: *
346: * On error, errno is set to:
347: * - EINVAL if not in valid parser state
348: *
349: * @param res response message to parse
350: * @param len pointer receiving value length
351: * @return pointer to value, NULL on error
352: */
353: void* vici_parse_value(vici_res_t *res, int *len);
354:
355: /**
356: * Parse value of a previously parsed element, as a string.
357: *
358: * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
359: * VICI_PARSE_LIST_ITEM.
360: *
361: * This call is successful only if the value contains no non-printable
362: * characters. The string is valid until vici_free_res() is called.
363: *
364: * On error, errno is set to:
365: * - EBADMSG if value is not a printable string
366: * - EINVAL if not in valid parser state
367: *
368: * @param res response message to parse
369: * @return value as string, NULL on error
370: */
371: char* vici_parse_value_str(vici_res_t *res);
372:
373: /**
374: * Parse a complete message with callbacks.
375: *
376: * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
377: * invoked for the current section level only. To descent into sections, call
378: * vici_parse_cb() from within a section callback.
379: *
380: * On error, errno is set to:
381: * - EBADMSG if message encoding invalid
382: * - Any other errno set by the invoked callbacks
383: *
384: * @param res message to parse
385: * @param section callback invoked for each section
386: * @param kv callback invoked for key/value pairs
387: * @param li callback invoked for list items
388: * @param user user data to pass to callbacks
389: * @return 0 if parsing successful
390: */
391: int vici_parse_cb(vici_res_t *res, vici_parse_section_cb_t section,
392: vici_parse_value_cb_t kv, vici_parse_value_cb_t li,
393: void *user);
394:
395: /*
396: * Find a blob value in a message for a given key.
397: *
398: * Sections can be selected by prefixing them separated by dots.
399: *
400: * @param res response message to parse
401: * @param len length of returned object
402: * @param fmt printf format string of key and sections
403: * @param ... arguments to format string
404: * @return blob value, having *len bytes, NULL if not found
405: */
406: void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
407:
408: /**
409: * Find a string value in a message for a given key.
410: *
411: * Sections can be selected by prefixing them separated by dots.
412: *
413: * @param res response message to parse
414: * @param def default value, if key not found
415: * @param fmt printf format string of key and sections
416: * @param ... arguments to format string
417: * @return string, def if not found
418: */
419: char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
420:
421: /**
422: * Find an integer value in a message for a given key.
423: *
424: * Sections can be selected by prefixing them separated by dots.
425: *
426: * @param res response message to parse
427: * @param def default value, if key not found
428: * @param fmt printf format string of key and sections
429: * @param ... arguments to format string
430: * @return integer value, def if not found
431: */
432: int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
433:
434: /**
435: * Clean up a received response message.
436: *
437: * Event messages get cleaned up by the library, it is not allowed to call
438: * vici_free_res() from within a vici_event_cb_t.
439: *
440: * @param res response message to free
441: */
442: void vici_free_res(vici_res_t *res);
443:
444: /**
445: * (Un-)Register for events of a given kind.
446: *
447: * Events callbacks get invoked by a different thread from the libstrongswan
448: * thread pool.
449: * On failure, errno is set to:
450: * - ENOENT if the event name is unknown
451: * - EBADMSG if the response is invalid
452: * - Any other IO related errno
453: *
454: * @param conn connection context
455: * @param name name of event messages to register to
456: * @param cb callback function to register, NULL to unregister
457: * @param user user data passed to callback invocations
458: * @return 0 if registered successfully
459: */
460: int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
461:
462: /**
463: * Initialize libvici before first time use.
464: */
465: void vici_init();
466:
467: /**
468: * Deinitialize libvici after use.
469: */
470: void vici_deinit();
471:
472: #ifdef __cplusplus
473: }
474: #endif
475:
476: #endif /** LIBVICI_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to libvici.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libcharon / plugins / vici