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

FreeBSD Manual Pages

  
 
  

home | help 
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  re-
       sponse  is  generated  remotely).  Some of the functions	and values de-
       fined below only	make sense in one of these cases.

       http_response objects are not created directly; rather,	they  are  ob-
       tained  from  another  object which is associated with the HTTP connec-
       tion.  They are freed automatically (and	become invalid)	when the  cor-
       responding HTTP connection object is closed.

   Accessors
       http_response_get_code()	 returns  the  HTTP  status  code from the re-
       sponse,	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  connec-
       tion, 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 imme-
       diately	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	incom-
       patible with keep-alive,	unless the user	code manually sets  the	 "Con-
       tent-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	 asso-
       ciated 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"
       authentication 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	corre-
       sponds  to  code;  otherwise,  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
       "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	* hav-
       ing 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 danger.  This function will	fail for  SSL  connections.   The  re-
       turned file descriptor 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	ports 15.0		April 22, 2002		      HTTP_RESPONSE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_response_get_output&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help