HTTP_REQUEST(3) 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 con- nection 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-decod- ing. 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-decod- ing 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 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 imple- ment "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-in- sensitive. 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 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. HTTP Basic Authorization http_request_get_username() returns the username from the "Authorization" header, or NULL if none was specified. This works for "Basic" authentica- tion only. http_request_get_password() returns the password from the "Authorization" header, or NULL if none was specified. This works for "Basic" authentica- tion 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 re- quest 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 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 po- sition 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 out- put 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 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 de- scription 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. Miscellaneous 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 re- sult, 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 dan- ger, but necessary for implementing a proxy server that supports the "CON- NECT" method. This function will fail for SSL connections. The returned file descriptor 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_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 ports 15.quarterly April 22, 2002 HTTP_REQUEST(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_request_set_header&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>