Annotation of embedaddon/libpdel/structs/structs_xml_input.3, revision 1.1.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