Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
STRUCTS_XML_INPUT(3)   FreeBSD Library Functions Manual	  STRUCTS_XML_INPUT(3)

NAME
     structs_xml_input,	structs_xml_output -- XML conversion for data struc-
     tures

LIBRARY
     PDEL Library (libpdel, -lpdel)

SYNOPSIS
     #include <sys/types.h>
     #include <stdio.h>
     #include <pdel/structs/structs.h>
     #include <pdel/structs/xml.h>

     int
     structs_xml_input(const struct structs_type *type,	const char *elem_tag,
	 char **attrp, const char *attr_type, FILE *fp,	void *data, int	flags,
	 structs_xmllog_t *logger);

     int
     structs_xml_output(const struct structs_type *type, const char *elem_tag,
	 const char *attrs, const void *data, FILE *fp,	const char **elems,
	 int flags);

DESCRIPTION
     These routines convert instances of structs(3) data structures to and
     from XML.

     structs_xml_input() reads an XML document from the	stream fp and attempts
     to	parse it as an instance	of the data structure type described by	type.
     data must point to	a region of memory large enough	to hold	such an	in-
     stance.

     The elem_tag is the XML document tag expected.  This is the top-level XML
     tag and the only tag that may contain attributes.	If attrp is not	NULL,
     then any attributes with this tag are concatenated	together as name,
     value pairs with a	final terminating '\0' like so:

	    name1 '\0' value1 '\0'
	    name2 '\0' value2 '\0'
	    ...
	    nameN '\0' valueN '\0'
	    '\0'

     The concatenated name, value pairs	are stored in a	buffer allocated with
     typed_mem(3) type attr_type, a pointer to which is	then stored in *attrp.
     The caller	is responsible for freeing this	memory.

     The logger	is a pointer to	a logging function having this type:

	typedef	void structs_xmllog_t(int sev, const char *fmt,	...);

     Here sev is a syslog(3) severity level.  logger may also take one of the
     following predefined values:

	STRUCTS_LOGGER_NONE	 Discard log output
	STRUCTS_LOGGER_STDERR	 Log to	standard error
	STRUCTS_LOGGER_ALOG	 Log using alog(3)

     The flags argument	may contain any	of the following values	OR'd together:

	STRUCTS_XML_UNINIT	 The data structure is uninitialized
	STRUCTS_XML_LOOSE	 Unknown tags and nested attributes OK
	STRUCTS_XML_SCAN	 Don't try to build data structure
	STRUCTS_XML_COMB_TAGS	 Allow combined	tags

     The STRUCTS_XML_UNINIT flag indicates that	the region of memory pointed
     to	by data	is uninitialized and that structs_xml_input() should initial-
     ize it first.  Otherwise, structs_xml_input() assumes the data structure
     is	already	initialized.

     STRUCTS_XML_LOOSE specifies "loose" parsing: any unrecognized XML tags
     and nested	attributes may generate	a warning but should otherwise be ig-
     nored.  If	this flag is not specified, these will cause a fatal error.

     STRUCTS_XML_SCAN causes the parser	scan the XML but not try to decode the
     data structure.  The type and data	parameters are ignored;	however, the
     other parameters are still	used, e.g., the	top level XML document tag
     must match	and it's still possible	to retrieve its	attributes.

     STRUCTS_XML_COMB_TAGS allows combining of nested XML tags.	 For example,
     if	"bar" is the only XML tag contained in "foo", then the input
     <foo><bar>...</bar></foo> may be abbreviated as <foo.bar>...</foo.bar>.
     Note this presents	a parse	ambiguity if there is also a structure or
     union field at the	same level that	contains the "." character, e.g.
     "foo.bar".	 Such field names always match first when uncombined; they
     never match when combined with other tags.

     All of the	fields defined in the data structure need not be present in
     the XML input; missing fields are left unmodified.	 Therefore if the
     STRUCTS_XML_UNINIT	flag is	not specified, the XML input is	"overlayed" on
     top of the	existing data structure.

     structs_xml_output() outputs the contents of the data structure having
     structs(3)	type type and pointed to by data in XML	format to the stream
     fp.  The document tag is specified	by elem_tag, along with	optional at-
     tributes specified	by a non- NULL attrs pointing to the concatenated at-
     tributes as described above.

     If	only specific sub-fields of the	data structure are desired in the out-
     put, these	may be specified with a	non- NULL elems, which points to a
     NULL terminated array of sub-field	names.	In this	array, the empty
     string may	be used	to mean	the entire data	structure (which is equivalent
     to	elems being NULL).

     The flags argument	may contain any	of the following values	OR'd together:

	STRUCTS_XML_FULL   Output a sub-field equal to its default value

     By	default, structs_xml_output() will omit	outputting any sub-field that
     is	equal to its default value.  The STRUCTS_XML_FULL disables this	behav-
     ior.

RETURN VALUES
     All of the	above functions	indicate an error condition by returning ei-
     ther -1 or	NULL and setting errno to an appropriate value.

     Whenever there is an error, no partial work is done: the state of the pa-
     rameters has not changed, and nothing has been allocated or freed.

SEE ALSO
     http_servlet_xmlrpc(3), http_xml(3), libpdel(3), structs(3),
     structs_xmlrpc(3),	typed_mem(3)

     Extensible	Markup Language	(XML) 1.0 (Second Edition),
     http://www.w3.org/TR/REC-xml.

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=structs_xml_input&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help