STRUCTS_XML_INPUT(3) Library Functions Manual STRUCTS_XML_INPUT(3) NAME structs_xml_input, structs_xml_output -- XML conversion for data structures 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 initialize it first. Otherwise, structs_xml_input() assumes the data structure is al- ready initialized. STRUCTS_XML_LOOSE specifies "loose" parsing: any unrecognized XML tags and nested attributes may generate a warning but should otherwise be ignored. 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 attributes specified by a non- NULL attrs pointing to the concatenated attributes 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 be- ing 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 behavior. RETURN VALUES All of the above functions indicate an error condition by returning either -1 or NULL and setting errno to an appropriate value. Whenever there is an error, no partial work is done: the state of the para- meters has not changed, and nothing has been allocated or freed. SEE ALSO http_servlet_xmlrpc(3), http_xml(3), libpdel(3), structs(3), structs_xml- rpc(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 ports 15.quarterly April 22, 2002 STRUCTS_XML_INPUT(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=structs_xml_output&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>