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

FreeBSD Manual Pages

  
 
  

home | help
HTTP_SERVLET_XML(3)    FreeBSD Library Functions Manual	   HTTP_SERVLET_XML(3)

NAME
     http_servlet_xml -- HTTP servlet for XML 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/xml.h>

     struct http_servlet *
     http_servlet_xml_create(const struct http_servlet_xml_info	*info,
	 void *arg, void (*destroy)(void *));

DESCRIPTION
     http_servlet_xml_create() creates a servlet that receives HTTP requests
     optionally	containing XML and sends back XML responses.  The request and
     response data are automatically converted to and from native binary for-
     mat using the structs(3) library.

     This servlet is basically acts as glue between the	http_servlet(3)	API
     and the structs_xml_input(3) and structs_xml_output(3) library routines.
     The net result is the ability to send and receive arbitrary data struc-
     tures between two machines	using XML over HTTP.

     The incoming HTTP request is expected to either be	a "GET"	or "POST", in
     the latter	case with a request body containing XML.  The incoming content
     type is ignored.  The response has	content	type "text/xml"	and contains
     XML.

     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_xml_info:

	typedef	void *http_servlet_xml_handler_t(void *arg,
			struct http_request *req, const	void *payload,
			const char *pattrs, char **rattrsp, const char *mtype);

	struct http_servlet_xml_info {
	    http_servlet_xml_handler_t	*handler;	/* user	handler	*/
	    const char			*ptag;		/* payload doc elem */
	    const struct structs_type	*ptype;		/* payload type	*/
	    const char			*rtag;		/* reply doc elem */
	    const struct structs_type	*rtype;		/* reply type */
	    u_char			allow_post;	/* allow POST */
	    u_char			allow_get;	/* allow GET */
	    http_logger_t		*logger;	/* loggging function */
	    int				flags;		/* output flags	*/
	};

     The handler is the	user routine invoked for each HTTP request (see	be-
     low).  ptag is the	XML document tag for incoming requests.	 ptype is the
     structs(3)	type for the payload data.  Incoming requests that don't match
     ptag and ptype are	rejected.

     Similarly,	rtag is	the XML	document tag for responses and rtype is	the
     structs(3)	type for the data returned by handler().

     The allow_post and	allow_get flags	select which of	"GET" and/or "POST"
     queries are allowed.  If allow_post is zero, then ptag and	ptype are ig-
     nored.

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

     flags controls how	XML responses are generated; this value	is passed un-
     altered to	structs_xml_output(3).

     When handler() is invoked,	arg is the opqaue cookie supplied to
     http_servlet_xml_create(),	and req	is the http_request(3) object.
     payload and pattrs	will be	NULL for a "GET" request, otherwise payload
     will point	to the received	data in	native binary format.  handler()
     should not	free this data.

     pattrs, if	not NULL, points to the	top level XML attributes in the	re-
     quest.  The attributes are	stored as a single sequence of concatenated
     pairs: name, '\0',	value, '\0', name, '\0', value,	etc., terminated with
     a final (extra) '\0'.

     If	top level XML attributes are desired in	the response, *rattrsp should
     be	set to a similarly concatenated	list of	name, value pairs allocated
     with typed_mem(3) type mtype.

     handler() should return a pointer to the reply data in native binary for-
     mat, in a region of memory	allocated with typed_mem(3) type mtype.	 If
     there was an error, handler() should return NULL and set errno appropri-
     ately.

     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.

RETURN VALUES
     On	failure, http_servlet_xml_create() returns NULL	and sets errno to an
     appropriate value.

SEE ALSO
     http_request(3), http_response(3),	http_server(3),	http_servlet(3),
     http_servlet_xmlrpc(3), http_xml(3), libpdel(3), structs(3), typed_mem(3)

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

AUTHORS
     Archie Cobbs <archie@freebsd.org>

BUGS
     http_servlet_xml_create() copies all information in info except the
     structs(3)	types pointed to by ptype and rtype, 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

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=http_servlet_xml&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help