Annotation of embedaddon/libpdel/http/http_response.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_response.3,v 1.14 2004/06/02 17:24:37 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt HTTP_RESPONSE 3
42: .Os
43: .Sh NAME
44: .Nm http_response
45: .Nd HTTP response object
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: .\"
56: .Ss Accessors
57: .\"
58: .Ft "int"
59: .Fn http_response_get_code "struct http_response *resp"
60: .Ft "struct in_addr"
61: .Fn http_response_get_remote_ip "struct http_response *resp"
62: .Ft "u_int16_t"
63: .Fn http_response_get_remote_port "struct http_response *resp"
64: .Ft "SSL_CTX *"
65: .Fn http_response_get_ssl "struct http_response *resp"
66: .\"
67: .Ss "HTTP Headers"
68: .\"
69: .Ft "int"
70: .Fn http_response_num_headers "struct http_response *req"
71: .Ft "const char *"
72: .Fn http_response_get_header "struct http_response *resp" "const char *name"
73: .Ft "int"
74: .Fn http_response_get_header_by_index "struct http_response *resp" "u_int index" "const char **namep" "const char **valuep"
75: .Ft "int"
76: .Fn http_response_set_header "struct http_response *resp" "int append" "const char *name" "const char *valfmt" "..."
77: .Ft "int"
78: .Fn http_response_remove_header "struct http_response *resp" "const char *name"
79: .Ft "int"
80: .Fn http_response_send_headers "struct http_response *resp" "int unbuffer"
81: .\"
82: .Ss "HTTP Body"
83: .\"
84: .Ft "FILE *"
85: .Fn http_response_get_input "struct http_response *resp"
86: .Ft "FILE *"
87: .Fn http_response_get_output "struct http_response *resp" "int buffer"
88: .\"
89: .Ss "Canned Responses"
90: .\"
91: .Ft "void"
92: .Fn http_response_send_redirect "struct http_response *resp" "const char *url"
93: .Ft "void"
94: .Fn http_response_send_basic_auth "struct http_response *resp" "const char *realm"
95: .Ft "void"
96: .Fn http_response_send_error "struct http_response *resp" "int code" "const char *fmt" "..."
97: .Ft "void"
98: .Fn http_response_send_errno_error "struct http_response *resp"
99: .\"
100: .Ss Miscellaneous
101: .\"
102: .Ft "void"
103: .Fn http_response_guess_mime "const char *path" "const char **ctype" "const char **cencs" "int maxenc"
104: .Ft "const char *"
105: .Fn http_response_status_msg "int code"
106: .Ft "int"
107: .Fn http_response_no_body "int code"
108: .Ft "int"
109: .Fn http_response_get_raw_socket "struct http_response *resp"
110: .\"
111: .Sh DESCRIPTION
112: .\"
113: The
114: .Nm http_response
115: object is used by the PDEL HTTP library to represent an HTTP response.
116: An HTTP response may be associated with an HTTP server (the response is
117: generated locally) or an HTTP client (the response is generated remotely).
118: Some of the functions and values defined below only make sense in one
119: of these cases.
120: .Pp
121: .Nm http_response
122: objects are not created directly; rather, they are obtained from another
123: object which is associated with the HTTP connection.
124: They are freed automatically (and become invalid) when the corresponding
125: HTTP connection object is closed.
126: .\"
127: .Ss Accessors
128: .\"
129: .Fn http_response_get_code
130: returns the HTTP status code from the response, e.g., 200 for "OK".
131: Status codes are defined in
132: .Li "<pdel/http/http_defs.h>" ,
133: which is included by
134: .Li "<pdel/http/http_server.h>" .
135: .Pp
136: .Fn http_response_get_remote_ip
137: returns the IP address of the remote side.
138: .Pp
139: .Fn http_response_get_remote_port
140: returns the TCP port of the remote side.
141: .Pp
142: .Fn http_response_get_ssl
143: returns the SSL context for the HTTP connection, or
144: .Dv NULL
145: if the connection is not over SSL.
146: .\"
147: .Ss "HTTP Headers"
148: .\"
149: .Fn http_response_get_header
150: returns the value of the named header, or
151: .Dv NULL
152: if the header is not defined for the response.
153: HTTP header names are case-insensitive.
154: .Pp
155: .Fn http_response_num_headers
156: returns the number of headers in the response.
157: .Pp
158: .Fn http_response_get_header_by_index
159: points
160: .Fa "*namep"
161: at the name and
162: .Fa "*valuep"
163: at the value of the header with index
164: .Fa index ,
165: which must be less than the value returned by
166: .Fn http_response_num_headers .
167: .Pp
168: .Fn http_response_set_header
169: formats and sets a header value.
170: If
171: .Fa append
172: is non-zero, the value is appended to any existing value
173: (after adding a ",\ " separator) rather than replacing it.
174: As a special case, setting the "Set-Cookie" header does not
175: replace existing instances, it just adds a new instance.
176: When the response headers are sent, all instances of "Set-Cookie" are sent.
177: .Pp
178: .Fn http_response_remove_header
179: removes a header from the response.
180: .Pp
181: .Fn http_response_send_headers
182: causes the server response headers to be sent to the client if they
183: haven't already been sent.
184: Setting
185: .Fa unbuffer
186: to non-zero causes the output to be unbuffered.
187: It has the same affect as setting
188: .Fa buffer
189: to zero when calling
190: .Fn http_response_get_output
191: (see below).
192: .\"
193: .Ss "HTTP Body"
194: .\"
195: .Fn http_response_get_input
196: returns the body of the response as an input stream.
197: The local side must be the client for this HTTP connection.
198: .Pp
199: .Fn http_response_get_output
200: returns an output stream that writes into the body of the response.
201: The local side must be the server for this HTTP connection.
202: .Fa buffer
203: determines whether the entire output should be buffered before sending, or
204: should writes to the stream translate immediately into writes to the server.
205: The latter option will force the headers to be sent (if they haven't been
206: sent already) when the first byte is written to the stream.
207: Setting
208: .Fa buffer
209: to zero is also incompatible with keep-alive, unless the user code manually
210: sets the "Content-Length" header (in which case it takes responsibility
211: for writing the correct number of bytes).
212: If
213: .Fa buffer
214: is non-zero, the output will be buffered entirely in memory until the output
215: stream is closed, at which point "Content-Length" is computed automatically.
216: .Pp
217: Certain HTTP responses (e.g., "304 Not Modified") do not have an associated
218: response body (see
219: .Fn http_response_no_body
220: below); for these responses, the output stream returned by
221: .Fn http_response_get_output
222: will discard all data written to it.
223: .\"
224: .Ss "Canned Responses"
225: .\"
226: .Fn http_response_send_redirect
227: sends an HTTP redirect (301) to the client.
228: .Fa url
229: is the URL to which the client should be redirected.
230: .Pp
231: .Fn http_response_send_basic_auth
232: sends an "Unauthorized" repsonse (401) to the client, causing browsers
233: to pop up a login window.
234: Only "Basic" authentication is supported.
235: The
236: .Fa realm
237: is the authentication realm (which is usually visible in the popup window).
238: .Pp
239: .Fn http_response_send_error
240: formats and sends an error response to the client with the HTTP status code
241: .Fa code .
242: For status codes that have response bodies, a very simple HTML page
243: is cobbled together and sent as well.
244: .Fa fmt
245: may be
246: .Dv NULL
247: to use the generic error message that corresponds to
248: .Fa code ;
249: otherwise, the error string is formatted as with
250: .Xr printf 3 .
251: .Pp
252: .Fn http_response_send_errno_error
253: attempts to generate an appropriate error response based on the value of
254: .Va errno .
255: .\"
256: .Ss Miscellaneous
257: .\"
258: .Fn http_response_guess_mime
259: tries to guess the MIME "Content-Type" and "Content-Encoding" of the file
260: .Fa path .
261: The content type is returned in
262: .Fa "*ctype" .
263: If it can't be determined, "text/plain; charset=iso-8859-1" is returned.
264: .Pp
265: The content encoding is really a list of encodings.
266: For example, "foo.uu.gz" would be detected as having encoding
267: "x-uuencode" followed by "gzip".
268: The
269: .Fa "cencs"
270: argument should point to an array of
271: .Li "char *"
272: having length
273: .Fa maxencs .
274: This array will be filled in and any extra entries set to
275: .Dv NULL .
276: If
277: .Fa "cencs"
278: is
279: .Dv NULL ,
280: no attempt is made to determine content encoding.
281: .Pp
282: .Fn http_response_status_msg
283: returns an ASCII string corresponding to the HTTP response code
284: .Fa code .
285: .Pp
286: .Fn http_response_no_body
287: returns 1 if a response with HTTP response code
288: .Fa code
289: should not have a response body, otherwise zero.
290: .Pp
291: .Fn http_response_get_raw_socket
292: returns the underlying file descriptor for the HTTP connection.
293: This is a huge layering violation fraught with danger.
294: This function will fail for SSL connections.
295: The returned file descriptor should not be closed.
296: .Sh RETURN VALUES
297: All of the above routines that can return an error return
298: .Dv NULL
299: or -1 to indicate this and set
300: .Va errno
301: to an appropriate value.
302: Success is indicated by a normal return value or zero.
303: .Sh SEE ALSO
304: .Xr http_client 3 ,
305: .Xr http_mime 3 ,
306: .Xr http_request 3 ,
307: .Xr http_server 3 ,
308: .Xr http_servlet 3 ,
309: .Xr libpdel 3
310: .Rs
311: .%A R. Fielding
312: .%A J. Gettys
313: .%A J. Mogul
314: .%A H. Frystyk
315: .%A L. Masinter
316: .%A P. Leach
317: .%A T. Berners-Lee
318: .%T "Hypertext Transfer Protocol -- HTTP/1.1"
319: .%O RFC 2616
320: .Re
321: .Sh HISTORY
322: The PDEL library was developed at Packet Design, LLC.
323: .Dv "http://www.packetdesign.com/"
324: .Sh AUTHORS
325: .An Archie Cobbs Aq archie@freebsd.org
326: .Sh BUGS
327: There are not as many
328: .Nm http_response
329: methods as there are
330: .Nm http_request
331: methods.
332: This reflects a bias of the library towards implementing servers
333: rather than clients.
334: More support for the client side should be added.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_response.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