Annotation of embedaddon/libpdel/http/servlet/http_servlet_xml.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: http_servlet_xml.3,v 1.14 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_SERVLET_XML 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_servlet_xml
! 45: .Nd HTTP servlet for XML requests
! 46: .Sh LIBRARY
! 47: PDEL Library (libpdel, \-lpdel)
! 48: .Sh SYNOPSIS
! 49: .In sys/types.h
! 50: .In stdio.h
! 51: .In netinet/in.h
! 52: .In openssl/ssl.h
! 53: .In pdel/http/http_defs.h
! 54: .In pdel/http/http_server.h
! 55: .In pdel/http/servlet/xml.h
! 56: .Ft "struct http_servlet *"
! 57: .Fn http_servlet_xml_create "const struct http_servlet_xml_info *info" "void *arg" "void (*destroy)(void *)"
! 58: .Sh DESCRIPTION
! 59: .Fn http_servlet_xml_create
! 60: creates a servlet that receives HTTP requests optionally containing XML
! 61: and sends back XML responses.
! 62: The request and response data are automatically converted to and
! 63: from native binary format using the
! 64: .Xr structs 3
! 65: library.
! 66: .Pp
! 67: This servlet is basically acts as glue between the
! 68: .Xr http_servlet 3
! 69: API and the
! 70: .Xr structs_xml_input 3
! 71: and
! 72: .Xr structs_xml_output 3
! 73: library routines.
! 74: The net result is the ability to send and receive arbitrary data
! 75: structures between two machines using XML over HTTP.
! 76: .Pp
! 77: The incoming HTTP request is expected to either be a
! 78: .Dq GET
! 79: or
! 80: .Dq POST ,
! 81: in the latter case with a request body containing XML.
! 82: The incoming content type is ignored.
! 83: The response has content type
! 84: .Dq text/xml
! 85: and contains XML.
! 86: .Pp
! 87: The
! 88: .Fa arg
! 89: is an opaque user cookie.
! 90: When the servlet is destroyed, if
! 91: .Fa destroy
! 92: is not
! 93: .Dv NULL ,
! 94: it will be invoked with
! 95: .Fa arg
! 96: as its parameter.
! 97: .Pp
! 98: .Fa info
! 99: is a pointer to a
! 100: .Li "struct http_servlet_xml_info" :
! 101: .Pp
! 102: .Bd -literal -compact -offset 3n
! 103: typedef void *http_servlet_xml_handler_t(void *arg,
! 104: struct http_request *req, const void *payload,
! 105: const char *pattrs, char **rattrsp, const char *mtype);
! 106:
! 107: struct http_servlet_xml_info {
! 108: http_servlet_xml_handler_t *handler; /* user handler */
! 109: const char *ptag; /* payload doc elem */
! 110: const struct structs_type *ptype; /* payload type */
! 111: const char *rtag; /* reply doc elem */
! 112: const struct structs_type *rtype; /* reply type */
! 113: u_char allow_post; /* allow POST */
! 114: u_char allow_get; /* allow GET */
! 115: http_logger_t *logger; /* loggging function */
! 116: int flags; /* output flags */
! 117: };
! 118: .Ed
! 119: .Pp
! 120: The
! 121: .Fa handler
! 122: is the user routine invoked for each HTTP request (see below).
! 123: .Fa ptag
! 124: is the XML document tag for incoming requests.
! 125: .Fa ptype
! 126: is the
! 127: .Xr structs 3
! 128: type for the payload data.
! 129: Incoming requests that don't match
! 130: .Fa ptag
! 131: and
! 132: .Fa ptype
! 133: are rejected.
! 134: .Pp
! 135: Similarly,
! 136: .Fa rtag
! 137: is the XML document tag for responses and
! 138: .Fa rtype
! 139: is the
! 140: .Xr structs 3
! 141: type for the data returned by
! 142: .Fn handler .
! 143: .Pp
! 144: The
! 145: .Fa allow_post
! 146: and
! 147: .Fa allow_get
! 148: flags select which of
! 149: .Dq GET
! 150: and/or
! 151: .Dq POST
! 152: queries are allowed.
! 153: If
! 154: .Fa allow_post
! 155: is zero, then
! 156: .Fa ptag
! 157: and
! 158: .Fa ptype
! 159: are ignored.
! 160: .Pp
! 161: The
! 162: .Fa logger
! 163: is a logging function whose type is defined in
! 164: .Xr http_server 3 .
! 165: .Pp
! 166: .Fa flags
! 167: controls how XML responses are generated; this value is passed unaltered to
! 168: .Xr structs_xml_output 3 .
! 169: .Pp
! 170: When
! 171: .Fn handler
! 172: is invoked,
! 173: .Fa arg
! 174: is the opqaue cookie supplied to
! 175: .Fn http_servlet_xml_create ,
! 176: and
! 177: .Fa req
! 178: is the
! 179: .Xr http_request 3
! 180: object.
! 181: .Fa payload
! 182: and
! 183: .Fa pattrs
! 184: will be
! 185: .Dv NULL
! 186: for a
! 187: .Dq GET
! 188: request, otherwise
! 189: .Fa payload
! 190: will point to the received data in native binary format.
! 191: .Fn handler
! 192: should not free this data.
! 193: .Pp
! 194: .Fa pattrs ,
! 195: if not
! 196: .Dv NULL ,
! 197: points to the top level XML attributes in the request.
! 198: The attributes are stored as a single sequence of concatenated pairs:
! 199: name, '\\0', value, '\\0', name, '\\0', value, etc., terminated with a
! 200: final (extra) '\\0'.
! 201: .Pp
! 202: If top level XML attributes are desired in the response,
! 203: .Fa "*rattrsp"
! 204: should be set to a similarly concatenated list of name, value pairs
! 205: allocated with
! 206: .Xr typed_mem 3
! 207: type
! 208: .Fa mtype .
! 209: .Pp
! 210: .Fn handler
! 211: should return a pointer to the reply data in native binary format,
! 212: in a region of memory allocated with
! 213: .Xr typed_mem 3
! 214: type
! 215: .Fa mtype .
! 216: If there was an error,
! 217: .Fn handler
! 218: should return
! 219: .Dv NULL
! 220: and set
! 221: .Va errno
! 222: appropriately.
! 223: .Pp
! 224: Since it's running as a servlet, the thread executing
! 225: .Fn handler
! 226: may be canceled at any cancellation point.
! 227: .Fn handler
! 228: should be written so as to not leak resources if this happens.
! 229: .Sh RETURN VALUES
! 230: On failure,
! 231: .Fn http_servlet_xml_create
! 232: returns
! 233: .Dv NULL
! 234: and sets
! 235: .Va errno
! 236: to an appropriate value.
! 237: .Sh SEE ALSO
! 238: .Xr http_request 3 ,
! 239: .Xr http_response 3 ,
! 240: .Xr http_server 3 ,
! 241: .Xr http_servlet 3 ,
! 242: .Xr http_servlet_xmlrpc 3 ,
! 243: .Xr http_xml 3 ,
! 244: .Xr libpdel 3 ,
! 245: .Xr structs 3 ,
! 246: .Xr typed_mem 3
! 247: .Sh HISTORY
! 248: The PDEL library was developed at Packet Design, LLC.
! 249: .Dv "http://www.packetdesign.com/"
! 250: .Sh AUTHORS
! 251: .An Archie Cobbs Aq archie@freebsd.org
! 252: .Sh BUGS
! 253: .Fn http_servlet_xml_create
! 254: copies all information in
! 255: .Fa info
! 256: except the
! 257: .Xr structs 3
! 258: types pointed to by
! 259: .Fa ptype
! 260: and
! 261: .Fa rtype ,
! 262: so these must remain valid for the lifetime of the servlet.
! 263: Typically
! 264: .Xr structs 3
! 265: types are stored in static variables, so this is not usually a problem.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet_xml.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http / servlet