* Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
* Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#ifndef EVENT2_HTTP_H_INCLUDED_
#define EVENT2_HTTP_H_INCLUDED_
#include <event2/visibility.h>
/* In case we haven't included the right headers yet. */
struct evhttp_connection;
* 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.
#define HTTP_OK 200 /**< request completed ok */
#define HTTP_NOCONTENT 204 /**< request does not have content */
#define HTTP_MOVEPERM 301 /**< the uri moved permanently */
#define HTTP_MOVETEMP 302 /**< the uri moved temporarily */
#define HTTP_NOTMODIFIED 304 /**< page was not modified from last */
#define HTTP_BADREQUEST 400 /**< invalid http request was made */
#define HTTP_NOTFOUND 404 /**< could not find content for uri */
#define HTTP_BADMETHOD 405 /**< method not allowed for this uri */
#define HTTP_ENTITYTOOLARGE 413 /**< */
#define HTTP_EXPECTATIONFAILED 417 /**< we can't handle this expectation */
#define HTTP_INTERNAL 500 /**< internal error */
#define HTTP_NOTIMPLEMENTED 501 /**< not implemented */
#define HTTP_SERVUNAVAIL 503 /**< the server is not available */
struct evhttp_bound_socket;
* Create a new HTTP server.
* @param base (optional) the event base to receive the HTTP events
* @return a pointer to a newly initialized evhttp server structure
struct evhttp *evhttp_new(struct event_base *base);
* 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.
* @param http a pointer to an evhttp object
* @param address a string containing the IP address to listen(2) on
* @param port the port number to listen on
* @return 0 on success, -1 on failure.
* @see evhttp_accept_socket()
int evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port);
* Like evhttp_bind_socket(), but returns a handle for referencing the socket.
* The returned pointer is not valid after \a http is freed.
* @param http a pointer to an evhttp object
* @param address a string containing the IP address to listen(2) on
* @param port the port number to listen on
* @return Handle for the socket on success, NULL on failure.
* @see evhttp_bind_socket(), evhttp_del_accept_socket()
struct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port);
* 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.
* @param http a pointer to an evhttp object
* @param fd a socket fd that is ready for accepting connections
* @return 0 on success, -1 on failure.
* @see evhttp_bind_socket()
int evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd);
* Like evhttp_accept_socket(), but returns a handle for referencing the socket.
* The returned pointer is not valid after \a http is freed.
* @param http a pointer to an evhttp object
* @param fd a socket fd that is ready for accepting connections
* @return Handle for the socket on success, NULL on failure.
* @see evhttp_accept_socket(), evhttp_del_accept_socket()
struct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd);
* The most low-level evhttp_bind/accept method: takes an evconnlistener, and
* returns an evhttp_bound_socket. The listener will be freed when the bound
struct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener);
* Return the listener used to implement a bound socket.
struct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound);
typedef void evhttp_bound_socket_foreach_fn(struct evhttp_bound_socket *, void *);
* Applies the function specified in the first argument to all
* evhttp_bound_sockets associated with "http". The user must not
* attempt to free or remove any connections, sockets or listeners
* in the callback "function".
* @param http pointer to an evhttp object
* @param function function to apply to every bound socket
* @param argument pointer value passed to function for every socket iterated
void evhttp_foreach_bound_socket(struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument);
* Makes an HTTP server stop accepting connections on the specified socket
* This may be useful when a socket has been sent via file descriptor passing
* and is no longer needed by the current process.
* If you created this bound socket with evhttp_bind_socket_with_handle or
* evhttp_accept_socket_with_handle, this function closes the fd you provided.
* If you created this bound socket with evhttp_bind_listener, this function
* frees the listener you provided.
* \a bound_socket is an invalid pointer after this call returns.
* @param http a pointer to an evhttp object
* @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
* @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
void evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket);
* Get the raw file descriptor referenced by an evhttp_bound_socket.
* @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
* @return the file descriptor used by the bound socket
* @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
evutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket);
* Free the previously created HTTP server.
* Works only if no requests are currently being served.
* @param http the evhttp server object to be freed
void evhttp_free(struct evhttp* http);
void evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size);
void evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size);
Set the value to use for the Content-Type header when none was provided. If
the content type string is NULL, the Content-Type header will not be
@param http the http server on which to set the default content type
@param content_type the value for the Content-Type header
void evhttp_set_default_content_type(struct evhttp *http,
const char *content_type);
Sets the what HTTP methods are supported in requests accepted by this
server, and passed to user callbacks.
If not supported they will generate a "405 Method not allowed" response.
By default this includes the following methods: GET, POST, HEAD, PUT, DELETE
@param http the http server on which to set the methods
@param methods bit mask constructed from evhttp_cmd_type values
void evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods);
Set a callback for a specified URI
@param http the http sever on which to set the callback
@param path the path for which to invoke the callback
@param cb the callback function that gets invoked on requesting path
@param cb_arg an additional context argument for the callback
@return 0 on success, -1 if the callback existed already, -2 on failure
int evhttp_set_cb(struct evhttp *http, const char *path,
void (*cb)(struct evhttp_request *, void *), void *cb_arg);
/** Removes the callback for a specified URI */
int evhttp_del_cb(struct evhttp *, const char *);
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().
@param http the evhttp server object for which to set the callback
@param cb the callback to invoke for any unmatched requests
@param arg an context argument for the callback
void evhttp_set_gencb(struct evhttp *http,
void (*cb)(struct evhttp_request *, void *), void *arg);
Set a callback used to create new bufferevents for connections
to a given evhttp object.
You can use this to override the default bufferevent type -- for example,
to make this evhttp object use SSL bufferevents rather than unencrypted
New bufferevents must be allocated with no fd set on them.
@param http the evhttp server object for which to set the callback
@param cb the callback to invoke for incoming connections
@param arg an context argument for the callback
void evhttp_set_bevcb(struct evhttp *http,
struct bufferevent *(*cb)(struct event_base *, void *), void *arg);
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.
@param http the evhttp object to which to add a virtual host
@param pattern the glob pattern against which the hostname is matched.
The match is case insensitive and follows otherwise regular shell
@param vhost the virtual host to add the regular http server.
@return 0 on success, -1 on failure
@see evhttp_remove_virtual_host()
int evhttp_add_virtual_host(struct evhttp* http, const char *pattern,
Removes a virtual host from the http server.
@param http the evhttp object from which to remove the virtual host
@param vhost the virtual host to remove from the regular http server.
@return 0 on success, -1 on failure
@see evhttp_add_virtual_host()
int evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost);
Add a server alias to an http object. The http object can be a virtual
@param http the evhttp object
@param alias the alias to add
@see evhttp_add_remove_alias()
int evhttp_add_server_alias(struct evhttp *http, const char *alias);
Remove a server alias from an http object.
@param http the evhttp object
@param alias the alias to remove
@see evhttp_add_server_alias()
int evhttp_remove_server_alias(struct evhttp *http, const char *alias);
* Set the timeout for an HTTP request.
* @param http an evhttp object
* @param timeout_in_secs the timeout, in seconds
void evhttp_set_timeout(struct evhttp *http, int timeout_in_secs);
* Set the timeout for an HTTP request.
* @param http an evhttp object
* @param tv the timeout, or NULL
void evhttp_set_timeout_tv(struct evhttp *http, const struct timeval* tv);
/* Read all the clients body, and only after this respond with an error if the
* clients body exceed max_body_size */
#define EVHTTP_SERVER_LINGERING_CLOSE 0x0001
* Set connection flags for HTTP server.
* @return 0 on success, otherwise non zero (for example if flag doesn't
int evhttp_set_flags(struct evhttp *http, int flags);
/* Request/Response functionality */
* Send an HTML error message to the client.
* @param req a request object
* @param error the HTTP error code
* @param reason a brief explanation of the error. If this is NULL, we'll
* just use the standard meaning of the error code.
void evhttp_send_error(struct evhttp_request *req, int error,
* 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
* @param req a request object
* @param code the HTTP response code to send
* @param reason a brief message to send with the response code
* @param databuf the body of the response
void evhttp_send_reply(struct evhttp_request *req, int code,
const char *reason, struct evbuffer *databuf);
/* Low-level response interface, for streaming/chunked replies */
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().
@param req a request object
@param code the HTTP response code to send
@param reason a brief message to send with the response code
void evhttp_send_reply_start(struct evhttp_request *req, int code,
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
@param req a request object
@param databuf the data chunk to send as part of the reply.
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
@param req a request object
@param databuf the data chunk to send as part of the reply.
@param cb callback funcion
@param call back's argument.
void evhttp_send_reply_chunk_with_cb(struct evhttp_request *, struct evbuffer *,
void (*cb)(struct evhttp_connection *, void *), void *arg);
Complete a chunked reply, freeing the request as appropriate.
@param req a request object
void evhttp_send_reply_end(struct evhttp_request *req);
* Interfaces for making requests
/** The different request types supported by evhttp. These are as specified
* in RFC2616, except for PATCH which is specified by RFC5789.
* By default, only some of these methods are accepted and passed to user
* callbacks; use evhttp_set_allowed_methods() to change which methods
EVHTTP_REQ_POST = 1 << 1,
EVHTTP_REQ_HEAD = 1 << 2,
EVHTTP_REQ_DELETE = 1 << 4,
EVHTTP_REQ_OPTIONS = 1 << 5,
EVHTTP_REQ_TRACE = 1 << 6,
EVHTTP_REQ_CONNECT = 1 << 7,
EVHTTP_REQ_PATCH = 1 << 8
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
