include/event2/http.h File Reference

Basic support for HTTP serving. More...

#include <event2/util.h>

Go to the source code of this file.

Defines
#define	HTTP_BADREQUEST   400
	invalid http request was made
#define	HTTP_MOVEPERM   301
	the uri moved permanently
#define	HTTP_MOVETEMP   302
	the uri moved temporarily
#define	HTTP_NOCONTENT   204
	request does not have content
#define	HTTP_NOTFOUND   404
	could not find content for uri
#define	HTTP_NOTMODIFIED   304
	page was not modified from last
#define	HTTP_OK   200
	request completed ok
#define	HTTP_SERVUNAVAIL   503
	the server is not available
Enumerations
enum	evhttp_cmd_type {   EVHTTP_REQ_GET, EVHTTP_REQ_POST, EVHTTP_REQ_HEAD, EVHTTP_REQ_PUT,   EVHTTP_REQ_DELETE }
	the different request types supported by evhttp
enum	evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE }
	a request object can represent either a request or a reply
Functions
int	evhttp_accept_socket (struct evhttp *http, evutil_socket_t fd)
	Makes an HTTP server accept connections on the specified socket.
int	evhttp_add_header (struct evkeyvalq *headers, const char *key, const char *value)
	Adds a header to a list of exisiting headers.
int	evhttp_add_virtual_host (struct evhttp *http, const char *pattern, struct evhttp *vhost)
	Adds a virtual host to the http server.
int	evhttp_bind_socket (struct evhttp *http, const char *address, ev_uint16_t port)
	Binds an HTTP server on the specified address and port.
void	evhttp_cancel_request (struct evhttp_request *req)
	Cancels a pending HTTP request.
void	evhttp_clear_headers (struct evkeyvalq *headers)
	Removes all headers from the header list.
struct evhttp_connection *	evhttp_connection_base_new (struct event_base *base, const char *address, unsigned short port)
	A connection object that can be used to for making HTTP requests.
void	evhttp_connection_free (struct evhttp_connection *evcon)
	Frees an http connection.
void	evhttp_connection_get_peer (struct evhttp_connection *evcon, char **address, ev_uint16_t *port)
	Get the remote address and port associated with this connection.
void	evhttp_connection_set_closecb (struct evhttp_connection *evcon, void(*)(struct evhttp_connection *, void *), void *)
	Set a callback for connection close.
void	evhttp_connection_set_local_address (struct evhttp_connection *evcon, const char *address)
	sets the ip address from which http connections are made
void	evhttp_connection_set_local_port (struct evhttp_connection *evcon, ev_uint16_t port)
	sets the local port from which http connections are made
void	evhttp_connection_set_retries (struct evhttp_connection *evcon, int retry_max)
	Sets the retry limit for this connection - -1 repeats indefnitely.
void	evhttp_connection_set_timeout (struct evhttp_connection *evcon, int timeout_in_secs)
	Sets the timeout for events related to this connection.
char *	evhttp_decode_uri (const char *uri)
	Helper function to decode a URI.
int	evhttp_del_cb (struct evhttp *, const char *)
	Removes the callback for a specified URI.
char *	evhttp_encode_uri (const char *uri)
	Helper function to encode a URI.
const char *	evhttp_find_header (const struct evkeyvalq *headers, const char *key)
	Finds the value belonging to a header.
void	evhttp_free (struct evhttp *http)
	Free the previously created HTTP server.
char *	evhttp_htmlescape (const char *html)
	Escape HTML character entities in a string.
int	evhttp_make_request (struct evhttp_connection *evcon, struct evhttp_request *req, enum evhttp_cmd_type type, const char *uri)
	Make an HTTP request over the specified connection.
struct evhttp *	evhttp_new (struct event_base *base)
	Create a new HTTP server.
void	evhttp_parse_query (const char *uri, struct evkeyvalq *headers)
	Helper function to parse out arguments in a query.
int	evhttp_remove_header (struct evkeyvalq *headers, const char *key)
	Removes a header from a list of exisiting headers.
int	evhttp_remove_virtual_host (struct evhttp *http, struct evhttp *vhost)
	Removes a virtual host from the http server.
void	evhttp_request_free (struct evhttp_request *req)
	Frees the request object and removes associated events.
struct evbuffer *	evhttp_request_get_input_buffer (struct evhttp_request *req)
	Returns the input buffer.
struct evkeyvalq *	evhttp_request_get_input_headers (struct evhttp_request *req)
	Returns the input headers.
struct evbuffer *	evhttp_request_get_output_buffer (struct evhttp_request *req)
	Returns the output buffer.
struct evkeyvalq *	evhttp_request_get_output_headers (struct evhttp_request *req)
	Returns the output headers.
const char *	evhttp_request_get_uri (struct evhttp_request *req)
	Returns the request URI.
int	evhttp_request_is_owned (struct evhttp_request *req)
	Returns 1 if the request is owned by the user.
struct evhttp_request *	evhttp_request_new (void(*cb)(struct evhttp_request *, void *), void *arg)
	Creates a new request object that needs to be filled in with the request parameters.
void	evhttp_request_own (struct evhttp_request *req)
	Takes ownership of the request object.
void	evhttp_request_set_chunked_cb (struct evhttp_request *, void(*cb)(struct evhttp_request *, void *))
	Enable delivery of chunks to requestor.
void	evhttp_send_error (struct evhttp_request *req, int error, const char *reason)
	Send an HTML error message to the client.
void	evhttp_send_reply (struct evhttp_request *req, int code, const char *reason, struct evbuffer *databuf)
	Send an HTML reply to the client.
void	evhttp_send_reply_chunk (struct evhttp_request *req, struct evbuffer *databuf)
	Send another data chunk as part of an ongoing chunked reply.
void	evhttp_send_reply_end (struct evhttp_request *req)
	Complete a chunked reply.
void	evhttp_send_reply_start (struct evhttp_request *req, int code, const char *reason)
	Initiate a reply that uses Transfer-Encoding chunked.
int	evhttp_set_cb (struct evhttp *http, const char *path, void(*cb)(struct evhttp_request *, void *), void *cb_arg)
	Set a callback for a specified URI.
void	evhttp_set_gencb (struct evhttp *http, void(*cb)(struct evhttp_request *, void *), void *arg)
	Set a callback for all requests that are not caught by specific callbacks.
void	evhttp_set_timeout (struct evhttp *http, int timeout_in_secs)
	Set the timeout for an HTTP request.

---

Detailed Description

Basic support for HTTP serving.

As libevent is a library for dealing with event notification and most interesting applications are networked today, I have often found the need to write HTTP code. The following prototypes and definitions provide an application with a minimal interface for making HTTP requests and for creating a very simple HTTP server.

---

Function Documentation

int evhttp_accept_socket	(	struct evhttp *	http,
		evutil_socket_t	fd
	)

Makes an HTTP server accept connections on the specified socket.

This may be useful to create a socket and then fork multiple instances of an http server, or when a socket has been communicated via file descriptor passing in situations where an http servers does not have permissions to bind to a low-numbered port.

Can be called multiple times to have the http server listen to multiple different sockets.

Parameters:

	http	a pointer to an evhttp object
	fd	a socket fd that is ready for accepting connections

Returns:

0 on success, -1 on failure.

See also:

evhttp_free(), evhttp_bind_socket()

int evhttp_add_header	(	struct evkeyvalq *	headers,
		const char *	key,
		const char *	value
	)

Adds a header to a list of exisiting headers.

Parameters:

	headers	the evkeyvalq object to which to add a header
	key	the name of the header
	value	the value belonging to the header

Returns:

0 on success, -1 otherwise.

See also:

evhttp_find_header(), evhttp_clear_headers()

int evhttp_add_virtual_host	(	struct evhttp *	http,
		const char *	pattern,
		struct evhttp *	vhost
	)

Adds a virtual host to the http server.

A virtual host is a newly initialized evhttp object that has request callbacks set on it via evhttp_set_cb() or evhttp_set_gencb(). It most not have any listing sockets associated with it.

If the virtual host has not been removed by the time that evhttp_free() is called on the main http server, it will be automatically freed, too.

It is possible to have hierarchical vhosts. For example: A vhost with the pattern *.example.com may have other vhosts with patterns foo.example.com and bar.example.com associated with it.

Parameters:

	http	the evhttp object to which to add a virtual host
	pattern	the glob pattern against which the hostname is matched. The match is case insensitive and follows otherwise regular shell matching.
	vhost	the virtual host to add the regular http server.

Returns:

0 on success, -1 on failure

See also:

evhttp_remove_virtual_host()

int evhttp_bind_socket	(	struct evhttp *	http,
		const char *	address,
		ev_uint16_t	port
	)

Binds an HTTP server on the specified address and port.

Can be called multiple times to bind the same http server to multiple different ports.

Parameters:

	http	a pointer to an evhttp object
	address	a string containing the IP address to listen(2) on
	port	the port number to listen on

Returns:

0 on success, -1 on failure.

See also:

evhttp_free(), evhttp_accept_socket()

void evhttp_cancel_request

(

struct evhttp_request *

req

)

Cancels a pending HTTP request.

Cancels an ongoing HTTP request. The callback associated with this request is not executed and the request object is freed. If the request is currently being processed, e.g. it is ongoing, the corresponding evhttp_connection object is going to get reset.

A request cannot be canceled if its callback has executed already. A request may be canceled reentrantly from its chunked callback.

Parameters:

req

the evhttp_request to cancel; req becomes invalid after this call.

void evhttp_clear_headers

(

struct evkeyvalq *

headers

)

Removes all headers from the header list.

Parameters:

headers

the evkeyvalq object from which to remove all headers

struct evhttp_connection* evhttp_connection_base_new	(	struct event_base *	base,
		const char *	address,
		unsigned short	port
	)			[read]

A connection object that can be used to for making HTTP requests.

The connection object tries to establish the connection when it is given an http request object.

void evhttp_connection_get_peer	(	struct evhttp_connection *	evcon,
		char **	address,
		ev_uint16_t *	port
	)

Get the remote address and port associated with this connection.

void evhttp_connection_set_closecb	(	struct evhttp_connection *	evcon,
		void(*)(struct evhttp_connection *, void *)	,
		void *
	)

Set a callback for connection close.

char* evhttp_decode_uri

(

const char *

uri

)

Helper function to decode a URI.

The returned string must be freed by the caller.

Parameters:

uri

an encoded URI

Returns:

a newly allocated unencoded URI

char* evhttp_encode_uri

(

const char *

uri

)

Helper function to encode a URI.

The returned string must be freed by the caller.

Parameters:

uri

an unencoded URI

Returns:

a newly allocated URI-encoded string

const char* evhttp_find_header	(	const struct evkeyvalq *	headers,
		const char *	key
	)

Finds the value belonging to a header.

Parameters:

	headers	the evkeyvalq object in which to find the header
	key	the name of the header to find

Returns:

a pointer to the value for the header or NULL if the header count not be found.

See also:

evhttp_add_header(), evhttp_remove_header()

void evhttp_free

(

struct evhttp *

http

)

Free the previously created HTTP server.

Works only if no requests are currently being served.

Parameters:

http

the evhttp server object to be freed

See also:

evhttp_start()

char* evhttp_htmlescape

(

const char *

html

)

Escape HTML character entities in a string.

Replaces <, >, ", ' and & with <, >, ", &#039; and & correspondingly.

The returned string needs to be freed by the caller.

Parameters:

html

an unescaped HTML string

Returns:

an escaped HTML string

int evhttp_make_request	(	struct evhttp_connection *	evcon,
		struct evhttp_request *	req,
		enum evhttp_cmd_type	type,
		const char *	uri
	)

Make an HTTP request over the specified connection.

The connection gets ownership of the request.

Parameters:

	evcon	the evhttp_connection object over which to send the request
	req	the previously created and configured request object
	type	the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc.
	uri	the URI associated with the request

Returns:

0 on success, -1 on failure

See also:

evhttp_cancel_request()

struct evhttp* evhttp_new

(

struct event_base *

base

)

[read]

Create a new HTTP server.

Parameters:

base

(optional) the event base to receive the HTTP events

Returns:

a pointer to a newly initialized evhttp server structure

void evhttp_parse_query	(	const char *	uri,
		struct evkeyvalq *	headers
	)

Helper function to parse out arguments in a query.

Parsing a uri like

http://foo.com/?q=test&s=some+thing

will result in two entries in the key value queue.

The first entry is: key="q", value="test" The second entry is: key="s", value="some thing"

Parameters:

	uri	the request URI
	headers	the head of the evkeyval queue

int evhttp_remove_header	(	struct evkeyvalq *	headers,
		const char *	key
	)

Removes a header from a list of exisiting headers.

Parameters:

	headers	the evkeyvalq object from which to remove a header
	key	the name of the header to remove

Returns:

0 if the header was removed, -1 otherwise.

See also:

evhttp_find_header(), evhttp_add_header()

int evhttp_remove_virtual_host	(	struct evhttp *	http,
		struct evhttp *	vhost
	)

Removes a virtual host from the http server.

Parameters:

	http	the evhttp object from which to remove the virtual host
	vhost	the virtual host to remove from the regular http server.

Returns:

0 on success, -1 on failure

See also:

evhttp_add_virtual_host()

void evhttp_request_free

(

struct evhttp_request *

req

)

Frees the request object and removes associated events.

struct evhttp_request* evhttp_request_new	(	void(*)(struct evhttp_request *, void *)	cb,
		void *	arg
	)			[read]

Creates a new request object that needs to be filled in with the request parameters.

The callback is executed when the request completed or an error occurred.

void evhttp_request_own

(

struct evhttp_request *

req

)

Takes ownership of the request object.

Can be used in a request callback to keep onto the request until evhttp_request_free() is explicitly called by the user.

void evhttp_request_set_chunked_cb	(	struct evhttp_request *	,
		void(*)(struct evhttp_request *, void *)	cb
	)

Enable delivery of chunks to requestor.

Parameters:

cb

will be called after every read of data with the same argument as the completion callback. Will never be called on an empty response. May drain the input buffer; it will be drained automatically on return.

void evhttp_send_error	(	struct evhttp_request *	req,
		int	error,
		const char *	reason
	)

Send an HTML error message to the client.

Parameters:

	req	a request object
	error	the HTTP error code
	reason	a brief explanation of the error

void evhttp_send_reply	(	struct evhttp_request *	req,
		int	code,
		const char *	reason,
		struct evbuffer *	databuf
	)

Send an HTML reply to the client.

The body of the reply consists of the data in databuf. After calling evhttp_send_reply() databuf will be empty, but the buffer is still owned by the caller and needs to be deallocated by the caller if necessary.

Parameters:

	req	a request object
	code	the HTTP response code to send
	reason	a brief message to send with the response code
	databuf	the body of the response

void evhttp_send_reply_chunk	(	struct evhttp_request *	req,
		struct evbuffer *	databuf
	)

Send another data chunk as part of an ongoing chunked reply.

The reply chunk consists of the data in databuf. After calling evhttp_send_reply_chunk() databuf will be empty, but the buffer is still owned by the caller and needs to be deallocated by the caller if necessary.

Parameters:

	req	a request object
	databuf	the data chunk to send as part of the reply.

void evhttp_send_reply_end

(

struct evhttp_request *

req

)

Complete a chunked reply.

Parameters:

req

a request object

void evhttp_send_reply_start	(	struct evhttp_request *	req,
		int	code,
		const char *	reason
	)

Initiate a reply that uses Transfer-Encoding chunked.

This allows the caller to stream the reply back to the client and is useful when either not all of the reply data is immediately available or when sending very large replies.

The caller needs to supply data chunks with evhttp_send_reply_chunk() and complete the reply by calling evhttp_send_reply_end().

Parameters:

	req	a request object
	code	the HTTP response code to send
	reason	a brief message to send with the response code

int evhttp_set_cb	(	struct evhttp *	http,
		const char *	path,
		void(*)(struct evhttp_request *, void *)	cb,
		void *	cb_arg
	)

Set a callback for a specified URI.

Parameters:

	http	the http sever on which to set the callback
	path	the path for which to invoke the callback
	cb	the callback function that gets invoked on requesting path
	cb_arg	an additional context argument for the callback

Returns:

0 on success, -1 if the callback existed already

void evhttp_set_gencb	(	struct evhttp *	http,
		void(*)(struct evhttp_request *, void *)	cb,
		void *	arg
	)

Set a callback for all requests that are not caught by specific callbacks.

Invokes the specified callback for all requests that do not match any of the previously specified request paths. This is catchall for requests not specifically configured with evhttp_set_cb().

Parameters:

	http	the evhttp server object for which to set the callback
	cb	the callback to invoke for any unmatched requests
	arg	an context argument for the callback

void evhttp_set_timeout	(	struct evhttp *	http,
		int	timeout_in_secs
	)

Set the timeout for an HTTP request.

Parameters:

	http	an evhttp object
	timeout_in_secs	the timeout, in seconds