GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRUCTS_XML_INPUT (3)

NAME

structs_xml_input, structs_xml_output - XML conversion for data structures

CONTENTS

Library
Synopsis
Description
Return Values
See Also
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In stdio.h
.In pdel/structs/structs.h
.In 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 instance.

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 already 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 output, 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 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 parameters 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)
.Rs Extensible Markup Language (XML) 1.0 (Second Edition)
.Re

HISTORY

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

AUTHORS


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.