Annotation of embedaddon/libpdel/structs/structs_xmlrpc.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_xmlrpc.3,v 1.16 2004/06/02 17:24:38 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt STRUCTS_XMLRPC 3
42: .Os
43: .Sh NAME
44: .Nm structs_xmlrpc
45: .Nd structs support for XML-RPC
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In pdel/structs/structs.h
51: .In pdel/structs/type/array.h
52: .In pdel/structs/type/union.h
53: .In pdel/structs/xmlrpc.h
54: .Ft int
55: .Fn structs_struct2xmlrpc "const struct structs_type *type" "const void *data" "const char *sname" "const struct structs_type *xtype" "void *xdata" "const char *xname"
56: .Ft int
57: .Fn structs_xmlrpc2struct "const struct structs_type *xtype" "const void *xdata" "const char *xname" "const struct structs_type *type" "void *data" "const char *sname" "char *ebuf" "size_t emax"
58: .Ft "struct xmlrpc_request *"
59: .Fn structs_xmlrpc_build_request "const char *mtype" "const char *methodName" "u_int nparams" "const struct structs_type **types" "const void **params"
60: .Ft "struct xmlrpc_response_union *"
61: .Fn structs_xmlrpc_build_response "const char *mtype" "const struct structs_type *type" "const void *data"
62: .Ft "struct xmlrpc_response_union *"
63: .Fn structs_xmlrpc_build_fault_response "const char *mtype" "const struct xmlrpc_compact_fault *fault"
64: .Vt extern const struct structs_type structs_type_xmlrpc_value ;
65: .Vt extern const struct structs_type structs_type_xmlrpc_array ;
66: .Vt extern const struct structs_type structs_type_xmlrpc_member ;
67: .Vt extern const struct structs_type structs_type_xmlrpc_struct ;
68: .Vt extern const struct structs_type structs_type_xmlrpc_request ;
69: .Vt extern const struct structs_type structs_type_xmlrpc_response ;
70: .Vt extern const struct structs_type structs_type_xmlrpc_fault ;
71: .Vt extern const struct structs_type structs_type_xmlrpc_compact_fault ;
72: .Sh DESCRIPTION
73: These functions and
74: .Xr structs 3
75: types provide support for XML-RPC, i.e.,
76: conversion between XML-RPC values and native C data types.
77: .\"
78: .Ss Compact and Exploded Types
79: .\"
80: For any XML-RPC data structure, there are two
81: .Xr structs 3
82: types that describe it: a
83: .Dq compact
84: type and an
85: .Dq exploded
86: type.
87: Applications usually work with compact (or native C) types, i.e., where
88: XML-RPC i32's are represented by C int32_t's, XML-RPC struct's are
89: represented by C structures, and so on.
90: In order to convert between native data structures and XML-RPC, intermediate
91: .Dq exploded
92: types are used.
93: This man page describes
94: .Xr structs 3
95: types for the exploded XML-RPC data structures and functions to convert
96: between the compact and exploded forms.
97: .Pp
98: That is, XML-RPC is just a special case of
99: .Xr structs 3
100: types converted into XML with lots of extra nesting so that a fixed set
101: of XML tags may be used.
102: The exploded types are simply the
103: .Xr structs 3
104: types that include the extra nesting so that when they are converted
105: to XML in the normal fashion (see
106: .Xr structs_xml_output 3) ,
107: the result is a well-formed XML-RPC request or response.
108: .Pp
109: The following types data structures are defined in the header file
110: .Li "<pdel/structs/xmlrpc.h>" :
111: .Pp
112: .Fa structs_type_xmlrpc_value
113: is a
114: .Xr structs 3
115: type representing an exploded XML-RPC value, i.e., a
116: .Li "struct xmlrpc_value_union" .
117: .Pp
118: .Fa structs_type_xmlrpc_array
119: is a
120: .Xr structs 3
121: type representing an exploded XML-RPC array, i.e., a
122: .Li "struct xmlrpc_array" .
123: .Pp
124: .Fa structs_type_xmlrpc_member
125: is a
126: .Xr structs 3
127: type representing an exploded XML-RPC structure member, i.e., a
128: .Li "struct xmlrpc_member" .
129: .Pp
130: .Fa structs_type_xmlrpc_struct
131: is a
132: .Xr structs 3
133: type representing an exploded XML-RPC structure, i.e., a
134: .Li "struct xmlrpc_struct" .
135: .Pp
136: .Fa structs_type_xmlrpc_request
137: is a
138: .Xr structs 3
139: type representing an exploded XML-RPC request, i.e., a
140: .Li "struct xmlrpc_request" .
141: .Pp
142: .Fa structs_type_xmlrpc_response
143: is a
144: .Xr structs 3
145: type representing an exploded XML-RPC response, i.e., a
146: .Li "struct xmlrpc_response_union" .
147: .Pp
148: .Fa structs_type_xmlrpc_fault
149: is a
150: .Xr structs 3
151: type representing an exploded XML-RPC fault, i.e., a
152: .Li "struct xmlrpc_fault" .
153: .Pp
154: .Fa structs_type_xmlrpc_compact_fault
155: is a
156: .Xr structs 3
157: type representing an XML-RPC fault in a compact form, i.e., a
158: .Li "struct xmlrpc_compact_fault" :
159: .Bd -literal -offset 3n
160: struct xmlrpc_compact_fault {
161: int32_t faultCode; /* XML-RPC fault code */
162: char *faultString; /* XML-RPC fault string */
163: };
164: .Ed
165: .\"
166: .Ss Conversion Routines
167: .\"
168: .Fn structs_struct2xmlrpc
169: converts an arbitrary compact
170: .Xr structs 3
171: instance into an
172: .Dq exploded
173: XML-RPC value.
174: The original instance should be pointed to by
175: .Fa data
176: and have
177: .Xr structs 3
178: type
179: .Fa type ,
180: while the XML-RPC instance should be pointed to by
181: .Fa xdata
182: and have
183: .Xr structs 3
184: type
185: .Fa xtype .
186: .Fa sname
187: and
188: .Fa xname
189: may be non-
190: .Dv NULL
191: to name specific sub-fields of
192: .Fa data
193: and
194: .Fa xdata ,
195: respectively, to convert.
196: The
197: .Fa xdata
198: instance must already be initialized, and the sub-field of
199: .Fa xdata
200: specified by
201: .Fa xname
202: must have type
203: .Fa structs_type_xmlrpc_value ,
204: i.e., it must be a
205: .Li "struct xmlrpc_value_union" .
206: .Pp
207: The following primitive
208: .Xr structs 3
209: types are specially recognized by
210: .Fn structs_struct2xmlrpc :
211: .Bl -tag -width "xxxxx" -offset indent
212: .It Xo
213: .Va structs_type_int32 ,
214: and
215: .Va structs_type_int
216: when
217: .Li "sizeof(int) == 4"
218: .Xc
219: Converted to <i4>.
220: .It Xo
221: .Va structs_type_boolean
222: and all variants
223: .Xc
224: Converted to <boolean>.
225: .It Va structs_type_float
226: Converted to <double>.
227: .It Va structs_type_double
228: Converted to <double>.
229: .It Va structs_type_time_iso8601
230: Converted to <dateTime.iso8601>.
231: .It Xo
232: .Va structs_type_data
233: or any variant using the default character set
234: .Xc
235: Converted to <base64>.
236: .It Xo
237: Variable and fixed length array types
238: .Xc
239: Converted to <array>.
240: .It Xo
241: Structure types
242: .Xc
243: Converted to <struct>.
244: .It Xo
245: Union types
246: .Xc
247: Converted to <struct>.
248: .El
249: .Pp
250: All other primitive types are converted to XML-RPC <string>'s.
251: .Pp
252: .Fn structs_xmlrpc2struct
253: converts an XML-RPC value back into a
254: .Dq compact
255: data structure, essentially the reverse of
256: .Fn structs_struct2xmlrpc .
257: As before,
258: .Fa xname ,
259: .Fa xdata ,
260: and
261: .Fa xtype
262: describe the XML-RPC value and
263: .Fa sname ,
264: .Fa data ,
265: and
266: .Fa type
267: describe the normal, native instance.
268: The
269: .Fa data
270: instance must already be initialized.
271: The sub-field of
272: .Fa xdata
273: specified by
274: .Fa xname
275: must have type
276: .Fa structs_type_xmlrpc_value ,
277: i.e., it must be a
278: .Li "struct xmlrpc_value_union" .
279: In addition, an error buffer pointed to by
280: .Fa ebuf
281: having size
282: .Fa emax
283: may be provided; if so, any errors from the decoding will be written into it.
284: .Pp
285: Scalar XML-RPC values are converted into primitive types by simply calling
286: .Xr structs_set_string 3 .
287: There is no checking that the XML-RPC tag is consistent with the
288: primitive structs type; i.e., if the primitive type successfully parses
289: the string, then it's assumed to be OK.
290: .Pp
291: Array XML-RPC values are converted into array types.
292: Structure XML-RPC values are converted into structure types or union types,
293: depending on the destination type provided.
294: In the union case, the last field specified in the XML-RPC structure is
295: chosen for the union.
296: Other fields specified must be valid for the union, but are otherwise ignored.
297: .\"
298: .Ss XML-RPC Requests and Responses
299: .\"
300: .Fn structs_xmlrpc_build_request
301: creates an XML-RPC request instance from native,
302: .Dq compact
303: parameter data structures.
304: .Fa methodName
305: is the XML-RPC request method name.
306: There will be
307: .Fa nparams
308: parameters in the request;
309: .Fa types
310: must point to an array of
311: .Fa nparams
312: .Xr structs 3
313: parameter types and
314: .Fa params
315: an array of
316: .Fa nparams
317: parameter values having the corresponding types.
318: .Pp
319: To build the request directly out of
320: .Dq exploded
321: XML-RPC parameter values, set
322: .Fa types
323: to
324: .Dv NULL .
325: Then it will be assumed that each parameter in the
326: .Fa params
327: array is an instance of
328: .Fa structs_type_xmlrpc_value ,
329: i.e., a
330: .Li "struct xmlrpc_value_union" .
331: .Pp
332: If successful,
333: .Fn structs_xmlrpc_build_request
334: returns an instance of type
335: .Fa structs_type_xmlrpc_request ,
336: i.e., a
337: .Li "struct xmlrpc_request" ,
338: in a memory block allocated with
339: .Xr typed_mem
340: type
341: .Fa mtype ,
342: which the caller is responsible for unintializing and freeing.
343: .Pp
344: .Fn structs_xmlrpc_build_response
345: creates an XML-RPC response.
346: The response data structure (i.e., the XML-RPC return value)
347: pointed to by
348: .Fa data
349: should be
350: .Dq compact
351: and have
352: .Xr structs 3
353: type
354: .Fa type .
355: .Pp
356: To directly send an
357: .Dq exploded
358: XML-RPC return value, set
359: .Fa type
360: to
361: .Dv NULL .
362: Then it will be assumed that
363: .Fa data
364: points to an instance of
365: .Fa structs_type_xmlrpc_value ,
366: i.e., a
367: .Li "struct xmlrpc_value_union" .
368: .Pp
369: If successful,
370: .Fn structs_xmlrpc_build_response
371: returns an instance of type
372: .Fa structs_type_xmlrpc_response ,
373: i.e., a
374: .Li "struct xmlrpc_response_union" ,
375: in a memory block allocated with
376: .Xr typed_mem
377: type
378: .Fa mtype ,
379: which the caller is responsible for unintializing and freeing.
380: .Pp
381: .Fn structs_xmlrpc_build_fault_response
382: builds an XML-RPC fault response.
383: If successful, it returns an instance of
384: .Fa structs_type_xmlrpc_response ,
385: i.e., a
386: .Li "struct xmlrpc_response_union" ,
387: in a memory block allocated with
388: .Xr typed_mem
389: type
390: .Fa mtype ,
391: which the caller is responsible for unintializing and freeing.
392: .Sh RETURN VALUES
393: The above functions indicate an error by returning either -1 or
394: .Dv NULL
395: and setting
396: .Va errno
397: to an appropriate value.
398: .Sh SEE ALSO
399: .Xr http_servlet_xmlrpc 3 ,
400: .Xr http_xml 3 ,
401: .Xr libpdel 3 ,
402: .Xr structs 3 ,
403: .Xr structs_type 3 ,
404: .Xr structs_xml_input 3 ,
405: .Xr typed_mem 3
406: .Rs
407: .%T "XML-RPC Home Page"
408: .%O "http://www.xmlrpc.org/"
409: .Re
410: .Sh HISTORY
411: The PDEL library was developed at Packet Design, LLC.
412: .Dv "http://www.packetdesign.com/"
413: .Sh AUTHORS
414: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs_xmlrpc.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