NAME

http_servlet_xmlrpc — HTTP servlet for XML-RPC requests

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS

#include <sys/types.h>
#include <stdio.h>
#include <netinet/in.h>
#include <openssl/ssl.h>
#include <pdel/http/http_defs.h>
#include <pdel/http/http_server.h>
#include <pdel/http/servlet/xmlrpc.h>

struct http_servlet *
http_servlet_xmlrpc_create(const struct http_servlet_xmlrpc_info *info, void *arg, void (*destroy)(void *));

DESCRIPTION

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 xmlrpc_compact_fault structure, and set *rtypep to &structs_type_xmlrpc_compact_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.

RETURN VALUES

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

HISTORY

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

AUTHORS

Archie Cobbs ⟨archie@freebsd.org⟩

BUGS

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.