Annotation of embedaddon/libpdel/http/servlet/http_servlet_tmpl.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_tmpl.3,v 1.13 2004/06/02 17:24:37 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt HTTP_SERVLET_TMPL 3
42: .Os
43: .Sh NAME
44: .Nm http_servlet_tmpl
45: .Nd HTTP servlet for template files
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/tmpl/tmpl.h
54: .In pdel/http/http_defs.h
55: .In pdel/http/http_server.h
56: .In pdel/http/servlet/tmpl.h
57: .Ft "struct http_servlet *"
58: .Fn http_servlet_tmpl_create "struct http_servlet_tmpl_info *info"
59: .Vt extern tmpl_handler_t http_servlet_tmpl_func_query ;
60: .Vt extern tmpl_handler_t http_servlet_tmpl_func_query_exists ;
61: .Vt extern tmpl_handler_t http_servlet_tmpl_func_query_string ;
62: .Vt extern tmpl_handler_t http_servlet_tmpl_func_get_header ;
63: .Vt extern tmpl_handler_t http_servlet_tmpl_func_set_header ;
64: .Vt extern tmpl_handler_t http_servlet_tmpl_func_remove_header ;
65: .Vt extern tmpl_handler_t http_servlet_tmpl_func_redirect ;
66: .Vt extern tmpl_handler_t http_servlet_tmpl_func_unbuffer ;
67: .Sh DESCRIPTION
68: .Fn http_servlet_tmpl_create
69: creates a new servlet that serves HTTP requests by executing a
70: .Xr tmpl 3
71: template file.
72: The output of the template is sent as the body of the HTTP response.
73: By default, the template output is buffered in memory and after
74: template execution has finished the HTTP response is sent.
75: .Pp
76: .Fa info
77: is a pointer to a
78: .Li "struct http_servlet_tmpl_info" ,
79: which contains a
80: .Li "struct http_servlet_tmpl_tinfo" :
81: .Pp
82: .Bd -literal -compact -offset 3n
83: /* Function to free user 'arg' */
84: typedef void http_servlet_tmpl_free_t(void *arg);
85:
86: /* Information required by tmpl(3) library */
87: struct http_servlet_tmpl_tinfo {
88: int flags; /* tmpl_execute() flags */
89: const char *mtype; /* tmpl string mem type */
90: tmpl_handler_t *handler; /* tmpl function handler */
91: tmpl_errfmtr_t *errfmtr; /* tmpl error formatter */
92: void *arg; /* opaque argument */
93: http_servlet_tmpl_free_t *freer; /* destructor for 'arg' */
94: };
95:
96: /* Information required for the tmpl servlet */
97: struct http_servlet_tmpl_info {
98: const char *path; /* template file */
99: const char *mime_type; /* default mime type */
100: const char *mime_encoding; /* default mime encoding */
101: http_logger_t *logger; /* http error logger */
102: struct http_servlet_tmpl_tinfo tinfo; /* info for tmpl(3) */
103: };
104: .Ed
105: .Pp
106: .Fa path
107: is the pathname of the template file.
108: The file is parsed when the servlet is first executed, and the parsed
109: template is cached for use by subsequent servlet invocations.
110: If the file modification timestamp changes, the file is parsed again.
111: .Pp
112: .Fa mime_type
113: and
114: .Fa mime_encoding
115: specify the default MIME type and encoding for the template output.
116: The template itself may change the MIME type however.
117: If
118: .Fa mime_type
119: is
120: .Dv NULL ,
121: "text/html; charset=iso-8859-1" is used.
122: .Pp
123: The
124: .Fa logger
125: is a logging function whose type is defined in
126: .Xr http_server 3 .
127: .Pp
128: The
129: .Fa tinfo
130: structure provides information required by the
131: .Xr tmpl 3
132: library in order to create and execute the template.
133: The
134: .Fa mtype ,
135: .Fa handler ,
136: and
137: .Fa errfmtr
138: fields are passed to
139: .Fn tmpl_ctx_create ;
140: The
141: .Fa flags
142: field is passed to
143: .Fn tmpl_execute .
144: .Pp
145: The
146: .Fa arg
147: field is copied into a
148: .Li "struct http_servlet_tmpl_arg" ,
149: and a pointer to this structure is used as the user cookie field
150: .Fa arg
151: passed to
152: .Fn tmpl_ctx_create :
153: .Pp
154: .Bd -literal -compact -offset 3n
155: struct http_servlet_tmpl_arg {
156: void *arg; /* arg from 'tinfo' */
157: struct http_request *req; /* http request */
158: struct http_response *resp; /* http response */
159: };
160: .Ed
161: .Pp
162: Therefore, by casting the pointer returned from
163: .Fn tmpl_ctx_get_arg
164: to a
165: .Li "struct http_servlet_tmpl_arg *" ,
166: .Fn handler
167: can access both the original
168: .Fa arg
169: as well as the HTTP request and response objects.
170: .Pp
171: For an HTTP POST with MIME type
172: .Dq application/x-www-form-urlencoded
173: the servlet will automatically read in the URL-encoded name, value pairs,
174: making them accessible via
175: .Xr http_request_get_value 3
176: (see also
177: .Fn http_servlet_tmpl_func_query
178: below).
179: .Pp
180: When the servlet is destroyed, if the
181: .Fa freer
182: field is not
183: .Dv NULL ,
184: it is invoked to release resources associated with
185: .Fa arg .
186: .\"
187: .Ss Built-in template functions
188: .\"
189: The
190: .Nm http_servlet_tmpl
191: servlet includes the following built-in
192: .Xr tmpl 3
193: user functions.
194: These functions all assume the
195: .Xr tmpl 3
196: user cookie is a
197: .Li "struct http_servlet_tmpl_arg *".
198: .Pp
199: .Bl -hang -offset 3n -width 3n
200: .It Fn http_servlet_tmpl_func_query
201: This function takes exactly one argument, which is the name of a field
202: in an HTML form, and returns the value of that field as submitted by
203: the remote client.
204: This function works for both GET and POST form submissions.
205: If no such field was submitted, the empty string is returned.
206: .It Fn http_servlet_tmpl_func_query_exists
207: This function takes exactly one argument, which is the name of a field
208: in an HTML form, and returns "1" or "0" depending on whether a field
209: having that name was submitted by the client.
210: .It Fn http_servlet_tmpl_func_query_string
211: Takes zero arguments. Returns the HTTP query string.
212: .It Fn http_servlet_tmpl_func_get_header
213: Takes one argument, and returns the contents of the HTTP header having
214: that name.
215: .It Fn http_servlet_tmpl_func_set_header
216: Takes two arguments, the name of an HTTP header and its value, and
217: sets the corresponding HTTP response header.
218: This function has no effect if the headers have already been sent.
219: .It Fn http_servlet_tmpl_func_remove_header
220: Takes one argument, the name of an HTTP header, and removes the
221: corresponding HTTP response header.
222: This function has no effect if the headers have already been sent.
223: .It Fn http_servlet_tmpl_func_redirect
224: Takes one argument, which must be a valid URL.
225: Forces an HTTP redirect response to the URL.
226: This function only works if the servlet has not created any output yet.
227: .It Fn http_servlet_tmpl_func_unbuffer
228: Takes zero arguments.
229: Unbuffers the servlet output, so that the output is written
230: directly to the network instead of first into a memory buffer.
231: This is done by calling
232: .Xr http_response_send_headers 3
233: with a non-zero
234: .Fa unbuffer
235: argument.
236: This function should be called in servlets that produce a high
237: volume of output.
238: You can't modify the HTTP response headers once this has been called.
239: .El
240: .Pp
241: The
242: .Nm http_servlet_tmpl
243: servlet by default buffers the entire template output
244: to facilitate HTTP keep-alive.
245: For templates that generate voluminous output, this could consume
246: excessive memory.
247: The solution is to implement a template function using
248: .Fn http_servlet_tmpl_func_unbuffer
249: and invoke this function within those templates.
250: .Sh IMPLEMENTATION NOTES
251: Multiple instances of the same
252: .Nm http_servlet_tmpl
253: servlet may be executing at the same time.
254: Therefore, any user-supplied template functions called must
255: be thread-safe.
256: .Pp
257: Since it's running as a servlet, the thread executing
258: .Fn handler
259: and
260: .Fn errfmtr
261: may be canceled at any cancellation point.
262: Therefore, these functions should be written so as to not leak
263: resources if this happens.
264: .Sh RETURN VALUES
265: On failure,
266: .Fn http_servlet_tmpl_create
267: returns
268: .Dv NULL
269: and sets
270: .Va errno
271: to an appropriate value.
272: .Pp
273: The built-in
274: .Xr tmpl 3
275: user functions return
276: .Dv NULL
277: with
278: .Va errno
279: set to
280: .Er EINVAL
281: if the wrong number of arguments is passed.
282: They may also return
283: .Dv NULL
284: with
285: .Va errno
286: set as a result of other system errors.
287: .Sh SEE ALSO
288: .Xr http_request 3 ,
289: .Xr http_response 3 ,
290: .Xr http_server 3 ,
291: .Xr http_servlet 3 ,
292: .Xr libpdel 3 ,
293: .Xr tmpl 3
294: .Sh HISTORY
295: The PDEL library was developed at Packet Design, LLC.
296: .Dv "http://www.packetdesign.com/"
297: .Sh AUTHORS
298: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet_tmpl.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