Return to structs_xmlrpc.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / structs

libpdel

    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.1.1.1 2012/02/21 23:25:53 misho 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