XMLSD(3)

NAME
xmlsd - xml validation library

SYNOPSIS
#include <xmlsd.h>
int
xmlsd_doc_alloc(struct xmlsd_document **xdp);
void
xmlsd_doc_clear(struct xmlsd_document *xd);
void
xmlsd_doc_free(struct xmlsd_document *xd);
int
xmlsd_doc_is_empty(struct xmlsd_document *xd);
struct xmlsd_element *
xmlsd_doc_get_first_elem(struct xmlsd_document *xd);
struct xmlsd_element *
xmlsd_doc_add_elem(struct xmlsd_document *xd, struct xmlsd_element *parent, const char *name);
void
xmlsd_doc_remove_elem(struct xmlsd_document *xd, struct xmlsd_element *xe);
int
xmlsd_validate(struct xmlsd_document *xd, struct xmlsd_v_elements *v_elem);
int
xmlsd_validate_info(struct xmlsd_document *xd, struct xmlsd_v_elements *v_elem, , struct, xmlsd_validate_failure, *xvf");
char
xmlsd_get_validate_failure_string(struct xmlsd_validate_failure *xvf);
enum xmlsd_validate_v_elements_failure
xmlsd_validate_v_elements(struct xmlsd_v_elements *cmds, ,, struct xmlsd_v_elements_validation *xvev);
char
xmlsd_get_validate_v_elements_failure_string(struct xmlsd_validate_v_elements_validation *xvev);
int
xmlsd_parse_fileds(int fd, struct xmlsd_document *xd);
int
xmlsd_parse_file(FILE *file, struct xmlsd_document *xd);
int
xmlsd_parse_mem(const char *buf, size_t len, struct xmlsd_document *xd);
char *
xmlsd_generate(struct xmlsd_document *xd, void *(*alloc_fn)(size_t), size_t *szp, int flags);
const char *
xmlsd_attr_get_name(struct xmlsd_attribute *xa);
const char *
xmlsd_attr_get_value(struct xmlsd_attribute *xa);
const char *
xmlsd_elem_get_name(struct xmlsd_element *xe);
const char *
xmlsd_elem_get_value(struct xmlsd_element *xe);
long long
xmlsd_elem_get_value_strtonum(struct xmlsd_elment *xd, unsigned long long minval, unsigned long long maxval, const char **errstring);
unsigned long long
xmlsd_elem_get_value_hexnum(struct xmlsd_elment *xd, unsigned long long minval, unsigned long long maxval, const char **errstring);
int
xmlsd_elem_get_value_boolean(struct xmlsd_element *xe, int *bool, int);
default"
int
xmlsd_elem_get_depth(struct xmlsd_element *xe);
struct xmlsd_element *
xmlsd_elem_get_parent(struct xmlsd_element *);
const char *
xmlsd_elem_get_attr(struct xmlsd_element *xe, const char *name);
long long
xmlsd_elem_get_attr_strtonum(struct xmlsd_elment *xd, const char *name, unsigned long long minval, unsigned long long maxval, const char **errstring);
unsigned long long
xmlsd_elem_get_attr_hexnum(struct xmlsd_elment *xd, const char *name, unsigned long long minval, unsigned long long maxval, const char **errstring);
int
xmlsd_elem_get_attr_boolean(struct xmlsd_element *xe, const char *name, int *bool, int);
struct xmlsd_attribute *
xmlsd_elem_find_attr(struct xmlsd_element *xe, const char *name);
struct xmlsd_attribute *
xmlsd_elem_get_first_attr(struct xmlsd_element *xe);
struct xmlsd_attribute *
xmlsd_elem_get_next_attr(struct xmlsd_element *xe, struct xmlsd_attribute *cur);
struct xmlsd_attribute *
xmlsd_elem_get_last_attr(struct xmlsd_element *xe);
struct xmlsd_attribute *
xmlsd_elem_get_previous_attr(struct xmlsd_element *xe, struct xmlsd_attribute *cur);
XMLSD_ELEM_FOREACH_ATTR(struct xmlsd_attribute *attr, struct xmlsd_element *elem);
struct xmlsd_element *
xmlsd_elem_find_child(struct xmlsd_elment *xe, const char *name);
struct xmlsd_element *
xmlsd_elem_get_first_child(struct xmlsd_elment *xe);
struct xmlsd_element *
xmlsd_elem_get_next_child(struct xmlsd_elment *xe, struct xmlsd_element *cur);
struct xmlsd_element *
xmlsd_elem_get_last_child(struct xmlsd_elment *xe);
struct xmlsd_element *
xmlsd_elem_get_previous_child(struct xmlsd_elment *xe, struct xmlsd_element *cur);
XMLSD_ELEM_FOREACH_CHILDREN(struct xmlsd_element *child, struct xmlsd_element *elem);
int
xmlsd_elem_set_attr(struct xmlsd_element *xe, const char *name, const char *value);
int
xmlsd_elem_set_attr_int32(struct xmlsd_element *xe, const char *name, int32_t value);
int
xmlsd_elem_set_attr_uint32(struct xmlsd_element *xe, const char *name, uint32_t value);
int
xmlsd_elem_set_attr_int64(struct xmlsd_element *xe, const char *name, int64_t value);
int
xmlsd_elem_set_attr_uint64(struct xmlsd_element *xe, const char *name, uint64_t value);
int
xmlsd_elem_set_attr_x32(struct xmlsd_element *xe, const char *name, uint32_t value);
int
xmlsd_elem_set_attr_x64(struct xmlsd_element *xe, const char *name, uint64_t value);
int
xmlsd_elem_set_value(struct xmlsd_element *xe, const char *value);
int
xmlsd_elem_set_value_int32(struct xmlsd_element *xe, int32_t value);
int
xmlsd_elem_set_value_uint32(struct xmlsd_element *xe, uint32_t value);
int
xmlsd_elem_set_value_int64(struct xmlsd_element *xe, int64_t value);
int
xmlsd_elem_set_value_uint64(struct xmlsd_element *xe, uint64_t value);
int
xmlsd_elem_set_value_x32(struct xmlsd_element *xe, uint32_t value);
int
xmlsd_elem_set_value_x64(struct xmlsd_element *xe, uint64_t value);
void
xmlsd_elem_free(struct xmlsd_element *xe);
void
xmlsd_version(int *major, int *minor, int *patch);

DESCRIPTION
The xmlsd library has three basic types: struct xmlsd_document, struct xmlsd_element, and struct xmlsd_attribute, Representing the various parts of an xml document. The top-level type xmlsd_document is required before any other manipulation occurs on the document. xmlsd_doc_alloc() allocates an xmlsd_document to xdp or returns an error. The document may then either be filled by parsing an existing xml document, or built from from scratch using xmlsd apis, both methods will be described below. A document may be cleared (but not freed) by xmlsd_doc_clear(), or cleared and freed by xmlsd_doc_free(). xmlsd_doc_is_empty() returns true or false if the document is empty or not. xmlsd_doc_get_root(), will return either the root element, or NULL if empty.

struct xmlsd_element represents an individual element within an XML document. A new element is added to a document using xmlsd_doc_add_elem() which will add an elemnt with name name to the document xd with the parent parent, The new element will be returned. If parent is NULL then the element will be added as the root element of the document. Conversely, xmlsd_doc_remove_elem() will remove an element (and its children). To fully initialize the new element attributes may be set with xmlsd_elem_set_attr(), which will add an attribute with name and value to xe. alternative versions of the function exist to set attributes with given types. xmlsd_elem_set_value() and the family of typed variations perform the same way for filling in the value of the element. Functions are also provided to access the properties of an element: xmlsd_elem_get_name(), xmlsd_elem_get_value(), xmlsd_elem_get_depth(), and xmlsd_elem-get_parent() will return the named property from an element. additonally xmlsd_elem_get_value_strtonum(), and xmlsd_elem_get_value_hexnum(), and xmlsd_elem_get_value_boolean() may be used if additional processing of the value is needed. Similarly to the functions provided for the value, the values of the attributes for an element may be accessed using xmlsd_elem_get_attr(), xmlsd_elem_get_attr_strtonum(), xmlsd_elem_get_attr_hexnum(), or xmlsd_elem_get_attr_boolean().

A direct child of an element can be searched for using xmlsd_elem_find_child(), alternatively xmlsd_elem_get_first_child(), xmlsd_elem_get_next_child(), xmlsd_elem_get_last_child(and) xmlsd_elem_get_previous may be used to iterate over the children. The macro XMLSD_ELEM_FOREACH_CHILDREN() may be used as a convenient interface to the above.

A struct xmlsd_attribute may be accessed using xmlsd_attr_get_name() to access the name, and xmlsd_attr_get_value() for the value.

Two interfaces exist for parsing XML documents into xmlsd structures. xmlsd_parse_file() will parse the xml document in that is stored in file into xd, xmlsd_parse_mem() will parse the xml document stored in buf. Both functions will return 0 on success or non zero on error.

A string containing an XML document may be generated from struct xmlsd_document using xmlsd_generate.() This function will generate the string from xd allocating the string using alloc_fn and return the size in szp. flags may be any of the following:
XMLSD_GEN_ADD_HEADER
    add a header with the encoding and xml version to the xml defined in the document. Without this flag only the elements explicitly in the will be included.

xmlsd provides facilities to validate an XML document against an expected structure. xmlsd_validate() will validate xd against the structures in v_elem returnng 0 on success or non-zero on failure. xmlsd_validate_info() may be used if more information is required about the validation failure, this function will populate xvf with information about the failure. xmlsd_get_validate_failure_string() may be used to get an informational string from xvf. xmlsd_validate_v_elements() may be used to verify that the validation strucures themsevles are valid for debugging purposes, with xmlsd_get_validate_v_elements_failure_string() providing a textual explanation of failures.

EXAMPLES
The regression directory in the xmlsd source distribution contains a few authorative examples of library usage.

HISTORY
-nosplit xmlsd was written by Conformal Systems, LLC. <info@conformal.com>.