Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  HTTP_SERVLET_XMLRPC (3)


http_servlet_xmlrpc - HTTP servlet for XML-RPC requests


     Returning Faults
     Working With Raw XML-RPC
Return Values
See Also


PDEL Library (libpdel, -lpdel)


.In sys/types.h
.In stdio.h
.In netinet/in.h
.In openssl/ssl.h
.In pdel/http/http_defs.h
.In pdel/http/http_server.h
.In pdel/http/servlet/xmlrpc.h struct http_servlet * http_servlet_xmlrpc_create const struct http_servlet_xmlrpc_info *info void *arg void (*destroy)(void *)


http_servlet_xmlrpc_create creates a new servlet that handles XML-RPC HTTP requests. The request and response data are automatically converted to and from native binary format using the structs(3) library.

The arg is an opaque user cookie. When the servlet is destroyed, if destroy is not NULL, it will be invoked with arg as its parameter. info is a pointer to a struct http_servlet_xmlrpc_info, which contains a pointer to an array of http_servlet_xmlrpc_method structures:

struct http_servlet_xmlrpc_method {
    const char                    *name;         /* method name */
    http_servlet_xmlrpc_handler_t *handler;      /* method handler */
    const struct structs_type     **ptypes;      /* parameter types */
    u_int                         min_params;    /* min # params */
    u_int                         max_params;    /* max # params */

struct http_servlet_xmlrpc_info { const struct http_servlet_xmlrpc_method *methods; /* methods */ http_logger_t *logger; /* loggging function */ };

The methods field points to the method descriptor array, which is terminated with an entry having a NULL name.

The logger is a logging function whose type is defined in http_server(3).

Each element in the methods array describes one supported XML-RPC method: name is the method name; min_params and max_params specify the minimum and maximum number of parameters allowed for the method (the servlet itself enforces these limits); and ptypes points to an array of structs(3) types that has length max_params, one for each possible parameter.

The handler is a pointer to the user function that implements the XML-RPC method. The function must be of this type:

typedef void *http_servlet_xmlrpc_handler_t(void *arg,
               const char *method, struct http_request *req,
               u_int nparams, const void **params, const char *mtype,
               const struct structs_type **rtypep, int *faulted)

The arg is the opqaue cookie supplied to http_servlet_xmlrpc_create; method is the XML-RPC method name; req is the HTTP request object; and params points to an array of nparams pointers to the XML-RPC request parameters in native binary format. handler should not free the parameters.

If successful, handler should allocate a region of memory with typed_mem(3) type mtype, initialize it with the response value in native binary format, and return a pointer to it. The structs(3) type of the returned memory region must be stored in *rtypep.

Since it’s running as a servlet, the thread executing handler may be canceled at any cancellation point. handler should be written so as to not leak resources if this happens.

    Returning Faults

If handler wishes to return an XML-RPC fault, it should set *faulted to one, return a pointer to a struct structs_xmlrpc_fault structure, and set *rtypep to &structs_type_xmlrpc_fault.

handler may also return NULL and set errno, in which case an XML-RPC fault will be created using errno as the fault code and strerror errno as the fault string.

    Working With Raw XML-RPC

In some cases, the types of the XML-RPC parameters are not known ahead of time, or it may be inconvenient to have to provide a structs(3) type for the returned value. In these situations, handler can operate with the XML-RPC parameters and/or response values in their raw, "exploded" forms.

If ptypes is NULL, then all of the parameters passed to handler via params are instances of the structs(3) type structs_type_xmlrpc_value, i.e., every parameter is a struct xmlrpc_value_union, defined in <pdel/structs/xmlrpc.h>.

If handler returns a non-NULL result but sets *rtypep to NULL, then the returned result is assumed to be an instance of the structs(3) type structs_type_xmlrpc_value, i.e., a struct xmlrpc_value_union.

Finally, if the method names themselves are not known ahead of time, a name equal to the empty string will match all method names. Such an entry acts as a "catch all" and must be last in the methods list.


On failure, http_servlet_xmlrpc_create returns NULL and sets errno to an appropriate value.


http_request(3), http_response(3), http_server(3), http_servlet(3), http_servlet_xml(3), http_xml(3), libpdel(3), structs(3), structs_xmlrpc(3), typed_mem(3)
.Rs XML-RPC Home Page


The PDEL library was developed at Packet Design, LLC.


.An Archie Cobbs Aq


http_servlet_xmlrpc_create copies all information in info except each method’s parameter structs(3) types (pointed to by the elements of the ptypes array), so these must remain valid for the lifetime of the servlet. Typically structs(3) types are stored in static variables, so this is not usually a problem.
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.