Annotation of embedaddon/libpdel/http/servlet/http_servlet_tmpl.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_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