HTTP_RESPONSE(3) Library Functions Manual HTTP_RESPONSE(3) NAME http_response -- HTTP response object LIBRARY PDEL Library (libpdel, -lpdel) SYNOPSIS #include <sys/types.h> #include <stdio.h> #include <netinet/in.h> #include <openssl/ssl.h> #include <pdel/http/http_defs.h> #include <pdel/http/http_server.h> Accessors int http_response_get_code(struct http_response *resp); struct in_addr http_response_get_remote_ip(struct http_response *resp); u_int16_t http_response_get_remote_port(struct http_response *resp); SSL_CTX * http_response_get_ssl(struct http_response *resp); HTTP Headers int http_response_num_headers(struct http_response *req); const char * http_response_get_header(struct http_response *resp, const char *name); int http_response_get_header_by_index(struct http_response *resp, u_int index, const char **namep, const char **valuep); int http_response_set_header(struct http_response *resp, int append, const char *name, const char *valfmt, ...); int http_response_remove_header(struct http_response *resp, const char *name); int http_response_send_headers(struct http_response *resp, int unbuffer); HTTP Body FILE * http_response_get_input(struct http_response *resp); FILE * http_response_get_output(struct http_response *resp, int buffer); Canned Responses void http_response_send_redirect(struct http_response *resp, const char *url); void http_response_send_basic_auth(struct http_response *resp, const char *realm); void http_response_send_error(struct http_response *resp, int code, const char *fmt, ...); void http_response_send_errno_error(struct http_response *resp); Miscellaneous void http_response_guess_mime(const char *path, const char **ctype, const char **cencs, int maxenc); const char * http_response_status_msg(int code); int http_response_no_body(int code); int http_response_get_raw_socket(struct http_response *resp); DESCRIPTION The http_response object is used by the PDEL HTTP library to represent an HTTP response. An HTTP response may be associated with an HTTP server (the response is generated locally) or an HTTP client (the response is generated remotely). Some of the functions and values defined below only make sense in one of these cases. http_response objects are not created directly; rather, they are obtained from another object which is associated with the HTTP connection. They are freed automatically (and become invalid) when the corresponding HTTP con- nection object is closed. Accessors http_response_get_code() returns the HTTP status code from the response, e.g., 200 for "OK". Status codes are defined in <pdel/http/http_defs.h>, which is included by <pdel/http/http_server.h>. http_response_get_remote_ip() returns the IP address of the remote side. http_response_get_remote_port() returns the TCP port of the remote side. http_response_get_ssl() returns the SSL context for the HTTP connection, or NULL if the connection is not over SSL. HTTP Headers http_response_get_header() returns the value of the named header, or NULL if the header is not defined for the response. HTTP header names are case- insensitive. http_response_num_headers() returns the number of headers in the response. http_response_get_header_by_index() points *namep at the name and *valuep at the value of the header with index index, which must be less than the value returned by http_response_num_headers(). http_response_set_header() formats and sets a header value. If append is non-zero, the value is appended to any existing value (after adding a ", " separator) rather than replacing it. As a special case, setting the "Set- Cookie" header does not replace existing instances, it just adds a new in- stance. When the response headers are sent, all instances of "Set-Cookie" are sent. http_response_remove_header() removes a header from the response. http_response_send_headers() causes the server response headers to be sent to the client if they haven't already been sent. Setting unbuffer to non- zero causes the output to be unbuffered. It has the same affect as setting buffer to zero when calling http_response_get_output() (see below). HTTP Body http_response_get_input() returns the body of the response as an input stream. The local side must be the client for this HTTP connection. http_response_get_output() returns an output stream that writes into the body of the response. The local side must be the server for this HTTP con- nection. buffer determines whether the entire output should be buffered before sending, or should writes to the stream translate immediately into writes to the server. The latter option will force the headers to be sent (if they haven't been sent already) when the first byte is written to the stream. Setting buffer to zero is also incompatible with keep-alive, un- less the user code manually sets the "Content-Length" header (in which case it takes responsibility for writing the correct number of bytes). If buffer is non-zero, the output will be buffered entirely in memory until the output stream is closed, at which point "Content-Length" is computed automatically. Certain HTTP responses (e.g., "304 Not Modified") do not have an associated response body (see http_response_no_body() below); for these responses, the output stream returned by http_response_get_output() will discard all data written to it. Canned Responses http_response_send_redirect() sends an HTTP redirect (301) to the client. url is the URL to which the client should be redirected. http_response_send_basic_auth() sends an "Unauthorized" repsonse (401) to the client, causing browsers to pop up a login window. Only "Basic" au- thentication is supported. The realm is the authentication realm (which is usually visible in the popup window). http_response_send_error() formats and sends an error response to the client with the HTTP status code code. For status codes that have response bodies, a very simple HTML page is cobbled together and sent as well. fmt may be NULL to use the generic error message that corresponds to code; oth- erwise, the error string is formatted as with printf(3). http_response_send_errno_error() attempts to generate an appropriate error response based on the value of errno. Miscellaneous http_response_guess_mime() tries to guess the MIME "Content-Type" and "Con- tent-Encoding" of the file path. The content type is returned in *ctype. If it can't be determined, "text/plain; charset=iso-8859-1" is returned. The content encoding is really a list of encodings. For example, "foo.uu.gz" would be detected as having encoding "x-uuencode" followed by "gzip". The cencs argument should point to an array of char * having length maxencs. This array will be filled in and any extra entries set to NULL. If cencs is NULL, no attempt is made to determine content encoding. http_response_status_msg() returns an ASCII string corresponding to the HTTP response code code. http_response_no_body() returns 1 if a response with HTTP response code code should not have a response body, otherwise zero. http_response_get_raw_socket() returns the underlying file descriptor for the HTTP connection. This is a huge layering violation fraught with dan- ger. This function will fail for SSL connections. The returned file de- scriptor should not be closed. RETURN VALUES All of the above routines that can return an error return NULL or -1 to in- dicate this and set errno to an appropriate value. Success is indicated by a normal return value or zero. SEE ALSO http_client(3), http_mime(3), http_request(3), http_server(3), http_servlet(3), libpdel(3) R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and T. Berners-Lee, Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616. HISTORY The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/ AUTHORS Archie Cobbs <archie@freebsd.org> BUGS There are not as many http_response methods as there are http_request meth- ods. This reflects a bias of the library towards implementing servers rather than clients. More support for the client side should be added. FreeBSD ports 15.quarterly April 22, 2002 HTTP_RESPONSE(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_response_send_headers&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>