GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRUCTS_XMLRPC (3)

NAME

structs_xmlrpc - structs support for XML-RPC

CONTENTS

Library
Synopsis
Description
     Compact and Exploded Types
     Conversion Routines
     XML-RPC Requests and Responses
Return Values
See Also
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In pdel/structs/structs.h
.In pdel/structs/type/array.h
.In pdel/structs/type/union.h
.In 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
.Vt extern const struct structs_type structs_type_xmlrpc_value ;
.Vt extern const struct structs_type structs_type_xmlrpc_array ;
.Vt extern const struct structs_type structs_type_xmlrpc_member ;
.Vt extern const struct structs_type structs_type_xmlrpc_struct ;
.Vt extern const struct structs_type structs_type_xmlrpc_request ;
.Vt extern const struct structs_type structs_type_xmlrpc_response ;
.Vt extern const struct structs_type structs_type_xmlrpc_fault ;
.Vt 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 describe 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 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 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 exploded 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 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 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 specified 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 responsible for unintializing and freeing.

structs_xmlrpc_build_response creates an XML-RPC response. The response 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)
.Rs XML-RPC Home Page
.Re

HISTORY

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

AUTHORS


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.