Annotation of embedaddon/libpdel/http/http_servlet.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.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