499e9a0b13349caa53608ca36549456c77e4c101
[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 * Open a new vici connection.
128 *
129 * On error, NULL is returned and errno is set appropriately.
130 *
131 * @param uri URI to connect to, NULL to use system default
132 * @return opaque vici connection context, NULL on error
133 */
134 vici_conn_t* vici_connect(char *uri);
135
136 /**
137 * Close a vici connection.
138 *
139 * @param conn connection context
140 */
141 void vici_disconnect(vici_conn_t *conn);
142
143 /**
144 * Begin a new vici message request.
145 *
146 * This function always succeeds.
147 *
148 * @param name name of request command
149 * @return request message, to add contents
150 */
151 vici_req_t* vici_begin(char *name);
152
153 /**
154 * Begin a new section in a vici request message.
155 *
156 * @param req request message to create a new section in
157 * @param name name of section to create
158 */
159 void vici_begin_section(vici_req_t *req, char *name);
160
161 /**
162 * End a previously opened section.
163 *
164 * @param req request message to close an open section in
165 */
166 void vici_end_section(vici_req_t *req);
167
168 /**
169 * Add a key/value pair, using an as-is blob as value.
170 *
171 * @param req request message to add key/value pair to
172 * @param key key name of key/value pair
173 * @param buf pointer to blob to add as value
174 * @param len length of value blob to add
175 */
176 void vici_add_key_value(vici_req_t *req, char *key, void *buf, int len);
177
178 /**
179 * Add a key/value pair, setting value from a printf() format string.
180 *
181 * @param req request message to add key/value pair to
182 * @param key key name of key/value pair
183 * @param fmt format string for value
184 * @param ... arguments to format string
185 */
186 void vici_add_key_valuef(vici_req_t *req, char *key, char *fmt, ...);
187
188 /**
189 * Begin a list in a request message.
190 *
191 * After starting a list, only list items can be added until the list gets
192 * closed by vici_end_list().
193 *
194 * @param req request message to begin list in
195 * @param name name of list to begin
196 */
197 void vici_begin_list(vici_req_t *req, char *name);
198
199 /**
200 * Add a list item to a currently open list, using an as-is blob.
201 *
202 * @param req request message to add list item to
203 * @param buf pointer to blob to add as value
204 * @param len length of value blob to add
205 */
206 void vici_add_list_item(vici_req_t *req, void *buf, int len);
207
208 /**
209 * Add a list item to a currently open list, using a printf() format string.
210 *
211 * @param req request message to add list item to
212 * @param fmt format string to create value from
213 * @param ... arguments to format string
214 */
215 void vici_add_list_itemf(vici_req_t *req, char *fmt, ...);
216
217 /**
218 * End a previously opened list in a request message.
219 *
220 * @param req request message to end list in
221 */
222 void vici_end_list(vici_req_t *req);
223
224 /**
225 * Submit a request message, and wait for response.
226 *
227 * On error, NULL is returned an errno is set appropriately. The request
228 * messages gets cleaned up by this call and gets invalid.
229 *
230 * @param req request message to send
231 * @param conn connection context to send message over
232 * @return response message, NULL on error
233 */
234 vici_res_t* vici_submit(vici_req_t *req, vici_conn_t *conn);
235
236 /**
237 * Cancel a request message started.
238 *
239 * If a request created by vici_begin() does not get submitted using
240 * vici_submit(), it has to get freed using this call.
241 *
242 * @param req request message to clean up
243 */
244 void vici_free_req(vici_req_t *req);
245
246 /**
247 * Dump a message text representation to a FILE stream.
248 *
249 * @param res response message to dump
250 * @param label a label to print for this message
251 * @param out FILE to dump to
252 * @return 0 if dumped complete message, 1 on error
253 */
254 int vici_dump(vici_res_t *res, char *label, FILE *out);
255
256 /**
257 * Parse next element from a vici response message.
258 *
259 * @param res response message to parse
260 * @return parse result
261 */
262 vici_parse_t vici_parse(vici_res_t *res);
263
264 /**
265 * Parse name tag / key of a previously parsed element.
266 *
267 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
268 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
269 *
270 * The string is valid until vici_free_res() is called.
271 *
272 * @param res response message to parse
273 * @return name tag / key, NULL on error
274 */
275 char* vici_parse_name(vici_res_t *res);
276
277 /**
278 * Compare name tag / key of a previusly parsed element.
279 *
280 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
281 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
282 *
283 * @param res response message to parse
284 * @param name string to compare
285 * @return 1 if name equals, 0 if not
286 */
287 int vici_parse_name_eq(vici_res_t *res, char *name);
288
289 /**
290 * Parse value of a previously parsed element, as a blob.
291 *
292 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
293 * VICI_PARSE_LIST_ITEM.
294 * The string is valid until vici_free_res() is called.
295 */
296 void* vici_parse_value(vici_res_t *res, int *len);
297
298 /**
299 * Parse value of a previously parsed element, as a string.
300 *
301 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
302 * VICI_PARSE_LIST_ITEM.
303 * This call is successful only if the value contains no non-printable
304 * characters. The string is valid until vici_free_res() is called.
305 *
306 * @param res response message to parse
307 * @return value as string, NULL on error
308 */
309 char* vici_parse_value_str(vici_res_t *res);
310
311 /**
312 * Find a blob value in a message for a given key.
313 *
314 * Sections can be selected by prefixing them separated by dots.
315 *
316 * @param res response message to parse
317 * @param len length of returned object
318 * @param fmt printf format string of key and sections
319 * @param ... arguments to format string
320 * @return blob value, having *len bytes, NULL if not found
321 */
322 void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
323
324 /**
325 * Find a string value in a message for a given key.
326 *
327 * Sections can be selected by prefixing them separated by dots.
328 *
329 * @param res response message to parse
330 * @param def default value, if key not found
331 * @param fmt printf format string of key and sections
332 * @param ... arguments to format string
333 * @return string, def if not found
334 */
335 char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
336
337 /**
338 * Find an integer value in a message for a given key.
339 *
340 * Sections can be selected by prefixing them separated by dots.
341 *
342 * @param res response message to parse
343 * @param def default value, if key not found
344 * @param fmt printf format string of key and sections
345 * @param ... arguments to format string
346 * @return integer value, def if not found
347 */
348 int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
349
350 /**
351 * Clean up a received response message.
352 *
353 * Event messages get cleaned up by the library, it is not allowed to call
354 * vici_free_res() from within a vici_event_cb_t.
355 *
356 * @param res response message to free
357 */
358 void vici_free_res(vici_res_t *res);
359
360 /**
361 * (Un-)Register for events of a given kind.
362 *
363 * Events callbacks get invoked by a different thread from the libstrongswan
364 * thread pool. On failure, errno is set appropriately.
365 *
366 * @param conn connection context
367 * @param name name of event messages to register to
368 * @param cb callback function to register, NULL to unregister
369 * @param user user data passed to callback invocations
370 * @return 0 if registered successfully
371 */
372 int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
373
374 /**
375 * Initialize libvici before first time use.
376 */
377 void vici_init();
378
379 /**
380 * Deinitialize libvici after use.
381 */
382 void vici_deinit();
383
384 #endif /** LIBVICI_H_ @}*/