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