Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTTP_RESPONSE(3)       FreeBSD 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
     connection	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 re-
     sponse.

     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 instance.  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
     connection.  buffer determines whether the	entire output should be
     buffered before sending, or should	writes to the stream translate immedi-
     ately into	writes to the server.  The latter option will force the	head-
     ers 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, unless	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 en-
     tirely in memory until the	output stream is closed, at which point	"Con-
     tent-Length" is computed automatically.

     Certain HTTP responses (e.g., "304	Not Modified") do not have an associ-
     ated response body	(see http_response_no_body() below); for these re-
     sponses, 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	re-
     sponse 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; otherwise, the error string is formatted as with printf(3).

     http_response_send_errno_error() attempts to generate an appropriate er-
     ror response based	on the value of	errno.

   Miscellaneous
     http_response_guess_mime()	tries to guess the MIME	"Content-Type" and
     "Content-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 en-
     coding.

     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
     indicate this and set errno to an appropriate value.  Success is indi-
     cated 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
     methods.  This reflects a bias of the library towards implementing
     servers rather than clients.  More	support	for the	client side should be
     added.

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=http_response_send_headers&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help