Annotation of embedaddon/libpdel/structs/structs_xml_input.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: structs_xml_input.3,v 1.20 2004/06/02 17:24:38 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt STRUCTS_XML_INPUT 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm structs_xml_input ,
! 45: .Nm structs_xml_output
! 46: .Nd XML conversion for data structures
! 47: .Sh LIBRARY
! 48: PDEL Library (libpdel, \-lpdel)
! 49: .Sh SYNOPSIS
! 50: .In sys/types.h
! 51: .In stdio.h
! 52: .In pdel/structs/structs.h
! 53: .In pdel/structs/xml.h
! 54: .Ft int
! 55: .Fn 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"
! 56: .Ft int
! 57: .Fn 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"
! 58: .Sh DESCRIPTION
! 59: These routines convert instances of
! 60: .Xr structs 3
! 61: data structures to and from XML.
! 62: .Pp
! 63: .Fn structs_xml_input
! 64: reads an XML document from the stream
! 65: .Fa fp
! 66: and attempts to parse it as an instance of the data structure type
! 67: described by
! 68: .Fa type .
! 69: .Fa data
! 70: must point to a region of memory large enough to hold such an instance.
! 71: .Pp
! 72: The
! 73: .Fa elem_tag
! 74: is the XML document tag expected.
! 75: This is the top-level XML tag and the only tag that may contain attributes.
! 76: If
! 77: .Fa attrp
! 78: is not
! 79: .Dv NULL ,
! 80: then any attributes with this tag are concatenated together
! 81: as name, value pairs with a final terminating '\\0' like so:
! 82: .Pp
! 83: .Bd -literal -compact -offset 3n
! 84: name1 '\\0' value1 '\\0'
! 85: name2 '\\0' value2 '\\0'
! 86: ...
! 87: nameN '\\0' valueN '\\0'
! 88: '\\0'
! 89: .Ed
! 90: .Pp
! 91: The concatenated name, value pairs are stored in a buffer allocated with
! 92: .Xr typed_mem 3
! 93: type
! 94: .Fa attr_type ,
! 95: a pointer to which is then stored in
! 96: .Fa "*attrp" .
! 97: The caller is responsible for freeing this memory.
! 98: .Pp
! 99: The
! 100: .Fa logger
! 101: is a pointer to a logging function having this type:
! 102: .Pp
! 103: .Bd -literal -compact -offset 3n
! 104: typedef void structs_xmllog_t(int sev, const char *fmt, ...);
! 105: .Ed
! 106: .Pp
! 107: Here
! 108: .Fa sev
! 109: is a
! 110: .Xr syslog 3
! 111: severity level.
! 112: .Fa logger
! 113: may also take one of the following predefined values:
! 114: .Pp
! 115: .Bd -literal -compact -offset 3n
! 116: STRUCTS_LOGGER_NONE Discard log output
! 117: STRUCTS_LOGGER_STDERR Log to standard error
! 118: STRUCTS_LOGGER_ALOG Log using alog(3)
! 119: .Ed
! 120: .Pp
! 121: The
! 122: .Fa flags
! 123: argument may contain any of the following values OR'd together:
! 124: .Pp
! 125: .Bd -literal -compact -offset 3n
! 126: STRUCTS_XML_UNINIT The data structure is uninitialized
! 127: STRUCTS_XML_LOOSE Unknown tags and nested attributes OK
! 128: STRUCTS_XML_SCAN Don't try to build data structure
! 129: STRUCTS_XML_COMB_TAGS Allow combined tags
! 130: .Ed
! 131: .Pp
! 132: The
! 133: .Dv STRUCTS_XML_UNINIT
! 134: flag indicates that the region of memory pointed to by
! 135: .Fa data
! 136: is uninitialized and that
! 137: .Fn structs_xml_input
! 138: should initialize it first.
! 139: Otherwise,
! 140: .Fn structs_xml_input
! 141: assumes the data structure is already initialized.
! 142: .Pp
! 143: .Dv STRUCTS_XML_LOOSE
! 144: specifies "loose" parsing: any unrecognized XML tags and nested attributes
! 145: may generate a warning but should otherwise be ignored.
! 146: If this flag is not specified, these will cause a fatal error.
! 147: .Pp
! 148: .Dv STRUCTS_XML_SCAN
! 149: causes the parser scan the XML but not try to decode the data structure.
! 150: The
! 151: .Fa type
! 152: and
! 153: .Fa data
! 154: parameters are ignored;
! 155: however, the other parameters are still used, e.g., the top level
! 156: XML document tag must match and it's still possible to retrieve its
! 157: attributes.
! 158: .Pp
! 159: .Dv STRUCTS_XML_COMB_TAGS
! 160: allows combining of nested XML tags.
! 161: For example, if
! 162: .Dq bar
! 163: is the only XML tag contained in
! 164: .Dq foo ,
! 165: then the input
! 166: .Li "<foo><bar>...</bar></foo>"
! 167: may be abbreviated as
! 168: .Li "<foo.bar>...</foo.bar>" .
! 169: Note this presents a parse ambiguity if there is also
! 170: a structure or union field at the same level that contains the
! 171: .Dq \&.
! 172: character, e.g.
! 173: .Dq foo.bar .
! 174: Such field names always match first when uncombined; they never match
! 175: when combined with other tags.
! 176: .Pp
! 177: All of the fields defined in the data structure need not be present in the
! 178: XML input; missing fields are left unmodified.
! 179: Therefore if the
! 180: .Dv STRUCTS_XML_UNINIT
! 181: flag is not specified, the XML input is
! 182: .Dq overlayed
! 183: on top of the existing data structure.
! 184: .Pp
! 185: .Fn structs_xml_output
! 186: outputs the contents of the data structure having
! 187: .Xr structs 3
! 188: type
! 189: .Fa type
! 190: and pointed to by
! 191: .Fa data
! 192: in XML format to the stream
! 193: .Fa fp .
! 194: The document tag is specified by
! 195: .Fa elem_tag ,
! 196: along with optional attributes specified by a non-
! 197: .Dv NULL
! 198: .Fa attrs
! 199: pointing to the concatenated attributes as described above.
! 200: .Pp
! 201: If only specific sub-fields of the data structure are desired in the
! 202: output, these may be specified with a non-
! 203: .Dv NULL
! 204: .Fa elems ,
! 205: which points to a
! 206: .Dv NULL
! 207: terminated array of sub-field names.
! 208: In this array, the empty string may be used to mean the entire data structure
! 209: (which is equivalent to
! 210: .Fa elems
! 211: being
! 212: .Dv NULL) .
! 213: .Pp
! 214: The
! 215: .Fa flags
! 216: argument may contain any of the following values OR'd together:
! 217: .Pp
! 218: .Bd -literal -compact -offset 3n
! 219: STRUCTS_XML_FULL Output a sub-field equal to its default value
! 220: .Ed
! 221: .Pp
! 222: By default,
! 223: .Fn structs_xml_output
! 224: will omit outputting any sub-field that is equal to its default value.
! 225: The
! 226: .Dv STRUCTS_XML_FULL
! 227: disables this behavior.
! 228: .Sh RETURN VALUES
! 229: All of the above functions indicate an error condition by returning
! 230: either -1 or
! 231: .Dv NULL
! 232: and setting
! 233: .Va errno
! 234: to an appropriate value.
! 235: .Pp
! 236: Whenever there is an error, no partial work is done: the state of
! 237: the parameters has not changed, and nothing has been allocated or freed.
! 238: .Sh SEE ALSO
! 239: .Xr http_servlet_xmlrpc 3 ,
! 240: .Xr http_xml 3 ,
! 241: .Xr libpdel 3 ,
! 242: .Xr structs 3 ,
! 243: .Xr structs_xmlrpc 3 ,
! 244: .Xr typed_mem 3
! 245: .Rs
! 246: .%T "Extensible Markup Language (XML) 1.0 (Second Edition)"
! 247: .%O "http://www.w3.org/TR/REC-xml"
! 248: .Re
! 249: .Sh HISTORY
! 250: The PDEL library was developed at Packet Design, LLC.
! 251: .Dv "http://www.packetdesign.com/"
! 252: .Sh AUTHORS
! 253: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs_xml_input.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / structs