Annotation of embedaddon/strongswan/src/libcharon/plugins/vici/libvici.h, revision 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