http.h File Reference

Go to the source code of this file.

Data Structures
struct	server_cfg
	HTTP server configuration. More...

Macros
#define	HTTP_REQ_MAX_HDRS   (16)
	Maximum number of request headers. More...
#define	HTTP_METHODS_GET_HEAD    ((1U << HTTP_METHOD_GET) | (1U << HTTP_METHOD_HEAD))
	Bitmap for methods GET and HEAD. More...
#define	HTTP_DEFAULT_IDLE_TMO_S   (5)
	Default idle timeout. More...
#define	HTTP_DEFAULT_SEND_TMO_S   (5)
	Default send timeout. More...
#define	HTTP_DEFAULT_LISTEN_BACKLOG   (10)
	Default listener backlog. More...
#define	STRLEN_LTRL(s)   (sizeof(s) - 1)
	Length of a literal string. More...
#define	http_req_hdr_ltrl(req, name, val_len)    http_req_hdr((req), (name), STRLEN_LTRL(name), (val_len))
	Return the value of a request header with a literal name. More...
#define	http_req_hdr_eq_ltrl(req, name, val)
	Return true if a request header value is equal to a literal string. More...
#define	http_req_hdr_contains_ltrl(req, name, substring)
	Return true if a request header contains a literal string. More...
#define	http_req_cookie_ltrl(req, name, val_len)    http_req_cookie((req), (name), STRLEN_LTRL(name), (val_len))
	Return the value of a cookie whose name is a string literal. More...
#define	RESP_HDR_SMALL_BUF_SZ   (512)
	Size of "small" buffers for response headers. More...
#define	RESP_HDR_LARGE_BUF_SZ   (TCP_MSS)
	Size of "large" buffers for response headers. More...
#define	RESP_HDR_SMALL_POOL_SZ   (MAX_CONCURRENT_CX_HINT)
	Number of buffers in the "small" memory pool for response headers. More...
#define	RESP_HDR_LARGE_POOL_SZ   (RESP_HDR_SMALL_POOL_SZ / 2)
	Number of buffers in the "large" memory pool for response headers. More...
#define	http_resp_set_hdr_ltrl(resp, name, val)
	Set a response header to a literal string. More...
#define	http_resp_set_type_ltrl(resp, type)    http_resp_set_type((resp), (type), STRLEN_LTRL(type))
	Set the Content-Type response header to a literal string. More...

Typedefs
typedef err_t(*	hndlr_f) (struct http *http, void *priv)
	Function type for custom response handlers. More...
typedef void	priv_fini_f(void *p)
	Function type for private data finalizers. More...
typedef err_t(*	name_val_iter_f) (const char *name, size_t name_len, const char *val, size_t val_len, void *priv)
	Function type for name/value iterators. More...

Enumerations
enum	http_method_t {   HTTP_METHOD_GET = 0 , HTTP_METHOD_HEAD , HTTP_METHOD_POST , HTTP_METHOD_PUT ,   HTTP_METHOD_DELETE , HTTP_METHOD_CONNECT , HTTP_METHOD_OPTIONS , HTTP_METHOD_TRACE ,   __HTTP_METHOD_MAX }
	Request method. More...
enum	http_status_t {   HTTP_STATUS_CONTINUE = 100 , HTTP_STATUS_SWITCHING_PROTOCOLS = 101 , HTTP_STATUS_OK = 200 , HTTP_STATUS_CREATED = 201 ,   HTTP_STATUS_ACCEPTED = 202 , HTTP_STATUS_NON_AUTHORITATIVE_INFO = 203 , HTTP_STATUS_NO_CONTENT = 204 , HTTP_STATUS_RESET_CONTENT = 205 ,   HTTP_STATUS_PARTIAL_CONTENT = 206 , HTTP_STATUS_MULTIPLE_CHOICES = 300 , HTTP_STATUS_MOVED_PERMANENTLY = 301 , HTTP_STATUS_FOUND = 302 ,   HTTP_STATUS_SEE_OTHER = 303 , HTTP_STATUS_NOT_MODIFIED = 304 , HTTP_STATUS_USE_PROXY = 305 , HTTP_STATUS_TEMPORARY_REDIRECT = 307 ,   HTTP_STATUS_PERMANENT_REDIRECT = 308 , HTTP_STATUS_BAD_REQUEST = 400 , HTTP_STATUS_UNAUTHORIZED = 401 , HTTP_STATUS_PAYMENT_REQUIRED = 402 ,   HTTP_STATUS_FORBIDDEN = 403 , HTTP_STATUS_NOT_FOUND = 404 , HTTP_STATUS_METHOD_NOT_ALLOWED = 405 , HTTP_STATUS_NOT_ACCEPTABLE = 406 ,   HTTP_STATUS_PROXY_AUTH_REQUIRED = 407 , HTTP_STATUS_REQUEST_TIMEOUT = 408 , HTTP_STATUS_CONFLICT = 409 , HTTP_STATUS_GONE = 410 ,   HTTP_STATUS_LENGTH_REQUIRED = 411 , HTTP_STATUS_PRECONDITION_FAILED = 412 , HTTP_STATUS_CONTENT_TOO_LARGE = 413 , HTTP_STATUS_URI_TOO_LONG = 414 ,   HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415 , HTTP_STATUS_RANGE_NOT_SATISFIABLE = 416 , HTTP_STATUS_EXPECTATION_FAILED = 417 , HTTP_STATUS_IM_A_TEAPOT = 418 ,   HTTP_STATUS_MISDIRECTED_REQUEST = 421 , HTTP_STATUS_UNPROCESSABLE_CONTENT = 422 , HTTP_STATUS_UPGRADE_REQUIRED = 426 , HTTP_STATUS_REQ_HDR_FIELDS_TOO_LARGE = 431 ,   HTTP_STATUS_INTERNAL_SERVER_ERROR = 500 , HTTP_STATUS_NOT_IMPLEMENTED = 501 , HTTP_STATUS_BAD_GATEWAY = 502 , HTTP_STATUS_SERVICE_UNAVAILABLE = 503 ,   HTTP_STATUS_GATEWAY_TIMEOUT = 504 , HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED = 505 }
	enum for HTTP response status codes More...

Functions
static void	http_cx_set_priv (struct http *http, void *priv, priv_fini_f *fini, priv_cnt_f *cnt)
	Set a connection-scoped private object. More...
static void *	http_cx_priv (struct http *http)
	Return the connection-scoped private object, if any. More...
err_t	http_cfg (const char *name, struct server_cfg *cfg)
	Get the default confiuration for a server by name. More...
static struct server_cfg	http_default_cfg (void)
	Get the default HTTP server configuration. More...
err_t	http_srv_init (struct server **server, struct server_cfg *cfg)
	Start an HTTP server. More...
err_t	http_srv_fini (struct server *server)
	Stop an HTTP server. More...
ip_addr_t *	http_srv_ip (struct server *server)
	Return the server listener IP address. More...
uint16_t	http_srv_port (struct server *server)
	Return the server listener port number. More...
void	http_srv_set_priv (struct server *server, void *priv, priv_fini_f *fini)
	Set a server-wide private object. More...
static ip_addr_t *	http_cx_local_ip (struct http *http)
	Return the local IP address of the current HTTP connection. More...
static uint16_t	http_cx_local_port (struct http *http)
	Return the local port of the current HTTP connection. More...
static ip_addr_t *	http_cx_remote_ip (struct http *http)
	Return the remote IP address of the current HTTP connection. More...
static uint16_t	http_cx_remote_port (struct http *http)
	Return the remote port of the current HTTP connection. More...
static void *	http_srv_priv (struct http *http)
	Return the server-wide private object, if any. More...
static struct req *	http_req (struct http *http)
	Get the current request object. More...
const char *	http_req_hdr (struct req *req, const char *name, size_t name_len, size_t *val_len)
	Return the value of a request header. More...
static const char *	http_req_hdr_str (struct req *req, const char *name, size_t *val_len)
	Return the value of a request header with a nul-terminated name. More...
bool	http_req_hdr_eq (struct req *req, const char *name, size_t name_len, const char *val, size_t val_len)
	Return true if a request header value is equal to a string. More...
bool	http_req_hdr_contains (struct req *req, const char *name, size_t name_len, const char *substring, size_t substring_len)
	Return true if a request header contains a string. More...
static bool	http_req_hdr_eq_str (struct req *req, const char *name, const char *val)
	Return true if a request header value is equal to a nul-terminated string. More...
static bool	http_req_hdr_contains_str (struct req *req, const char *name, const char *substring)
	Return true if a request header contains a nul-terminated string. More...
err_t	http_req_hdr_iter (struct req *req, name_val_iter_f iter_cb, void *priv)
	Iterate over request headers. More...
const uint8_t *	http_req_cookie (struct req *req, const char *name, size_t name_len, size_t *val_len)
	Return the value of a cookie. More...
static const uint8_t *	http_req_cookie_str (struct req *req, const char *name, size_t *val_len)
	Return the value of a cookie with a nul-terminated name. More...
err_t	http_req_cookie_iter (struct req *req, name_val_iter_f iter_cb, void *priv)
	Iterate over cooke name/value pairs. More...
static enum http_method_t	http_req_method (struct req *req)
	Return the request method. More...
static const uint8_t *	http_req_path (struct req *req, size_t *len)
	Return the path from the first request line. More...
static const uint8_t *	http_req_query (struct req *req, size_t *len)
	Return the request query string. More...
const uint8_t *	http_req_query_val (const uint8_t *query, size_t query_len, const uint8_t *name, size_t name_len, size_t *val_len)
	Return the value of a query parameter. More...
err_t	http_req_query_iter (const uint8_t *query, size_t len, name_val_iter_f iter_cb, void *priv)
	Iterate over query string parameter names and values. More...
static size_t	http_req_body_len (struct req *req)
	Return the length of the request body. More...
err_t	http_req_body (struct http *http, uint8_t buf[], size_t *len, size_t off)
	Copy the request body to a buffer. More...
err_t	http_req_body_ptr (struct http *http, const uint8_t **buf, size_t *len, size_t off)
	Get a pointer to request body contents with zero-copy. More...
err_t	http_req_chunk (struct http *http, uint8_t *buf, size_t *len)
	Copy the next chunk in a request body sent with chunked encdoding. More...
static struct resp *	http_resp (struct http *http)
	Get the current response object. More...
static err_t	http_resp_set_status (struct resp *resp, uint16_t status)
	Set the response status code. More...
static uint16_t	http_resp_status (struct resp *resp)
	Get the response status code. More...
err_t	http_resp_set_hdr (struct resp *resp, const char *name, size_t name_len, const char *val, size_t val_len)
	Set a response header. More...
static err_t	http_resp_set_hdr_str (struct resp *resp, const char *name, const char *val)
	Set a response header to a nul-terminated string. More...
static err_t	http_resp_set_type (struct resp *resp, const char *type, size_t type_len)
	Set the Content-Type response header. More...
static err_t	http_resp_set_type_str (struct resp *resp, const char *type)
	Set the Content-Type response header to a nul-terminated string. More...
err_t	http_resp_set_len (struct resp *resp, size_t len)
	Set the Content-Length response header. More...
static err_t	http_resp_set_xfer_chunked (struct resp *resp)
	Set the Transfer-Encdoing response header to "chunked". More...
err_t	http_resp_send_hdr (struct http *http)
	Send the response header. More...
err_t	http_resp_send_buf (struct http *http, const uint8_t *buf, size_t len, bool durable)
	Send the contents of a buffer as the response body. More...
err_t	http_resp_send_chunk (struct http *http, const uint8_t *buf, size_t len, bool durable)
	Send a chunk in a chunked-encoded response body. More...
static err_t	http_resp_err (struct http *http, uint16_t status)
	Send an error response. More...
err_t	register_hndlr_methods (struct server_cfg *cfg, const char *path, hndlr_f hndlr, uint8_t methods, void *priv)
	Register a response handler for request methods and a path. More...
static err_t	register_hndlr (struct server_cfg *cfg, const char *path, hndlr_f hndlr, enum http_method_t method, void *priv)
	Register a response handler for a request method and path. More...
err_t	register_default_hndlr (struct server_cfg *cfg, hndlr_f hndlr, void *priv, priv_fini_f fini)
	Register a default response handler. More...
err_t	register_error_hndlr (struct server_cfg *cfg, hndlr_f hndlr, void *priv, priv_fini_f fini)
	Register a custom error response handler. More...
err_t	format_decimal (char *s, size_t *len, int32_t n)
	Format a decimal number. More...
err_t	format_hex (char *s, size_t *len, uint32_t n, bool upper)
	Format a hexadecimal number. More...
err_t	url_decode (char *const out, size_t *outlen, const char *const in, ssize_t inlen, bool plus)
	Decode a "percent-encoded" string. More...
err_t	hex_decode (const char *const buf, ssize_t len, uint64_t *n)
	Decode a hexadecimal string. More...

Detailed Description

Public API of the picow-http server.

This API may be used to configure, start and stop an HTTP server; and to implement custom handlers, which generate dynamic HTTP responses.