Annotation of embedaddon/libpdel/http/http_servlet.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.3,v 1.8 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_SERVLET 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_servlet
! 45: .Nd HTTP response generation API
! 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/http_servlet.h
! 56: .Sh DESCRIPTION
! 57: The
! 58: .Nm http_servlet
! 59: API provides an interface for user code to generate HTTP responses
! 60: for the
! 61: .Xr http_server 3
! 62: HTTP server.
! 63: .Pp
! 64: The PDEL library comes with these predefined servlets:
! 65: .Pp
! 66: .Bl -dash -compact -offset 3n
! 67: .It
! 68: HTTP basic authentication:
! 69: .Xr http_servlet_basicauth 3
! 70: .It
! 71: HTTP secure cookie authentication:
! 72: .Xr http_servlet_cookieauth 3
! 73: .It
! 74: HTTP redirect servlet:
! 75: .Xr http_servlet_redirect 3
! 76: .It
! 77: File servlet:
! 78: .Xr http_servlet_file 3
! 79: .It
! 80: .Xr tmpl 3
! 81: template servlet:
! 82: .Xr http_servlet_tmpl 3
! 83: .It
! 84: XML servlet:
! 85: .Xr http_servlet_xml 3
! 86: .It
! 87: XML-RPC servlet:
! 88: .Xr http_servlet_xmlrpc 3
! 89: .El
! 90: .Pp
! 91: Servlets are registered by first constructing the servlet object
! 92: and then invoking
! 93: .Fn http_server_register_servlet .
! 94: A servlet is represented by a
! 95: .Li "struct http_servlet" :
! 96: .Pp
! 97: .Bd -literal -offset 3n
! 98: typedef int http_servlet_run_t(struct http_servlet *servlet,
! 99: struct http_request *req, struct http_response *resp);
! 100: typedef void http_servlet_destroy_t(struct http_servlet *servlet);
! 101:
! 102: struct http_servlet {
! 103: void *arg; /* servlet cookie */
! 104: struct http_servlet_hook *hook; /* server info */
! 105: http_servlet_run_t *run; /* execute method */
! 106: http_servlet_destroy_t *destroy; /* destructor */
! 107: };
! 108: .Ed
! 109: .Pp
! 110: The
! 111: .Va arg
! 112: fields is private to the servlet itself and is ignored by the server.
! 113: .Pp
! 114: The
! 115: .Va hook
! 116: is an
! 117: .Xr http_server 3
! 118: private pointer that should be initialized to
! 119: .Dv NULL
! 120: when the servlet is constructed.
! 121: This pointer is set to a non-
! 122: .Dv NULL
! 123: value when the servlet is registered with a server.
! 124: The servlet itself should not dereference or modify this field.
! 125: .Pp
! 126: .Fn run
! 127: executes the servlet for a single request/response pair.
! 128: Each response is handled by the server in a separate thread,
! 129: and several request/response pairs may exist at the same time for
! 130: the same servlet object; i.e., servlets are multi-threaded.
! 131: Synchronization is the responsibility of the servlet.
! 132: The thread executing the servlet may be canceled at any
! 133: cancellation point, e.g., if the requesting user-agent closes the connection
! 134: before the response has been sent.
! 135: This means that the servlet code may need to register thread cleanup hooks
! 136: to avoid leaking memory or other resources.
! 137: .Pp
! 138: .Fn destroy
! 139: will be called when the servlet is being
! 140: unregistered and destroyed (servlets can be registered only once;
! 141: unregistering a servlet destroys it).
! 142: It should free any resources allocated when the servlet was constructed.
! 143: The
! 144: .Xr http_server 3
! 145: code guarantees that when
! 146: .Fn destroy
! 147: is invoked, there will be no instances of the
! 148: .Fn run
! 149: method currently executing.
! 150: .Sh RETURN VALUES
! 151: If successful,
! 152: .Fn run
! 153: should return 1 to indicate that the response is complete, or 0 to
! 154: indicate that the servlet did not generate a response and execution
! 155: should continue with the next-best matching servlet.
! 156: Zero return values are used by servlets that only generate a response
! 157: conditionally, e.g., authorization servlets.
! 158: .Pp
! 159: On failure
! 160: .Fn run
! 161: should -1 and set
! 162: .Va errno .
! 163: In this case (typically due to a system error), if a response has not
! 164: yet been sent, a generic "500 Internal Server Error" response will be
! 165: automatically generated with the error string from
! 166: .Xr strerror 3 .
! 167: .Sh SEE ALSO
! 168: .Xr http_client 3 ,
! 169: .Xr http_request 3 ,
! 170: .Xr http_response 3 ,
! 171: .Xr http_server 3 ,
! 172: .Xr http_servlet_basicauth 3 ,
! 173: .Xr http_servlet_cookieauth 3 ,
! 174: .Xr http_servlet_file 3 ,
! 175: .Xr http_servlet_redirect 3 ,
! 176: .Xr http_servlet_tmpl 3 ,
! 177: .Xr http_servlet_xml 3 ,
! 178: .Xr http_servlet_xmlrpc 3 ,
! 179: .Xr libpdel 3
! 180: .Rs
! 181: .%A R. Fielding
! 182: .%A J. Gettys
! 183: .%A J. Mogul
! 184: .%A H. Frystyk
! 185: .%A L. Masinter
! 186: .%A P. Leach
! 187: .%A T. Berners-Lee
! 188: .%T "Hypertext Transfer Protocol -- HTTP/1.1"
! 189: .%O RFC 2616
! 190: .Re
! 191: .Sh HISTORY
! 192: The PDEL library was developed at Packet Design, LLC.
! 193: .Dv "http://www.packetdesign.com/"
! 194: .Sh AUTHORS
! 195: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet.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