http_servlet_xml
—
HTTP servlet for XML 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/xml.h>
struct http_servlet *
http_servlet_xml_create
(
const
struct http_servlet_xml_info *info,
void *arg,
void (*destroy)(void
*));
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 routines. 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 below).
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 request. 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 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 appropriately.
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.
On failure,
http_servlet_xml_create
() returns
NULL
and sets
errno to an appropriate value.
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)
The PDEL library was developed at Packet Design, LLC.
http://www.packetdesign.com/
Archie Cobbs
⟨archie@freebsd.org⟩
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.