Annotation of embedaddon/libpdel/http/servlet/http_servlet_xml.3, revision 1.1.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