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

FreeBSD Manual Pages

  
 
  

home | help
STRUCTS_XMLRPC(3)      FreeBSD 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 usually
     work with compact (or native C) types, i.e., where	XML-RPC	i32's are rep-
     resented by C int32_t's, XML-RPC struct's are represented by C struc-
     tures, and	so on.	In order to convert between native data	structures and
     XML-RPC, intermediate "exploded" types are	used.  This man	page describes
     structs(3)	types for the exploded XML-RPC data structures 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 include
     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 exploded
     XML-RPC structure member, i.e., a struct xmlrpc_member.

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

     structs_type_xmlrpc_request is a structs(3) type representing an exploded
     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) instance
     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 in-
     stance 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 ini-
     tialized, 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 hav-
     ing 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	call-
     ing structs_set_string(3).	 There is no checking that the XML-RPC tag is
     consistent	with the primitive structs type; i.e., if the primitive	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 speci-
     fied 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 values,
     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 responsi-
     ble 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	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=structs_type_xmlrpc_value&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help