Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
HTTP_REQUEST(3) FreeBSD Library Functions Manual HTTP_REQUEST(3)

HTTP request object

PDEL Library (libpdel, -lpdel)

#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>

const char *
http_request_get_method(struct http_request *req);
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);
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);
http_request_get_remote_port(struct http_request *req);
http_request_get_ssl(struct http_request *req);

const char *
http_request_get_header(struct http_request *req, const char *name);
http_request_num_headers(struct http_request *req);
http_request_get_header_by_index(struct http_request *req, u_int index, const char **namep, const char **valuep);
http_request_set_header(struct http_request *req, int append, const char *name, const char *valfmt, ...);
http_request_remove_header(struct http_request *req, const char *name);
http_request_send_headers(struct http_request *req);

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

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);

const char *
http_request_get_value(struct http_request *req, const char *name, int instance);
http_request_set_value(struct http_request *req, const char *name, const char *value);
http_request_get_num_values(struct http_request *req);
http_request_get_value_by_index(struct http_request *req, int index, const char **name, const char **value);
http_request_set_query_from_values(struct http_request *req);
http_request_read_url_encoded_values(struct http_request *req);
http_request_write_url_encoded_values(struct http_request *req);

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);
http_request_file_upload(struct http_request *req, const char *field, FILE *fp, size_t max);

char *
http_request_url_encode(const char *mtype, const char *string);
http_request_url_decode(const char *s, char *t);
http_request_parse_time(const char *string);
http_request_set_proxy(struct http_request *req, int whether);
http_request_get_raw_socket(struct http_request *req);

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.

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 requested resource exactly as the client requested it, before any URL-decoding. 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-decoding 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 optionally 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 performed 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 implement "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_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_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 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, 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 entirely in memory until the output stream is closed, at which point "Content-Length" is computed automatically.

http_request_get_username() returns the username from the "Authorization" header, or NULL if none was specified. This works for "Basic" authentication only.
http_request_get_password() returns the password from the "Authorization" header, or NULL if none was specified. This works for "Basic" authentication 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.

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 retrieve 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 database.
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 request 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.

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 functions 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 subsequent 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 request body into memory and returns the result, which the caller is responsible 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 uploads 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.

http_request_url_encode() URL-encodes the string s into a buffer allocated 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 result, or -1 on failure.
http_request_set_proxy() sets or clears the proxy bit for a client request. 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 danger, but necessary for implementing a proxy server that supports the "CONNECT" method. This function will fail for SSL connections. The returned file descriptor should not be closed.

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 indicated by a normal return value or zero.

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.

The PDEL library was developed at Packet Design, LLC.

Archie Cobbs ⟨⟩
April 22, 2002 FreeBSD 12.0-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.