evhttp.h File Reference

Basic support for HTTP serving. More...

#include <event.h>

Go to the source code of this file.

Data Structures

struct  evhttp_request
 the request structure that a server receives. More...

Defines

#define EVHTTP_PROXY_REQUEST   0x0002
#define EVHTTP_REQ_OWN_CONNECTION   0x0001
#define HTTP_BADREQUEST   400
#define HTTP_MOVEPERM   301
#define HTTP_MOVETEMP   302
#define HTTP_NOCONTENT   204
#define HTTP_NOTFOUND   404
#define HTTP_NOTMODIFIED   304
#define HTTP_OK   200
#define HTTP_SERVUNAVAIL   503

Enumerations

enum  evhttp_cmd_type { EVHTTP_REQ_GET, EVHTTP_REQ_POST, EVHTTP_REQ_HEAD }
enum  evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE }

Functions

int evhttp_accept_socket (struct evhttp *http, int fd)
 Makes an HTTP server accept connections on the specified socket.
int evhttp_add_header (struct evkeyvalq *, const char *, const char *)
int evhttp_bind_socket (struct evhttp *http, const char *address, u_short port)
 Binds an HTTP server on the specified address and port.
void evhttp_clear_headers (struct evkeyvalq *)
void evhttp_connection_free (struct evhttp_connection *evcon)
 Frees an http connection.
void evhttp_connection_get_peer (struct evhttp_connection *evcon, char **address, u_short *port)
 Get the remote address and port associated with this connection.
struct evhttp_connection * evhttp_connection_new (const char *address, unsigned short port)
 A connection object that can be used to for making HTTP requests.
void evhttp_connection_set_base (struct evhttp_connection *evcon, struct event_base *base)
 Associates an event base with the connection - can only be called on a freshly created connection object that has not been used yet.
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, unsigned short 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 *, const char *)
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)
 The connection gets ownership of the request.
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 *, const char *)
void evhttp_request_free (struct evhttp_request *req)
 Frees the request object and removes associated events.
struct evhttp_requestevhttp_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_set_chunked_cb (struct evhttp_request *, void(*cb)(struct evhttp_request *, void *))
 enable delivery of chunks to requestor
const char * evhttp_request_uri (struct evhttp_request *req)
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 *, struct evbuffer *)
void evhttp_send_reply_end (struct evhttp_request *)
void evhttp_send_reply_start (struct evhttp_request *, int, const char *)
void evhttp_set_cb (struct evhttp *, const char *, void(*)(struct evhttp_request *, void *), void *)
 Set a callback for a specified URI.
void evhttp_set_gencb (struct evhttp *, void(*)(struct evhttp_request *, void *), void *)
 Set a callback for all requests that are not caught by specific callbacks.
void evhttp_set_timeout (struct evhttp *, int timeout_in_secs)
 Set the timeout for an HTTP request.
struct evhttp * evhttp_start (const char *address, u_short port)
 Start an HTTP server on the specified address and port.


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,
int  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_bind_socket ( struct evhttp *  http,
const char *  address,
u_short  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:
a newly allocated evhttp struct
See also:
evhttp_free()

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

Get the remote address and port associated with this connection.

struct evhttp_connection* evhttp_connection_new ( 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_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

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

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

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_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.

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_set_timeout ( struct evhttp *  ,
int  timeout_in_secs 
)

Set the timeout for an HTTP request.

Parameters:
http an evhttp object
timeout_in_secs the timeout, in seconds

struct evhttp* evhttp_start ( const char *  address,
u_short  port 
) [read]

Start an HTTP server on the specified address and port.

DEPRECATED: it does not allow an event base to be specified

Parameters:
address the address to which the HTTP server should be bound
port the port number on which the HTTP server should listen
Returns:
an struct evhttp object


Generated on Fri Apr 17 21:20:18 2009 for libevent by  doxygen 1.5.7