.\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Id: http_servlet_tmpl.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $ .\" .Dd April 22, 2002 .Dt HTTP_SERVLET_TMPL 3 .Os .Sh NAME .Nm http_servlet_tmpl .Nd HTTP servlet for template files .Sh LIBRARY PDEL Library (libpdel, \-lpdel) .Sh SYNOPSIS .In sys/types.h .In stdio.h .In netinet/in.h .In openssl/ssl.h .In pdel/tmpl/tmpl.h .In pdel/http/http_defs.h .In pdel/http/http_server.h .In pdel/http/servlet/tmpl.h .Ft "struct http_servlet *" .Fn http_servlet_tmpl_create "struct http_servlet_tmpl_info *info" .Vt extern tmpl_handler_t http_servlet_tmpl_func_query ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_query_exists ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_query_string ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_get_header ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_set_header ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_remove_header ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_redirect ; .Vt extern tmpl_handler_t http_servlet_tmpl_func_unbuffer ; .Sh DESCRIPTION .Fn http_servlet_tmpl_create creates a new servlet that serves HTTP requests by executing a .Xr tmpl 3 template file. The output of the template is sent as the body of the HTTP response. By default, the template output is buffered in memory and after template execution has finished the HTTP response is sent. .Pp .Fa info is a pointer to a .Li "struct http_servlet_tmpl_info" , which contains a .Li "struct http_servlet_tmpl_tinfo" : .Pp .Bd -literal -compact -offset 3n /* Function to free user 'arg' */ typedef void http_servlet_tmpl_free_t(void *arg); /* Information required by tmpl(3) library */ struct http_servlet_tmpl_tinfo { int flags; /* tmpl_execute() flags */ const char *mtype; /* tmpl string mem type */ tmpl_handler_t *handler; /* tmpl function handler */ tmpl_errfmtr_t *errfmtr; /* tmpl error formatter */ void *arg; /* opaque argument */ http_servlet_tmpl_free_t *freer; /* destructor for 'arg' */ }; /* Information required for the tmpl servlet */ struct http_servlet_tmpl_info { const char *path; /* template file */ const char *mime_type; /* default mime type */ const char *mime_encoding; /* default mime encoding */ http_logger_t *logger; /* http error logger */ struct http_servlet_tmpl_tinfo tinfo; /* info for tmpl(3) */ }; .Ed .Pp .Fa path is the pathname of the template file. The file is parsed when the servlet is first executed, and the parsed template is cached for use by subsequent servlet invocations. If the file modification timestamp changes, the file is parsed again. .Pp .Fa mime_type and .Fa mime_encoding specify the default MIME type and encoding for the template output. The template itself may change the MIME type however. If .Fa mime_type is .Dv NULL , "text/html; charset=iso-8859-1" is used. .Pp The .Fa logger is a logging function whose type is defined in .Xr http_server 3 . .Pp The .Fa tinfo structure provides information required by the .Xr tmpl 3 library in order to create and execute the template. The .Fa mtype , .Fa handler , and .Fa errfmtr fields are passed to .Fn tmpl_ctx_create ; The .Fa flags field is passed to .Fn tmpl_execute . .Pp The .Fa arg field is copied into a .Li "struct http_servlet_tmpl_arg" , and a pointer to this structure is used as the user cookie field .Fa arg passed to .Fn tmpl_ctx_create : .Pp .Bd -literal -compact -offset 3n struct http_servlet_tmpl_arg { void *arg; /* arg from 'tinfo' */ struct http_request *req; /* http request */ struct http_response *resp; /* http response */ }; .Ed .Pp Therefore, by casting the pointer returned from .Fn tmpl_ctx_get_arg to a .Li "struct http_servlet_tmpl_arg *" , .Fn handler can access both the original .Fa arg as well as the HTTP request and response objects. .Pp For an HTTP POST with MIME type .Dq application/x-www-form-urlencoded the servlet will automatically read in the URL-encoded name, value pairs, making them accessible via .Xr http_request_get_value 3 (see also .Fn http_servlet_tmpl_func_query below). .Pp When the servlet is destroyed, if the .Fa freer field is not .Dv NULL , it is invoked to release resources associated with .Fa arg . .\" .Ss Built-in template functions .\" The .Nm http_servlet_tmpl servlet includes the following built-in .Xr tmpl 3 user functions. These functions all assume the .Xr tmpl 3 user cookie is a .Li "struct http_servlet_tmpl_arg *". .Pp .Bl -hang -offset 3n -width 3n .It Fn http_servlet_tmpl_func_query This function takes exactly one argument, which is the name of a field in an HTML form, and returns the value of that field as submitted by the remote client. This function works for both GET and POST form submissions. If no such field was submitted, the empty string is returned. .It Fn http_servlet_tmpl_func_query_exists This function takes exactly one argument, which is the name of a field in an HTML form, and returns "1" or "0" depending on whether a field having that name was submitted by the client. .It Fn http_servlet_tmpl_func_query_string Takes zero arguments. Returns the HTTP query string. .It Fn http_servlet_tmpl_func_get_header Takes one argument, and returns the contents of the HTTP header having that name. .It Fn http_servlet_tmpl_func_set_header Takes two arguments, the name of an HTTP header and its value, and sets the corresponding HTTP response header. This function has no effect if the headers have already been sent. .It Fn http_servlet_tmpl_func_remove_header Takes one argument, the name of an HTTP header, and removes the corresponding HTTP response header. This function has no effect if the headers have already been sent. .It Fn http_servlet_tmpl_func_redirect Takes one argument, which must be a valid URL. Forces an HTTP redirect response to the URL. This function only works if the servlet has not created any output yet. .It Fn http_servlet_tmpl_func_unbuffer Takes zero arguments. Unbuffers the servlet output, so that the output is written directly to the network instead of first into a memory buffer. This is done by calling .Xr http_response_send_headers 3 with a non-zero .Fa unbuffer argument. This function should be called in servlets that produce a high volume of output. You can't modify the HTTP response headers once this has been called. .El .Pp The .Nm http_servlet_tmpl servlet by default buffers the entire template output to facilitate HTTP keep-alive. For templates that generate voluminous output, this could consume excessive memory. The solution is to implement a template function using .Fn http_servlet_tmpl_func_unbuffer and invoke this function within those templates. .Sh IMPLEMENTATION NOTES Multiple instances of the same .Nm http_servlet_tmpl servlet may be executing at the same time. Therefore, any user-supplied template functions called must be thread-safe. .Pp Since it's running as a servlet, the thread executing .Fn handler and .Fn errfmtr may be canceled at any cancellation point. Therefore, these functions should be written so as to not leak resources if this happens. .Sh RETURN VALUES On failure, .Fn http_servlet_tmpl_create returns .Dv NULL and sets .Va errno to an appropriate value. .Pp The built-in .Xr tmpl 3 user functions return .Dv NULL with .Va errno set to .Er EINVAL if the wrong number of arguments is passed. They may also return .Dv NULL with .Va errno set as a result of other system errors. .Sh SEE ALSO .Xr http_request 3 , .Xr http_response 3 , .Xr http_server 3 , .Xr http_servlet 3 , .Xr libpdel 3 , .Xr tmpl 3 .Sh HISTORY The PDEL library was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org