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

FreeBSD Manual Pages

  
 
  

home | help
HTTP_REQUEST(3)	       FreeBSD Library Functions Manual	       HTTP_REQUEST(3)

NAME
     http_request -- HTTP request 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
     const char	*
     http_request_get_method(struct http_request *req);

     int
     http_request_set_method(struct http_request *req, const char *method);

     const char	*
     http_request_get_uri(struct http_request *req);

     const char	*
     http_request_get_path(struct http_request *req);

     int
     http_request_set_path(struct http_request *req, const char	*path);

     const char	*
     http_request_get_version(struct http_request *req);

     const char	*
     http_request_get_query_string(struct http_request *req);

     const char	*
     http_request_get_host(struct http_request *req);

     struct in_addr
     http_request_get_remote_ip(struct http_request *req);

     u_int16_t
     http_request_get_remote_port(struct http_request *req);

     SSL_CTX *
     http_request_get_ssl(struct http_request *req);

   HTTP	Headers
     const char	*
     http_request_get_header(struct http_request *req, const char *name);

     int
     http_request_num_headers(struct http_request *req);

     int
     http_request_get_header_by_index(struct http_request *req,	u_int index,
	 const char **namep, const char	**valuep);

     int
     http_request_set_header(struct http_request *req, int append,
	 const char *name, const char *valfmt, ...);

     int
     http_request_remove_header(struct http_request *req, const	char *name);

     int
     http_request_send_headers(struct http_request *req);

   HTTP	Body
     FILE *
     http_request_get_input(struct http_request	*req);

     FILE *
     http_request_get_output(struct http_request *req, int buffer);

   HTTP	Basic Authorization
     const char	*
     http_request_get_username(struct http_request *req);

     const char	*
     http_request_get_password(struct http_request *req);

     char *
     http_request_encode_basic_auth(const char *mtype, const char *username,
	 const char *password);

   Name/Value Pairs
     const char	*
     http_request_get_value(struct http_request	*req, const char *name,
	 int instance);

     int
     http_request_set_value(struct http_request	*req, const char *name,
	 const char *value);

     int
     http_request_get_num_values(struct	http_request *req);

     int
     http_request_get_value_by_index(struct http_request *req, int index,
	 const char **name, const char **value);

     int
     http_request_set_query_from_values(struct http_request *req);

     int
     http_request_read_url_encoded_values(struct http_request *req);

     int
     http_request_write_url_encoded_values(struct http_request *req);

   MIME	Multi-Part Support
     int
     http_request_get_mime_multiparts(struct http_request *req,
	 http_mime_handler_t *handler, void *arg);

     struct mime_multipart *
     http_request_read_mime_multipart(struct http_request *req);

     int
     http_request_file_upload(struct http_request *req,	const char *field,
	 FILE *fp, size_t max);

   Miscellaneous
     char *
     http_request_url_encode(const char	*mtype,	const char *string);

     void
     http_request_url_decode(const char	*s, char *t);

     time_t
     http_request_parse_time(const char	*string);

     void
     http_request_set_proxy(struct http_request	*req, int whether);

     int
     http_request_get_raw_socket(struct	http_request *req);

DESCRIPTION
     The http_request object is	used by	the PDEL HTTP library to represent an
     HTTP request.  An HTTP request may	be associated with an HTTP client (the
     request is	generated locally) or an HTTP server (the request is generated
     remotely).	 Some of the functions and values defined below	only make
     sense in one of these cases.

     http_request 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_request_get_method() returns the HTTP	method,	typically "GET"	or
     "POST" but	others are possible.

     http_request_set_method() sets the	method for a request when the local
     side is the client.

     http_request_get_uri() gets the URI from the request.  This is the	re-
     quested resource exactly as the client requested it, before any URL-de-
     coding.  The first	character of this string will always be	'/' for	non-
     proxy requests.

     http_request_get_path() returns the path part of the URI, after URL-de-
     coding has	taken place.  This does	not include the	'?' and	query string
     part, if any.  The	first character	of this	string will always be '/'.

     http_request_set_path() sets the path for a request.  The first character
     must be '/'.

     http_request_get_version()	returns	the version string for this request.
     Typically one of "HTTP/0.9", "HTTP/1.0", or "HTTP/1.1".

     http_request_get_query_string() returns the HTTP query string (which op-
     tionally appears at the end of an URL after a '?' character), or the
     empty string if there is no query string.	The returned string is exactly
     as	it was submitted by the	client,	i.e., no URL-decoding has been per-
     formed on it.

     http_request_get_host() returns the hostname specified in the request.
     This may be NULL for a non-proxy request if the client fails to send the
     "Host" header (typically older browsers).	This value can be used to im-
     plement "virtual hosting".

     http_request_get_remote_ip() returns the IP address of the	remote side.

     http_request_get_remote_port() returns the	TCP port of the	remote side.

     http_request_get_ssl() returns the	SSL context for	the HTTP connection,
     or	NULL if	the connection is not over SSL.

   HTTP	Headers
     http_request_get_header() returns the value of the	named header, or NULL
     if	the header is not defined for the request.  HTTP header	names are
     case-insensitive.

     http_request_num_headers()	returns	the number of headers in the request.

     http_request_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_request_num_headers().

     http_request_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.

     http_request_remove_header() removes a header from	the request.

     http_request_send_headers() causes	the client request headers to be sent
     to	the server if they haven't already been	sent.  This causes the URI to
     be	constructed from the request path (see http_request_set_path() above)
     and the name/value	pairs (see http_request_set_value() below) added as
     the query string.

   HTTP	Body
     http_request_get_input() returns the body of the request as an input
     stream.  The local	side must be the server	for this HTTP connection.

     http_request_get_output() returns an output stream	that writes into the
     body of the request.  The local side must be the client 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.

   HTTP	Basic Authorization
     http_request_get_username() returns the username from the "Authorization"
     header, or	NULL if	none was specified.  This works	for "Basic" authenti-
     cation only.

     http_request_get_password() returns the password from the "Authorization"
     header, or	NULL if	none was specified.  This works	for "Basic" authenti-
     cation only.

     http_request_encode_basic_auth() formats and base-64 encodes the username
     and password into a form suitable for the HTTP "Basic" authentication
     header.  The returned buffer is allocated with typed_mem(3) type mtype;
     the caller	must eventually	free it.

   Name/Value Pairs
     Requests have an internal list of name, value pairs.  The names need not
     be	unique.	 For servers, this list	is automatically initialized from the
     request by	parsing	the URI	query string.  For clients, this list is used
     to	automatically generate the URI query string when the request headers
     are sent for "GET"	queries	only.

     http_request_get_value() returns the value	associated with	with name.
     Since the same name may exist multiple times, instance should be 0	to re-
     trieve the	first value, 1 for the second, etc.  NULL is returned if the
     value is not found.

     http_request_set_value() adds a name, value pair to the internal data-
     base.

     http_request_get_num_values() returns the number of name, value pairs.

     http_request_get_value_by_index() retrieves name, value pair that is at
     position index in the list.  Note that the	list is	kept sorted by name.

     http_request_set_query_from_values() generates a query string for the re-
     quest based on the	name, value pairs.  This is useful if a	query string
     is	desired	with a non-GET request.

     http_request_read_url_encoded_values() reads the request body, interprets
     it	as an URL-encoded query	string,	and sets the request's name, value
     pairs from	string.	 This is typically used	by a server to input HTML form
     data that was submitted using the "POST" method.

     http_request_write_url_encoded_values() writes out	the name, value	pairs
     as	URL-encoded query string data.	This is	typically used by a client to
     output HTML form data using the "POST" method.

   MIME	Multi-Part Support
     These functions operate on	requests whose body contains multi-part	MIME
     data.  The	request	must have content type "multipart/form-data" and the
     body must be properly formatted for multi-part MIME or else these func-
     tions will	return an error.

     http_request_get_mime_multiparts()	reads the request body as a multi-part
     MIME document and invokes the handler for each part:

	 typedef int http_mime_handler_t(void *arg,
		     struct mime_part *part, FILE *fp);

     The arg is	passed untouched to the	handler.  fp is	an input stream	that
     reads only	the MIME part being processed.	The handler should read	as
     much of the MIME part as desired and then return 0	to continue with sub-
     sequent parts, or else -1 (with errno set)	to abort processing.  In the
     latter case, http_request_get_mime_multiparts() will return -1.  In no
     case should the handler close the stream fp or free part.	See
     http_mime(3) for a	description of how to use part.

     http_request_read_mime_multipart()	reads an entire	multi-part MIME	re-
     quest body	into memory and	returns	the result, which the caller is	re-
     sponsible for eventually freeing.	See http_mime(3) for a description of
     how to use	the return value.

     http_request_file_upload()	reads only the value of	the field field	from a
     multi-part	MIME request body and writes it	to the output stream fp.  The
     data is transferred in an on-line fasion so that the entire value does
     not need to fit in	memory at once.	 This is useful	for HTML form file up-
     loads of large files.  All	MIME parts other than the first	part with name
     field are discarded.  If max is non-zero and the length of	the field is
     more than max bytes, an error is generated	with errno set to EFBIG. This
     is	useful for avoiding disk-filling attacks.

   Miscellaneous
     http_request_url_encode() URL-encodes the string s	into a buffer allo-
     cated with	typed_mem(3) type mtype	and returns the	result,	which the
     caller must eventually free.

     http_request_url_decode() URL-decodes the string s	and puts the result in
     the buffer	t, which must have length at least strlen(s) + 1.

     http_request_parse_time() parses an HTTP time string and returns the re-
     sult, or -1 on failure.

     http_request_set_proxy() sets or clears the proxy bit for a client	re-
     quest.  When this bit is set, the client will make	a proxy	HTTP request
     instead of	a normal HTTP request.

     http_request_get_raw_socket() returns the underlying file descriptor for
     the HTTP connection.  This	is a huge layering violation fraught with dan-
     ger, but necessary	for implementing a proxy server	that supports the
     "CONNECT" method.	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_response(3), http_server(3),
     http_servlet(3), libpdel(3), typed_mem(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.

     N.	Freed and N. Borenstein, Multipurpose Internet Mail Extensions (MIME)
     Part Two: Media Types, RFC	2046.

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

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

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

home | help