Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
STRUCTS_XMLRPC(3)	    Library Functions Manual	     STRUCTS_XMLRPC(3)

NAME
       structs_xmlrpc -- structs support for XML-RPC

LIBRARY
       PDEL Library (libpdel, -lpdel)

SYNOPSIS
       #include	<sys/types.h>
       #include	<pdel/structs/structs.h>
       #include	<pdel/structs/type/array.h>
       #include	<pdel/structs/type/union.h>
       #include	<pdel/structs/xmlrpc.h>

       int
       structs_struct2xmlrpc(const	 struct	      structs_type	*type,
	   const       void	  *data,       const	   char	       *sname,
	   const struct	structs_type *xtype, void *xdata, const	char *xname);

       int
       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);

       struct xmlrpc_request *
       structs_xmlrpc_build_request(const char *mtype, const char *methodName,
	   u_int    nparams,	const	  struct     structs_type     **types,
	   const void **params);

       struct xmlrpc_response_union *
       structs_xmlrpc_build_response(const	       char	       *mtype,
	   const struct	structs_type *type, const void *data);

       struct xmlrpc_response_union *
       structs_xmlrpc_build_fault_response(const	 char	       *mtype,
	   const struct	xmlrpc_compact_fault *fault);

       extern const struct structs_type	structs_type_xmlrpc_value;
       extern const struct structs_type	structs_type_xmlrpc_array;
       extern const struct structs_type	structs_type_xmlrpc_member;
       extern const struct structs_type	structs_type_xmlrpc_struct;
       extern const struct structs_type	structs_type_xmlrpc_request;
       extern const struct structs_type	structs_type_xmlrpc_response;
       extern const struct structs_type	structs_type_xmlrpc_fault;
       extern const struct structs_type	structs_type_xmlrpc_compact_fault;

DESCRIPTION
       These functions and structs(3) types provide support for	XML-RPC, i.e.,
       conversion between XML-RPC values and native C data types.

   Compact and Exploded	Types
       For any XML-RPC data structure, there are two structs(3)	types that de-
       scribe  it: a "compact" type and	an "exploded" type.  Applications usu-
       ally work with compact (or native C) types, i.e., where	XML-RPC	 i32's
       are  represented	 by C int32_t's, XML-RPC struct's are represented by C
       structures, and so on.  In order	to convert between native data	struc-
       tures  and  XML-RPC,  intermediate "exploded" types are used.  This man
       page describes structs(3) types for the exploded	 XML-RPC  data	struc-
       tures and functions to convert between the compact and exploded forms.

       That  is,  XML-RPC is just a special case of structs(3) types converted
       into XML	with lots of extra nesting so that a fixed set of XML tags may
       be used.	 The exploded types are	simply the structs(3) types  that  in-
       clude  the  extra nesting so that when they are converted to XML	in the
       normal fashion (see structs_xml_output(3)), the result is a well-formed
       XML-RPC request or response.

       The following types data	structures are	defined	 in  the  header  file
       <pdel/structs/xmlrpc.h>:

       structs_type_xmlrpc_value is a structs(3) type representing an exploded
       XML-RPC value, i.e., a struct xmlrpc_value_union.

       structs_type_xmlrpc_array is a structs(3) type representing an exploded
       XML-RPC array, i.e., a struct xmlrpc_array.

       structs_type_xmlrpc_member  is  a  structs(3)  type representing	an ex-
       ploded XML-RPC structure	member,	i.e., a	struct xmlrpc_member.

       structs_type_xmlrpc_struct is a structs(3)  type	 representing  an  ex-
       ploded XML-RPC structure, i.e., a struct	xmlrpc_struct.

       structs_type_xmlrpc_request  is	a  structs(3) type representing	an ex-
       ploded XML-RPC request, i.e., a struct xmlrpc_request.

       structs_type_xmlrpc_response is a structs(3) type representing  an  ex-
       ploded XML-RPC response,	i.e., a	struct xmlrpc_response_union.

       structs_type_xmlrpc_fault is a structs(3) type representing an exploded
       XML-RPC fault, i.e., a struct xmlrpc_fault.

       structs_type_xmlrpc_compact_fault  is a structs(3) type representing an
       XML-RPC fault in	a compact form,	i.e., a	struct xmlrpc_compact_fault:

	  struct xmlrpc_compact_fault {
	      int32_t	  faultCode;	  /* XML-RPC fault code	*/
	      char	  *faultString;	  /* XML-RPC fault string */
	  };

   Conversion Routines
       structs_struct2xmlrpc() converts	an arbitrary  compact  structs(3)  in-
       stance  into an "exploded" XML-RPC value.  The original instance	should
       be pointed to by	data and have structs(3) type type, while the  XML-RPC
       instance	 should	be pointed to by xdata and have	structs(3) type	xtype.
       sname and xname may be non- NULL	to name	specific  sub-fields  of  data
       and  xdata,  respectively, to convert.  The xdata instance must already
       be initialized, and the sub-field of xdata specified by xname must have
       type   structs_type_xmlrpc_value,   i.e.,   it	must   be   a	struct
       xmlrpc_value_union.

       The  following  primitive  structs(3) types are specially recognized by
       structs_struct2xmlrpc():

	     structs_type_int32, and structs_type_int when sizeof(int) == 4
		    Converted to <i4>.

	     structs_type_boolean and all variants
		    Converted to <boolean>.

	     structs_type_float
		    Converted to <double>.

	     structs_type_double
		    Converted to <double>.

	     structs_type_time_iso8601
		    Converted to <dateTime.iso8601>.

	     structs_type_data or any variant using the	default	character set
		    Converted to <base64>.

	     Variable and fixed	length array types
		    Converted to <array>.

	     Structure types
		    Converted to <struct>.

	     Union types
		    Converted to <struct>.

       All other primitive types are converted to XML-RPC <string>'s.

       structs_xmlrpc2struct() converts	an XML-RPC value back into a "compact"
       data structure, essentially the reverse of structs_struct2xmlrpc().  As
       before, xname, xdata, and xtype describe	the XML-RPC value  and	sname,
       data, and type describe the normal, native instance.  The data instance
       must already be initialized.  The sub-field of xdata specified by xname
       must  have  type	 structs_type_xmlrpc_value,  i.e., it must be a	struct
       xmlrpc_value_union.  In addition, an error buffer pointed  to  by  ebuf
       having  size  emax may be provided; if so, any errors from the decoding
       will be written into it.

       Scalar XML-RPC values are converted  into  primitive  types  by	simply
       calling	structs_set_string(3).	 There is no checking that the XML-RPC
       tag is consistent with the primitive structs type; i.e.,	if the	primi-
       tive type successfully parses the string, then it's assumed to be OK.

       Array XML-RPC values are	converted into array types.  Structure XML-RPC
       values  are converted into structure types or union types, depending on
       the destination type provided.  In the union case, the last field spec-
       ified in	the XML-RPC structure is chosen	for the	union.	 Other	fields
       specified must be valid for the union, but are otherwise	ignored.

   XML-RPC Requests and	Responses
       structs_xmlrpc_build_request() creates an XML-RPC request instance from
       native, "compact" parameter data	structures.  methodName	is the XML-RPC
       request	method name.  There will be nparams parameters in the request;
       types must point	to an array of nparams structs(3) parameter types  and
       params  an  array  of nparams parameter values having the corresponding
       types.

       To build	the request directly out of "exploded" XML-RPC parameter  val-
       ues, set	types to NULL.	Then it	will be	assumed	that each parameter in
       the  params  array is an	instance of structs_type_xmlrpc_value, i.e., a
       struct xmlrpc_value_union.

       If successful, structs_xmlrpc_build_request() returns  an  instance  of
       type  structs_type_xmlrpc_request,  i.e., a struct xmlrpc_request, in a
       memory block allocated with typed_mem type mtype, which the  caller  is
       responsible for unintializing and freeing.

       structs_xmlrpc_build_response()	creates	 an XML-RPC response.  The re-
       sponse data structure (i.e., the	XML-RPC	return value)  pointed	to  by
       data should be "compact"	and have structs(3) type type.

       To  directly send an "exploded" XML-RPC return value, set type to NULL.
       Then  it	 will  be  assumed  that  data	points	to  an	 instance   of
       structs_type_xmlrpc_value, i.e.,	a struct xmlrpc_value_union.

       If  successful,	structs_xmlrpc_build_response()	returns	an instance of
       type	 structs_type_xmlrpc_response,	    i.e.,	a	struct
       xmlrpc_response_union,  in a memory block allocated with	typed_mem type
       mtype, which the	caller is responsible for unintializing	and freeing.

       structs_xmlrpc_build_fault_response() builds an XML-RPC fault response.
       If successful, it returns an instance of	 structs_type_xmlrpc_response,
       i.e.,  a	struct xmlrpc_response_union, in a memory block	allocated with
       typed_mem type mtype, which the caller is responsible for unintializing
       and freeing.

RETURN VALUES
       The above functions indicate an error by	returning either  -1  or  NULL
       and setting errno to an appropriate value.

SEE ALSO
       http_servlet_xmlrpc(3),	   http_xml(3),	    libpdel(3),	   structs(3),
       structs_type(3),	structs_xml_input(3), typed_mem(3)

       XML-RPC Home Page, http://www.xmlrpc.org/.

HISTORY
       The   PDEL   library   was   developed	at   Packet    Design,	  LLC.
       http://www.packetdesign.com/

AUTHORS
       Archie Cobbs <archie@freebsd.org>

FreeBSD	ports 15.0		April 22, 2002		     STRUCTS_XMLRPC(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=structs_xmlrpc_build_response&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help