Annotation of embedaddon/libpdel/structs/structs_xmlrpc.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_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