xmlsd.3

.\"
.\" Copyright (c) 2011 Conformal Systems LLC <info@conformal.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 10 2011 $
.Dt XMLSD 3
.Os
.Sh NAME
.Nm xmlsd
.Nd xml validation library
.Sh SYNOPSIS
.Fd #include <xmlsd.h>
.Ft int
.Fn xmlsd_doc_alloc "struct xmlsd_document **xdp"
.Ft void
.Fn xmlsd_doc_clear "struct xmlsd_document *xd"
.Ft void
.Fn xmlsd_doc_free "struct xmlsd_document *xd"
.Ft int
.Fn xmlsd_doc_is_empty "struct xmlsd_document *xd"
.Ft struct xmlsd_element *
.Fn xmlsd_doc_get_first_elem "struct xmlsd_document *xd"
.Ft struct xmlsd_element *
.Fn xmlsd_doc_add_elem "struct xmlsd_document *xd" "struct xmlsd_element *parent" "const char *name"
.Ft void
.Fn xmlsd_doc_remove_elem "struct xmlsd_document *xd" "struct xmlsd_element *xe"

.Ft int
.Fn xmlsd_validate "struct xmlsd_document *xd" "struct xmlsd_v_elements *v_elem"
.Ft int
.Fn xmlsd_validate_info "struct xmlsd_document *xd" "struct xmlsd_v_elements *v_elem, "struct xmlsd_validate_failure *xvf"
.Ft char
.Fn xmlsd_get_validate_failure_string "struct xmlsd_validate_failure *xvf"
.Ft enum xmlsd_validate_v_elements_failure
.Fn xmlsd_validate_v_elements "struct xmlsd_v_elements *cmds", "struct xmlsd_v_elements_validation *xvev"
.Ft char
.Fn xmlsd_get_validate_v_elements_failure_string "struct xmlsd_validate_v_elements_validation *xvev"

.Ft int
.Fn xmlsd_parse_fileds "int fd" "struct xmlsd_document *xd"
.Ft int
.Fn xmlsd_parse_file "FILE *file" "struct xmlsd_document *xd"
.Ft int
.Fn xmlsd_parse_mem "const char *buf" "size_t len" "struct xmlsd_document *xd"

.Ft char *
.Fn xmlsd_generate "struct xmlsd_document *xd" "void *(*alloc_fn)(size_t)" "size_t *szp" "int flags"


.Ft const char *
.Fn xmlsd_attr_get_name "struct xmlsd_attribute *xa"
.Ft const char *
.Fn xmlsd_attr_get_value "struct xmlsd_attribute *xa"


.Ft const char *
.Fn xmlsd_elem_get_name "struct xmlsd_element *xe"
.Ft const char *
.Fn xmlsd_elem_get_value "struct xmlsd_element *xe"
.Ft long long
.Fn xmlsd_elem_get_value_strtonum "struct xmlsd_elment *xd" "unsigned long long minval" "unsigned long long maxval" "const char **errstring"
.Ft unsigned long long
.Fn xmlsd_elem_get_value_hexnum "struct xmlsd_elment *xd" "unsigned long long minval" "unsigned long long maxval" "const char **errstring"
.Ft int
.Fn xmlsd_elem_get_value_boolean "struct xmlsd_element *xe" "int *bool" "int
default"
.Ft int
.Fn xmlsd_elem_get_depth "struct xmlsd_element *xe"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_get_parent "struct xmlsd_element *"
.Ft const char *
.Fn xmlsd_elem_get_attr "struct xmlsd_element *xe" "const char *name"
.Ft long long
.Fn xmlsd_elem_get_attr_strtonum "struct xmlsd_elment *xd" "const char *name" "unsigned long long minval" "unsigned long long maxval" "const char **errstring"
.Ft unsigned long long
.Fn xmlsd_elem_get_attr_hexnum "struct xmlsd_elment *xd" "const char *name" "unsigned long long minval" "unsigned long long maxval" "const char **errstring"
.Ft int
.Fn xmlsd_elem_get_attr_boolean "struct xmlsd_element *xe" "const char *name" "int *bool" "int
.Ft struct xmlsd_attribute *
.Fn xmlsd_elem_find_attr "struct xmlsd_element *xe" "const char *name"
.Ft struct xmlsd_attribute *
.Fn xmlsd_elem_get_first_attr "struct xmlsd_element *xe"
.Ft struct xmlsd_attribute *
.Fn xmlsd_elem_get_next_attr "struct xmlsd_element *xe" "struct xmlsd_attribute *cur"
.Ft struct xmlsd_attribute *
.Fn xmlsd_elem_get_last_attr "struct xmlsd_element *xe"
.Ft struct xmlsd_attribute *
.Fn xmlsd_elem_get_previous_attr "struct xmlsd_element *xe" "struct xmlsd_attribute *cur"
.Fn XMLSD_ELEM_FOREACH_ATTR "struct xmlsd_attribute *attr" "struct xmlsd_element *elem"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_find_child "struct xmlsd_elment *xe" "const char *name"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_get_first_child "struct xmlsd_elment *xe"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_get_next_child "struct xmlsd_elment *xe" "struct xmlsd_element *cur"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_get_last_child "struct xmlsd_elment *xe"
.Ft struct xmlsd_element *
.Fn xmlsd_elem_get_previous_child "struct xmlsd_elment *xe" "struct xmlsd_element *cur"
.Fn XMLSD_ELEM_FOREACH_CHILDREN "struct xmlsd_element *child" "struct xmlsd_element *elem"

.Ft int	
.Fn xmlsd_elem_set_attr "struct xmlsd_element *xe" "const char *name" "const char *value"
.Ft int
.Fn xmlsd_elem_set_attr_int32 "struct xmlsd_element *xe" "const char *name" "int32_t value"
.Ft int
.Fn xmlsd_elem_set_attr_uint32  "struct xmlsd_element *xe" "const char *name" "uint32_t value"
.Ft int
.Fn xmlsd_elem_set_attr_int64 "struct xmlsd_element *xe" "const char *name" "int64_t value"
.Ft int
.Fn xmlsd_elem_set_attr_uint64 "struct xmlsd_element *xe" "const char *name" "uint64_t value"
.Ft int
.Fn xmlsd_elem_set_attr_x32 "struct xmlsd_element *xe" "const char *name" "uint32_t value"
.Ft int
.Fn xmlsd_elem_set_attr_x64 "struct xmlsd_element *xe" "const char *name" "uint64_t value"
.Ft int
.Fn xmlsd_elem_set_value "struct xmlsd_element *xe" "const char *value"
.Ft int
.Fn xmlsd_elem_set_value_int32 "struct xmlsd_element *xe" "int32_t value"
.Ft int
.Fn xmlsd_elem_set_value_uint32 "struct xmlsd_element *xe" "uint32_t value"
.Ft int
.Fn xmlsd_elem_set_value_int64 "struct xmlsd_element *xe" "int64_t value"
.Ft int
.Fn xmlsd_elem_set_value_uint64 "struct xmlsd_element *xe" "uint64_t value"
.Ft int
.Fn xmlsd_elem_set_value_x32 "struct xmlsd_element *xe" "uint32_t value"
.Ft int
.Fn xmlsd_elem_set_value_x64 "struct xmlsd_element *xe" "uint64_t value"
.Ft void
.Fn xmlsd_elem_free "struct xmlsd_element *xe"

.Ft void
.Fn xmlsd_version "int *major" "int *minor" "int *patch"
.Sh DESCRIPTION
The
.Nm
library has three basic types:
.Vt struct xmlsd_document ,
.Vt struct xmlsd_element ,
and
.Vt struct xmlsd_attribute ,
Representing the various parts of an xml document.

The top-level type
.Vt xmlsd_document
is required before any other manipulation occurs on the document.
.Fn xmlsd_doc_alloc
allocates an
.Vt xmlsd_document
to
.Fa 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
.Fn xmlsd_doc_clear ,
or cleared and freed by
.Fn xmlsd_doc_free .
.Fn xmlsd_doc_is_empty
returns true or false if the document is empty or not.
.Fn xmlsd_doc_get_root ,
will return either the root element, or NULL if empty.
.Pp
.Vt struct xmlsd_element
represents an individual element within an XML document.
A new element is added to a document using
.Fn xmlsd_doc_add_elem
which will add an elemnt with name
.Fa name
to the document 
.Fa xd
with the parent
.Fa parent ,
The new element will be returned.
If
.Fa parent
is NULL then the element will be added as the root element of the document.
Conversely,
.Fn xmlsd_doc_remove_elem
will remove an element (and its children).
To fully initialize the new element attributes may be set with
.Fn xmlsd_elem_set_attr ,
which will add an attribute with
.Fa name
and
.Fa value
to
.Fa xe .
alternative versions of the function exist to set attributes with given types.
.Fn 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:
.Fn xmlsd_elem_get_name ,
.Fn xmlsd_elem_get_value ,
.Fn xmlsd_elem_get_depth ,
and
.Fn xmlsd_elem-get_parent
will return the named property from an element.
additonally
.Fn xmlsd_elem_get_value_strtonum ,
and
.Fn xmlsd_elem_get_value_hexnum  ,
and
.Fn 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
.Fn xmlsd_elem_get_attr ,
.Fn xmlsd_elem_get_attr_strtonum ,
.Fn xmlsd_elem_get_attr_hexnum ,
or
.Fn xmlsd_elem_get_attr_boolean .
.Pp
A direct child of an element can be searched for using 
.Fn xmlsd_elem_find_child ,
alternatively
.Fn xmlsd_elem_get_first_child ,
.Fn xmlsd_elem_get_next_child ,
.Fn xmlsd_elem_get_last_child and
xmlsd_elem_get_previous may be used to iterate over the children.
The macro
.Fn XMLSD_ELEM_FOREACH_CHILDREN
may be used as a convenient interface to the above.
.Pp
A
.Vt struct xmlsd_attribute
may be accessed using
.Fn xmlsd_attr_get_name
to access the name,
and
.Fn xmlsd_attr_get_value
for the value.
.Pp
Two interfaces exist for parsing XML documents into
.Nm
structures.
.Fn xmlsd_parse_file
will parse the xml document in that is stored in
.Fa file
into
.Fa xd,
.Fn xmlsd_parse_mem
will parse the xml document stored in
.Fa buf .
Both functions will return 0 on success or non zero on error.
.Pp
A string containing an XML document may be generated from
.Vt struct xmlsd_document
using
.Fn xmlsd_generate.
This function will generate the string from
.Fa xd
allocating the string using
.Fa alloc_fn
and return the size in
.Fa szp.
.Fa flags
may be any of the following:
.Bl -tag -width "XMLSD_GEN_ADD_HEADER" -compact
.It Fa 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
.Xv xmlsd_document
will be included.
.El
.Pp
.Nm
provides facilities to validate an XML document against an expected structure.
.Fn xmlsd_validate
will validate
.Fa xd
against the structures in 
.Fa v_elem
returnng 0 on success or non-zero on failure.
.Fn xmlsd_validate_info
may be used if more information is required about the validation failure,
this function will populate
.Fa xvf
with information about the failure.
.Fn xmlsd_get_validate_failure_string
may be used to get an informational string from
.Fa xvf.
.Fn xmlsd_validate_v_elements
may be used to verify that the validation strucures themsevles are valid for
debugging purposes, with 
.Fn xmlsd_get_validate_v_elements_failure_string
providing a textual explanation of failures.
.Sh EXAMPLES
The regression directory in the
.Nm
source distribution contains a few authorative examples of library
usage.
.Sh HISTORY
.An -nosplit
.Nm
was written by
.An Conformal Systems, LLC. Aq info@conformal.com .