davici.h

/*
 * Copyright (C) 2015 onway ag
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 */

/**
 * @defgroup davici davici
 * @{
 *
 * Decoupled Asynchronous strongSwan VICI client library.
 */

#ifndef _DAVICI_H_
#define _DAVICI_H_

#include <stdio.h>
#include <stdarg.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Opaque connection context.
 */
struct davici_conn;

/**
 * Opaque request message context.
 */
struct davici_request;

/**
 * Opaque response message context.
 */
struct davici_response;

/**
 * Parsed message element.
 */
enum davici_element {
	/** valid end of message */
	DAVICI_END = 0,
	/** begin of a section */
	DAVICI_SECTION_START,
	/** end of a section */
	DAVICI_SECTION_END,
	/** key/value pair */
	DAVICI_KEY_VALUE,
	/** begin of a list */
	DAVICI_LIST_START,
	/** list item */
	DAVICI_LIST_ITEM,
	/** end of a list */
	DAVICI_LIST_END,
};

/**
 * File descriptor watch operations requested.
 */
enum davici_fdops {
	/** request read-ready notifications */
	DAVICI_READ = (1<<0),
	/** request write-ready notifications */
	DAVICI_WRITE = (1<<1),
};

/**
 * Prototype for a command response or event callback function.
 *
 * This kind of callback is invoked for command response and event callbacks.
 * The err parameter indicates any errors in issuing a command or registering
 * for an event.
 *
 * For event registration, also implicitly for streamed command messages using
 * events, the callback gets invoked with a NULL res parameter both after
 * registration and deregistration to indicate any error conditions.
 *
 * Command and event registration responses do not carry a name on the wire,
 * but the name parameter is populated with the name of the issued event
 * registration or command request.
 *
 * @param conn		opaque connection context
 * @param err		0 on success, or a negative receive errno
 * @param name		command or event name raising the callback
 * @param res		event or response message
 * @param user		user context passed to registration function
 */
typedef void (*davici_cb)(struct davici_conn *conn, int err, const char *name,
						  struct davici_response *res, void *user);

/**
 * Prototype for a file descriptor watch update callback.
 *
 * The watch update callback requests (or updates) a file descriptor watch from
 * the user. The fd parameter is a file descriptor the user shall monitor
 * with select(), poll() or similar functionality. The ops argument is an ORed
 * set of enum davici_fdops flags indicating for what kind of file descriptor
 * events monitoring should be set up.
 *
 * The callback may be invoked from any davici function multiple times, but
 * is guaranteed to get called with a zero ops parameter before returning
 * from davici_disconnect().
 *
 * @param conn		opaque connection context
 * @param fd		file descriptor to watch
 * @param ops		watch operations to register for, enum davici_fdops
 * @param user		user context passed during connection
 * @return			0 if watch updated, or a negative errno
 */
typedef int (*davici_fdcb)(struct davici_conn *conn, int fd, int ops,
						   void *user);

/**
 * Prototype for a recursive parsing callback.
 *
 * This callback is used by davici_recurse(), a recursive VICI message parser.
 * The same kind of callback is used for section, list item and key/value
 * elements found in a message.
 *
 * If this callback returns a negative errno, parsing is aborted and the
 * same errno is returned from davici_recurse().
 *
 * @param res		response or event message parsing
 * @param user		user context, as passed to davici_recurse()
 * @return			a negative errno on error to stop parsing
 */
typedef int (*davici_recursecb)(struct davici_response *res, void *user);

/**
 * Create a connection to a VICI Unix socket.
 *
 * Opens a Unix socket connection to a VICI service under path, using a
 * file descriptor monitoring callback function as discussed above.
 *
 * Please note that this function uses connect() on a blocking socket, which
 * in theory is a blocking call.
 *
 * @param path		path to Unix socket
 * @param fdcb		callback to register for file descriptor watching
 * @param user		user context to pass to fdcb
 * @param connp		pointer receiving connection context on success
 * @return			0 on success, or a negative errno
 */
int davici_connect_unix(const char *path, davici_fdcb fdcb, void *user,
						struct davici_conn **connp);

/**
 * Read and process pending connection data.
 *
 * Performs a non-blocking read on the connection, and dispatches any
 * received response or event message. The call uses non-blocking reads
 * only, and returns with a successful result if the call would block. It is
 * usually an unrecoverable error if a negative errno is returned, and the
 * user should call davici_disconnect().
 *
 * @param conn		opaque connection context
 * @return			0 on success, or a negative errno
 */
int davici_read(struct davici_conn *conn);

/**
 * Write queued request data to the connection.
 *
 * Performs a non-blocking write on the connection for any currently queued
 * message. The call uses non-blocking reads only, and returns with a
 * successful result if the call would block. It is usually an unrecoverable
 * error if a negative errno is returned, and the user should call
 * davici_disconnect().
 *
 * @param conn		opaque connection context
 * @return			0 on success, or a negative errno
 */
int davici_write(struct davici_conn *conn);

/**
 * Close an open VICI connection and free associated resources.
 *
 * Frees any resources associated to a connection, and invokes the file
 * descriptor watch callback of the connection with zero-flags if a monitoring
 * registration is active.
 *
 * Any request messages created with davici_new_cmd() but not queued to
 * the connection using either davici_queue() or davici_queue_streamed()
 * is not freed by this call. Such requests must be freed explicitly by calling
 * davici_cancel() on them.
 *
 * @param conn		opaque connection context
 */
void davici_disconnect(struct davici_conn *conn);

/**
 * Allocate a new request command message.
 *
 * Creates a new but empty request message for a named command. The returned
 * handle must be passed to davici_queue() or davici_queue_streamed() after
 * adding request data. If the connection gets closed before the request
 * could be queued, the request must be freed using davici_cancel().
 *
 * @param cmd		command name
 * @param reqp		receives allocated request context
 * @return			0 on success, or a negative errno
 */
int davici_new_cmd(const char *cmd, struct davici_request **reqp);

/**
 * Begin a new section on a request message.
 *
 * Begin a new named section at the current request position. Any started
 * section must have a corresponding davici_section_end() added to form
 * a valid request message. Creating sections within lists is invalid.
 *
 * @param req		request context
 * @param name		name of section to open
 */
void davici_section_start(struct davici_request *req, const char *name);

/**
 * End a section previously opened on a request message.
 *
 * Close a section previously started with davici_section_start(). The
 * call must be balanced with davici_section_start() to form a valid request
 * message.
 *
 * @param req		request context
 */
void davici_section_end(struct davici_request *req);

/**
 * Add a key/value element to the request message.
 *
 * Adds a new key/value pair at the current request position. Key/values
 * may be added to any explicit or the implicit root section, but not to
 * lists.
 *
 * @param req		request context
 * @param name		key name
 * @param buf		value buffer
 * @param buflen	size, in bytes, of buf
 */
void davici_kv(struct davici_request *req, const char *name,
			   const void *buf, unsigned int buflen);

/**
 * Add a key with a format string value to the request message.
 *
 * Similar to davici_kv(), but instead of a fixed buffer takes a printf()
 * format string and arguments to form the value of the key/value pair.
 *
 * @param req		request context
 * @param name		key name
 * @param fmt		format string for value
 * @param ...		arguments for fmt string
 */
void davici_kvf(struct davici_request *req, const char *name,
				const char *fmt, ...);

/**
 * Add a key with a format string value and a va_list to the request message.
 *
 * Very similar to davici_kvf(), but takes a va_list argument list for the
 * format string instead of variable arguments.
 *
 * @param req		request context
 * @param name		key name
 * @param fmt		format string for value
 * @param args		argument list for fmt string
 */
void davici_vkvf(struct davici_request *req, const char *name,
				 const char *fmt, va_list args);

/**
 * Begin a list of unnamed items in a request message.
 *
 * Starts a new list at the current request message position. Lists may appear
 * in any section, but not in lists. Started lists must be closed by
 * davici_list_end(), and both calls must be balanced to form a valid request
 * message.
 *
 * @param req		request context
 * @param name		list name to open
 */
void davici_list_start(struct davici_request *req, const char *name);

/**
 * Add a list item value to a previously opened list.
 *
 * List items may be added to lists only, and are invalid in any other context.
 *
 * @param req		request context
 * @param buf		value buffer
 * @param buflen	size, in bytes, of buf
 */
void davici_list_item(struct davici_request *req, const void *buf,
					  unsigned int buflen);

/**
 * Add a list item with a format string value to a previously opened list.
 *
 * Similar to davici_list_item(), but instead of a fixed buffer takes a
 * printf() format string and variable arguments to form the list item value.
 *
 * @param req		request context
 * @param fmt		format string for value
 * @param ...		arguments for fmt string
 */
void davici_list_itemf(struct davici_request *req, const char *fmt, ...);

/**
 * Add a list item with a format string value and a va_list.
 *
 * Very similar to davici_list_itemf(), but instead of variable arguments
 * takes a va_list for the printf() format string.
 *
 * @param req		request context
 * @param fmt		format string for value
 * @param args		argument list for fmt string
 */
void davici_list_vitemf(struct davici_request *req, const char *fmt,
						va_list args);

/**
 * End a list previously opened for a request message.
 *
 * Closes the currently open list; valid only in a list context.
 *
 * @param req		request context
 */
void davici_list_end(struct davici_request *req);

/**
 * Clean up a request if it is not passed to davici_queue().
 *
 * Messages get automatically cleaned up when passed to davici_queue() or
 * after it has been fed to callbacks. Use this call only if an allocated
 * message does not get queued(), but the request is aborted.
 *
 * @param req		request context to free
 */
void davici_cancel(struct davici_request *req);

/**
 * Queue a command request message for submission.
 *
 * The request gets queued, and is sent to the daemon with davici_write()
 * when the daemon accepts new data and all previously queued requests have
 * been processed. Once the daemon responds to the request, davici_read()
 * invokes the passed callback with the response message and the provided
 * user context.
 *
 * @param conn		connection context
 * @param req		request message to queue
 * @param cb		callback to invoke for response message
 * @param user		user context to pass to callback
 * @return			0 on success, or a negative errno
 */
int davici_queue(struct davici_conn *conn, struct davici_request *req,
				 davici_cb cb, void *user);

/**
 * Queue a command request using event based streaming.
 *
 * In addition to davici_queue(), this call registers for an event while
 * the command is active and invokes an event callback for each streamed
 * object. Upon completion of the call, it invokes the result callback.
 *
 * @param conn		connection context
 * @param req		request message to queue
 * @param res_cb	callback to invoke for response message
 * @param event		streamed event name to register for
 * @param event_cb	event callback invoked for each streamed event message
 * @param user		user context to pass to callbacks
 * @return			0 on success, or a negative errno
 */
int davici_queue_streamed(struct davici_conn *conn, struct davici_request *req,
						  davici_cb res_cb, const char *event,
						  davici_cb event_cb, void *user);

/**
 * Get the count of all queued davici request messages.
 *
 * @param conn		connection context
 * @return			number of request messages in queue
 */
unsigned int davici_queue_len(struct davici_conn *conn);

/**
 * Register for event messages.
 *
 * Event registration is asynchronous; once registration completed the
 * callback is invoked with a NULL event message. The error code indicates
 * the registration status.
 *
 * @param conn		connection context
 * @param event		event name to register
 * @param cb		callback to invoke on events
 * @param user		user context to pass to cb
 * @return			0 on success, or a negative errno
 */
int davici_register(struct davici_conn *conn, const char *event,
					davici_cb cb, void *user);

/**
 * Unregister for event messages.
 *
 * Event deregistration is asynchronous; once deregistration completed the
 * callback is invoked with a NULL event message. The error code indicates
 * the deregistration status.
 *
 * @param conn		connection context
 * @param event		event name to unregister
 * @param cb		callback to invoke on events
 * @param user		user context to pass to cb
 * @return			0 on success, or a negative errno
 */
int davici_unregister(struct davici_conn *conn, const char *event,
					  davici_cb cb, void *user);

/**
 * Parse a response or event message.
 *
 * davici_parse() implements iterative parsing of response messages by
 * returning enum davici_element types as parsing status. For named types
 * davici_get_name() may be called to get the name of the just parsed element.
 * For types having a value, davici_get_value() returns the value of the
 * just parsed element.
 *
 * If parsing completes with DAVICI_END it may be parsed again using
 * davici_parse(). When davici_parse() returns an error, additional calls
 * to davici_parse() have undefined behavior.
 *
 * @param res		response or event message
 * @return			enum davici_element, or a negative errno
 */
int davici_parse(struct davici_response *res);

/**
 * Recursive response or event message parser.
 *
 * Using davici_parse(), davici_recurse() parses a VICI message by invoking
 * callbacks for the found elements. Three callbacks can be passed, but all
 * are optional to not further handle an element or descent into a section.
 *
 * If a section callback is given, that callback must invoke davici_recurse()
 * to parse the inner context, or it may return a negative errno. The return
 * value from the recursive davici_recurse() invocation should be returned
 * from the section callback to properly propagate inner errors.
 *
 * For any callback, davici_get_name() or davici_name_strcmp() can be called
 * to get the name of the element for which the callback is called. For lists,
 * the li callback is invoked for items only; davici_get_name() in a list item
 * callback returns the name of the list.
 *
 * davici_get_value() can be used in list item and key/value callbacks to get
 * the value of the element the callback is invoked for.
 *
 * @param res		response or event message
 * @param section	section callback, NULL to skip sub-sections
 * @param li		list item callback, NULL to ignore
 * @param kv		key/value callback, NULL to ignore
 * @return			a negative errno on error
 */
int davici_recurse(struct davici_response *res, davici_recursecb section,
				   davici_recursecb li, davici_recursecb kv, void *ctx);

/**
 * Get the section/list nesting level of the current parser position.
 *
 * The root section has a level of 0 and for each nested section the level is
 * incremented by one. When parsing a list, the level is incremented by one.
 * The level after parsing a section/list start is increased just after
 * davici_parse() is called for such an element, while for end elements the
 * level is decreased in davici_parse() for that element.
 *
 * @param res		response or event message
 * @return			section/list nesting level
 */
unsigned int davici_get_level(struct davici_response *res);

/**
 * Get the element name previously parsed in davici_parse().
 *
 * This call has defined behavior only if davici_parse() returned an element,
 * with a name, i.e. a section/list start or a key/value.
 *
 * @param res		response or event message
 * @return			element name
 */
const char* davici_get_name(struct davici_response *res);

/**
 * Compare the previously parsed element name against a given string.
 *
 * This call has defined behavior only if davici_parse() returned an element,
 * with a name, i.e. a section/list start or a key/value.
 *
 * @param res		response or event message
 * @param str		string to compare against name
 * @return			strcmp() result
 */
int davici_name_strcmp(struct davici_response *res, const char *str);

/**
 * Get the element value previously parsed in davici_parse().
 *
 * This call has defined behavior only if davici_parse() returned an element,
 * with a value, i.e. a section/list start or a key/value.
 *
 * @param res		response or event message
 * @param len		pointer receiving buffer length
 * @return			buffer containing value
 */
const void* davici_get_value(struct davici_response *res, unsigned int *len);

/**
 * Get the element value if it is a string.
 *
 * This is a convenience function to get the value of an element as string,
 * the same restrictions as to davici_get_value() apply. The function fails
 * if the value has any non-printable characters.
 *
 * @param res		response or event message context
 * @param buf		buffer to write string to
 * @param buflen	size of the buffer
 * @return			number of characters written, or a negative errno
 */
int davici_get_value_str(struct davici_response *res,
						 char *buf, unsigned int buflen);

/**
 * Convert value using a format specifier.
 *
 * This functions handles the value like a string, and then uses a scanf()
 * format string to convert the value to the passed argument pointers.
 *
 * @param res		response or event message context
 * @param fmt		scanf() format string
 * @param ...		arguments of format string
 * @return			number of input items matched, or a negative errno
 */
int davici_value_scanf(struct davici_response *res, const char *fmt, ...);

/**
 * Convert value using a format specifier, va_list variant.
 *
 * Like davici_value_scanf(), but takes arguments in a va_list.
 *
 * @param res		response or event message context
 * @param fmt		scanf() format string
 * @param args		arguments of format string
 * @return			number of input items matched, or a negative errno
 */
int davici_value_vscanf(struct davici_response *res, const char *fmt,
						va_list args);

/**
 * Convert value using a format specifier, error checking variant.
 *
 * Like davici_value_scanf(), but fails if either not the full value is
 * consumed or not all input items have been matched.
 *
 * Note that davici_value_escanf() is implemented as macro, and that
 * the arguments are evaluated more than once. fmt must be a string literal.
 *
 * @param res		response or event message context
 * @param fmt		scanf() format string
 * @param ...		arguments of format string
 * @return			a negative errno on error
 */
#define davici_value_escanf(res, fmt, ...) ({\
	unsigned int _v; \
	int _m, _e, _c; \
	_e = sizeof((void*[]){ __VA_ARGS__ }) / sizeof(void*); \
	_m = davici_value_scanf(res, fmt "%n", __VA_ARGS__, &_c); \
	davici_get_value(res, &_v); \
	(_m == _e && _c == _v) ? 0 : -EBADMSG; \
})

/**
 * Compare the element value to a given string.
 *
 * This is a convenience function to compare the value of an element as string
 * to a given string. The same restrictions as to davici_get_value() apply.
 *
 * @param res		response or event message
 * @param str		string to compare against value
 * @return			strcmp() result
 */
int davici_value_strcmp(struct davici_response *res, const char *str);

/**
 * Dump a response or event message to a FILE stream.
 *
 * The dump output is not considered stable, but solely for debugging
 * purposes.
 *
 * @param res		response or event message context
 * @param name		name of the message to dump
 * @param sep		value separator, such as "\n"
 * @param level		base indentation level
 * @param indent	number of spaces to use for indentation
 * @param out		FILE stream to write to
 * @return			total bytes written, or a negative errno on error
 */
int davici_dump(struct davici_response *res, const char *name, const char *sep,
				unsigned int level, unsigned int indent, FILE *out);

#ifdef __cplusplus
}
#endif

#endif /* _DAVICI_H_ */

/**
 * @}
 */