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
HTTP_SERVLET_XMLRPC(3) FreeBSD Library Functions Manual HTTP_SERVLET_XMLRPC(3)

http_servlet_xmlrpc
HTTP servlet for XML-RPC requests

PDEL Library (libpdel, -lpdel)

#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 *));

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.

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.

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)

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

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

Archie Cobbs ⟨archie@freebsd.org⟩

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.
April 22, 2002 FreeBSD 13.1-RELEASE

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 ManDoc.