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

FreeBSD Manual Pages

  
 
  

home | help 
HTTP_SERVLET_XML(3)	    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
       format 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  rou-
       tines.	The  net  result  is the ability to send and receive arbitrary
       data structures 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
       ignored.

       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
       unaltered 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 al-
       located with typed_mem(3) type mtype.

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

       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	ports 15.0		April 22, 2002		   HTTP_SERVLET_XML(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_servlet_xml_create&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help