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

FreeBSD Manual Pages


home | help

     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 termi-
     nated 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 it-
     self 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 pa-
     rameters in native	binary format.	handler() should not free the parame-

     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

     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 en-
     try 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,

     The PDEL library was developed at Packet Design, LLC.

     Archie Cobbs <>

     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.

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help