1290001Sglebius/* 2290001Sglebius * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3290001Sglebius * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4290001Sglebius * 5290001Sglebius * Redistribution and use in source and binary forms, with or without 6290001Sglebius * modification, are permitted provided that the following conditions 7290001Sglebius * are met: 8290001Sglebius * 1. Redistributions of source code must retain the above copyright 9290001Sglebius * notice, this list of conditions and the following disclaimer. 10290001Sglebius * 2. Redistributions in binary form must reproduce the above copyright 11290001Sglebius * notice, this list of conditions and the following disclaimer in the 12290001Sglebius * documentation and/or other materials provided with the distribution. 13290001Sglebius * 3. The name of the author may not be used to endorse or promote products 14290001Sglebius * derived from this software without specific prior written permission. 15290001Sglebius * 16290001Sglebius * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17290001Sglebius * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18290001Sglebius * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19290001Sglebius * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20290001Sglebius * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21290001Sglebius * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22290001Sglebius * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23290001Sglebius * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24290001Sglebius * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25290001Sglebius * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26290001Sglebius */ 27290001Sglebius#ifndef EVENT2_HTTP_H_INCLUDED_ 28290001Sglebius#define EVENT2_HTTP_H_INCLUDED_ 29290001Sglebius 30290001Sglebius/* For int types. */ 31290001Sglebius#include <event2/util.h> 32290001Sglebius#include <event2/visibility.h> 33290001Sglebius 34290001Sglebius#ifdef __cplusplus 35290001Sglebiusextern "C" { 36290001Sglebius#endif 37290001Sglebius 38290001Sglebius/* In case we haven't included the right headers yet. */ 39290001Sglebiusstruct evbuffer; 40290001Sglebiusstruct event_base; 41290001Sglebiusstruct bufferevent; 42290001Sglebiusstruct evhttp_connection; 43290001Sglebius 44290001Sglebius/** @file event2/http.h 45290001Sglebius * 46290001Sglebius * Basic support for HTTP serving. 47290001Sglebius * 48290001Sglebius * As Libevent is a library for dealing with event notification and most 49290001Sglebius * interesting applications are networked today, I have often found the 50290001Sglebius * need to write HTTP code. The following prototypes and definitions provide 51290001Sglebius * an application with a minimal interface for making HTTP requests and for 52290001Sglebius * creating a very simple HTTP server. 53290001Sglebius */ 54290001Sglebius 55290001Sglebius/* Response codes */ 56290001Sglebius#define HTTP_OK 200 /**< request completed ok */ 57290001Sglebius#define HTTP_NOCONTENT 204 /**< request does not have content */ 58290001Sglebius#define HTTP_MOVEPERM 301 /**< the uri moved permanently */ 59290001Sglebius#define HTTP_MOVETEMP 302 /**< the uri moved temporarily */ 60290001Sglebius#define HTTP_NOTMODIFIED 304 /**< page was not modified from last */ 61290001Sglebius#define HTTP_BADREQUEST 400 /**< invalid http request was made */ 62290001Sglebius#define HTTP_NOTFOUND 404 /**< could not find content for uri */ 63290001Sglebius#define HTTP_BADMETHOD 405 /**< method not allowed for this uri */ 64290001Sglebius#define HTTP_ENTITYTOOLARGE 413 /**< */ 65290001Sglebius#define HTTP_EXPECTATIONFAILED 417 /**< we can't handle this expectation */ 66290001Sglebius#define HTTP_INTERNAL 500 /**< internal error */ 67290001Sglebius#define HTTP_NOTIMPLEMENTED 501 /**< not implemented */ 68290001Sglebius#define HTTP_SERVUNAVAIL 503 /**< the server is not available */ 69290001Sglebius 70290001Sglebiusstruct evhttp; 71290001Sglebiusstruct evhttp_request; 72290001Sglebiusstruct evkeyvalq; 73290001Sglebiusstruct evhttp_bound_socket; 74290001Sglebiusstruct evconnlistener; 75290001Sglebiusstruct evdns_base; 76290001Sglebius 77290001Sglebius/** 78290001Sglebius * Create a new HTTP server. 79290001Sglebius * 80290001Sglebius * @param base (optional) the event base to receive the HTTP events 81290001Sglebius * @return a pointer to a newly initialized evhttp server structure 82290001Sglebius * @see evhttp_free() 83290001Sglebius */ 84290001SglebiusEVENT2_EXPORT_SYMBOL 85290001Sglebiusstruct evhttp *evhttp_new(struct event_base *base); 86290001Sglebius 87290001Sglebius/** 88290001Sglebius * Binds an HTTP server on the specified address and port. 89290001Sglebius * 90290001Sglebius * Can be called multiple times to bind the same http server 91290001Sglebius * to multiple different ports. 92290001Sglebius * 93290001Sglebius * @param http a pointer to an evhttp object 94290001Sglebius * @param address a string containing the IP address to listen(2) on 95290001Sglebius * @param port the port number to listen on 96290001Sglebius * @return 0 on success, -1 on failure. 97290001Sglebius * @see evhttp_accept_socket() 98290001Sglebius */ 99290001SglebiusEVENT2_EXPORT_SYMBOL 100290001Sglebiusint evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port); 101290001Sglebius 102290001Sglebius/** 103290001Sglebius * Like evhttp_bind_socket(), but returns a handle for referencing the socket. 104290001Sglebius * 105290001Sglebius * The returned pointer is not valid after \a http is freed. 106290001Sglebius * 107290001Sglebius * @param http a pointer to an evhttp object 108290001Sglebius * @param address a string containing the IP address to listen(2) on 109290001Sglebius * @param port the port number to listen on 110290001Sglebius * @return Handle for the socket on success, NULL on failure. 111290001Sglebius * @see evhttp_bind_socket(), evhttp_del_accept_socket() 112290001Sglebius */ 113290001SglebiusEVENT2_EXPORT_SYMBOL 114290001Sglebiusstruct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port); 115290001Sglebius 116290001Sglebius/** 117290001Sglebius * Makes an HTTP server accept connections on the specified socket. 118290001Sglebius * 119290001Sglebius * This may be useful to create a socket and then fork multiple instances 120290001Sglebius * of an http server, or when a socket has been communicated via file 121290001Sglebius * descriptor passing in situations where an http servers does not have 122290001Sglebius * permissions to bind to a low-numbered port. 123290001Sglebius * 124290001Sglebius * Can be called multiple times to have the http server listen to 125290001Sglebius * multiple different sockets. 126290001Sglebius * 127290001Sglebius * @param http a pointer to an evhttp object 128290001Sglebius * @param fd a socket fd that is ready for accepting connections 129290001Sglebius * @return 0 on success, -1 on failure. 130290001Sglebius * @see evhttp_bind_socket() 131290001Sglebius */ 132290001SglebiusEVENT2_EXPORT_SYMBOL 133290001Sglebiusint evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd); 134290001Sglebius 135290001Sglebius/** 136290001Sglebius * Like evhttp_accept_socket(), but returns a handle for referencing the socket. 137290001Sglebius * 138290001Sglebius * The returned pointer is not valid after \a http is freed. 139290001Sglebius * 140290001Sglebius * @param http a pointer to an evhttp object 141290001Sglebius * @param fd a socket fd that is ready for accepting connections 142290001Sglebius * @return Handle for the socket on success, NULL on failure. 143290001Sglebius * @see evhttp_accept_socket(), evhttp_del_accept_socket() 144290001Sglebius */ 145290001SglebiusEVENT2_EXPORT_SYMBOL 146290001Sglebiusstruct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd); 147290001Sglebius 148290001Sglebius/** 149290001Sglebius * The most low-level evhttp_bind/accept method: takes an evconnlistener, and 150290001Sglebius * returns an evhttp_bound_socket. The listener will be freed when the bound 151290001Sglebius * socket is freed. 152290001Sglebius */ 153290001SglebiusEVENT2_EXPORT_SYMBOL 154290001Sglebiusstruct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener); 155290001Sglebius 156290001Sglebius/** 157290001Sglebius * Return the listener used to implement a bound socket. 158290001Sglebius */ 159290001SglebiusEVENT2_EXPORT_SYMBOL 160290001Sglebiusstruct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound); 161290001Sglebius 162290001Sglebiustypedef void evhttp_bound_socket_foreach_fn(struct evhttp_bound_socket *, void *); 163290001Sglebius/** 164290001Sglebius * Applies the function specified in the first argument to all 165290001Sglebius * evhttp_bound_sockets associated with "http". The user must not 166290001Sglebius * attempt to free or remove any connections, sockets or listeners 167290001Sglebius * in the callback "function". 168290001Sglebius * 169290001Sglebius * @param http pointer to an evhttp object 170290001Sglebius * @param function function to apply to every bound socket 171290001Sglebius * @param argument pointer value passed to function for every socket iterated 172290001Sglebius */ 173290001SglebiusEVENT2_EXPORT_SYMBOL 174290001Sglebiusvoid evhttp_foreach_bound_socket(struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument); 175290001Sglebius 176290001Sglebius/** 177290001Sglebius * Makes an HTTP server stop accepting connections on the specified socket 178290001Sglebius * 179290001Sglebius * This may be useful when a socket has been sent via file descriptor passing 180290001Sglebius * and is no longer needed by the current process. 181290001Sglebius * 182290001Sglebius * If you created this bound socket with evhttp_bind_socket_with_handle or 183290001Sglebius * evhttp_accept_socket_with_handle, this function closes the fd you provided. 184290001Sglebius * If you created this bound socket with evhttp_bind_listener, this function 185290001Sglebius * frees the listener you provided. 186290001Sglebius * 187290001Sglebius * \a bound_socket is an invalid pointer after this call returns. 188290001Sglebius * 189290001Sglebius * @param http a pointer to an evhttp object 190290001Sglebius * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 191290001Sglebius * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 192290001Sglebius */ 193290001SglebiusEVENT2_EXPORT_SYMBOL 194290001Sglebiusvoid evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket); 195290001Sglebius 196290001Sglebius/** 197290001Sglebius * Get the raw file descriptor referenced by an evhttp_bound_socket. 198290001Sglebius * 199290001Sglebius * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 200290001Sglebius * @return the file descriptor used by the bound socket 201290001Sglebius * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 202290001Sglebius */ 203290001SglebiusEVENT2_EXPORT_SYMBOL 204290001Sglebiusevutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket); 205290001Sglebius 206290001Sglebius/** 207290001Sglebius * Free the previously created HTTP server. 208290001Sglebius * 209290001Sglebius * Works only if no requests are currently being served. 210290001Sglebius * 211290001Sglebius * @param http the evhttp server object to be freed 212290001Sglebius * @see evhttp_start() 213290001Sglebius */ 214290001SglebiusEVENT2_EXPORT_SYMBOL 215290001Sglebiusvoid evhttp_free(struct evhttp* http); 216290001Sglebius 217290001Sglebius/** XXX Document. */ 218290001SglebiusEVENT2_EXPORT_SYMBOL 219290001Sglebiusvoid evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size); 220290001Sglebius/** XXX Document. */ 221290001SglebiusEVENT2_EXPORT_SYMBOL 222290001Sglebiusvoid evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size); 223290001Sglebius 224290001Sglebius/** 225290001Sglebius Set the value to use for the Content-Type header when none was provided. If 226290001Sglebius the content type string is NULL, the Content-Type header will not be 227290001Sglebius automatically added. 228290001Sglebius 229290001Sglebius @param http the http server on which to set the default content type 230290001Sglebius @param content_type the value for the Content-Type header 231290001Sglebius*/ 232290001SglebiusEVENT2_EXPORT_SYMBOL 233290001Sglebiusvoid evhttp_set_default_content_type(struct evhttp *http, 234290001Sglebius const char *content_type); 235290001Sglebius 236290001Sglebius/** 237290001Sglebius Sets the what HTTP methods are supported in requests accepted by this 238290001Sglebius server, and passed to user callbacks. 239290001Sglebius 240290001Sglebius If not supported they will generate a "405 Method not allowed" response. 241290001Sglebius 242290001Sglebius By default this includes the following methods: GET, POST, HEAD, PUT, DELETE 243290001Sglebius 244290001Sglebius @param http the http server on which to set the methods 245290001Sglebius @param methods bit mask constructed from evhttp_cmd_type values 246290001Sglebius*/ 247290001SglebiusEVENT2_EXPORT_SYMBOL 248290001Sglebiusvoid evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods); 249290001Sglebius 250290001Sglebius/** 251290001Sglebius Set a callback for a specified URI 252290001Sglebius 253290001Sglebius @param http the http sever on which to set the callback 254290001Sglebius @param path the path for which to invoke the callback 255290001Sglebius @param cb the callback function that gets invoked on requesting path 256290001Sglebius @param cb_arg an additional context argument for the callback 257290001Sglebius @return 0 on success, -1 if the callback existed already, -2 on failure 258290001Sglebius*/ 259290001SglebiusEVENT2_EXPORT_SYMBOL 260290001Sglebiusint evhttp_set_cb(struct evhttp *http, const char *path, 261290001Sglebius void (*cb)(struct evhttp_request *, void *), void *cb_arg); 262290001Sglebius 263290001Sglebius/** Removes the callback for a specified URI */ 264290001SglebiusEVENT2_EXPORT_SYMBOL 265290001Sglebiusint evhttp_del_cb(struct evhttp *, const char *); 266290001Sglebius 267290001Sglebius/** 268290001Sglebius Set a callback for all requests that are not caught by specific callbacks 269290001Sglebius 270290001Sglebius Invokes the specified callback for all requests that do not match any of 271290001Sglebius the previously specified request paths. This is catchall for requests not 272290001Sglebius specifically configured with evhttp_set_cb(). 273290001Sglebius 274290001Sglebius @param http the evhttp server object for which to set the callback 275290001Sglebius @param cb the callback to invoke for any unmatched requests 276290001Sglebius @param arg an context argument for the callback 277290001Sglebius*/ 278290001SglebiusEVENT2_EXPORT_SYMBOL 279290001Sglebiusvoid evhttp_set_gencb(struct evhttp *http, 280290001Sglebius void (*cb)(struct evhttp_request *, void *), void *arg); 281290001Sglebius 282290001Sglebius/** 283290001Sglebius Set a callback used to create new bufferevents for connections 284290001Sglebius to a given evhttp object. 285290001Sglebius 286290001Sglebius You can use this to override the default bufferevent type -- for example, 287290001Sglebius to make this evhttp object use SSL bufferevents rather than unencrypted 288290001Sglebius ones. 289290001Sglebius 290290001Sglebius New bufferevents must be allocated with no fd set on them. 291290001Sglebius 292290001Sglebius @param http the evhttp server object for which to set the callback 293290001Sglebius @param cb the callback to invoke for incoming connections 294290001Sglebius @param arg an context argument for the callback 295290001Sglebius */ 296290001SglebiusEVENT2_EXPORT_SYMBOL 297290001Sglebiusvoid evhttp_set_bevcb(struct evhttp *http, 298290001Sglebius struct bufferevent *(*cb)(struct event_base *, void *), void *arg); 299290001Sglebius 300290001Sglebius/** 301290001Sglebius Adds a virtual host to the http server. 302290001Sglebius 303290001Sglebius A virtual host is a newly initialized evhttp object that has request 304290001Sglebius callbacks set on it via evhttp_set_cb() or evhttp_set_gencb(). It 305290001Sglebius most not have any listing sockets associated with it. 306290001Sglebius 307290001Sglebius If the virtual host has not been removed by the time that evhttp_free() 308290001Sglebius is called on the main http server, it will be automatically freed, too. 309290001Sglebius 310290001Sglebius It is possible to have hierarchical vhosts. For example: A vhost 311290001Sglebius with the pattern *.example.com may have other vhosts with patterns 312290001Sglebius foo.example.com and bar.example.com associated with it. 313290001Sglebius 314290001Sglebius @param http the evhttp object to which to add a virtual host 315290001Sglebius @param pattern the glob pattern against which the hostname is matched. 316290001Sglebius The match is case insensitive and follows otherwise regular shell 317290001Sglebius matching. 318290001Sglebius @param vhost the virtual host to add the regular http server. 319290001Sglebius @return 0 on success, -1 on failure 320290001Sglebius @see evhttp_remove_virtual_host() 321290001Sglebius*/ 322290001SglebiusEVENT2_EXPORT_SYMBOL 323290001Sglebiusint evhttp_add_virtual_host(struct evhttp* http, const char *pattern, 324290001Sglebius struct evhttp* vhost); 325290001Sglebius 326290001Sglebius/** 327290001Sglebius Removes a virtual host from the http server. 328290001Sglebius 329290001Sglebius @param http the evhttp object from which to remove the virtual host 330290001Sglebius @param vhost the virtual host to remove from the regular http server. 331290001Sglebius @return 0 on success, -1 on failure 332290001Sglebius @see evhttp_add_virtual_host() 333290001Sglebius*/ 334290001SglebiusEVENT2_EXPORT_SYMBOL 335290001Sglebiusint evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost); 336290001Sglebius 337290001Sglebius/** 338290001Sglebius Add a server alias to an http object. The http object can be a virtual 339290001Sglebius host or the main server. 340290001Sglebius 341290001Sglebius @param http the evhttp object 342290001Sglebius @param alias the alias to add 343290001Sglebius @see evhttp_add_remove_alias() 344290001Sglebius*/ 345290001SglebiusEVENT2_EXPORT_SYMBOL 346290001Sglebiusint evhttp_add_server_alias(struct evhttp *http, const char *alias); 347290001Sglebius 348290001Sglebius/** 349290001Sglebius Remove a server alias from an http object. 350290001Sglebius 351290001Sglebius @param http the evhttp object 352290001Sglebius @param alias the alias to remove 353290001Sglebius @see evhttp_add_server_alias() 354290001Sglebius*/ 355290001SglebiusEVENT2_EXPORT_SYMBOL 356290001Sglebiusint evhttp_remove_server_alias(struct evhttp *http, const char *alias); 357290001Sglebius 358290001Sglebius/** 359290001Sglebius * Set the timeout for an HTTP request. 360290001Sglebius * 361290001Sglebius * @param http an evhttp object 362290001Sglebius * @param timeout_in_secs the timeout, in seconds 363290001Sglebius */ 364290001SglebiusEVENT2_EXPORT_SYMBOL 365290001Sglebiusvoid evhttp_set_timeout(struct evhttp *http, int timeout_in_secs); 366290001Sglebius 367290001Sglebius/** 368290001Sglebius * Set the timeout for an HTTP request. 369290001Sglebius * 370290001Sglebius * @param http an evhttp object 371290001Sglebius * @param tv the timeout, or NULL 372290001Sglebius */ 373290001SglebiusEVENT2_EXPORT_SYMBOL 374290001Sglebiusvoid evhttp_set_timeout_tv(struct evhttp *http, const struct timeval* tv); 375290001Sglebius 376290001Sglebius/* Request/Response functionality */ 377290001Sglebius 378290001Sglebius/** 379290001Sglebius * Send an HTML error message to the client. 380290001Sglebius * 381290001Sglebius * @param req a request object 382290001Sglebius * @param error the HTTP error code 383290001Sglebius * @param reason a brief explanation of the error. If this is NULL, we'll 384290001Sglebius * just use the standard meaning of the error code. 385290001Sglebius */ 386290001SglebiusEVENT2_EXPORT_SYMBOL 387290001Sglebiusvoid evhttp_send_error(struct evhttp_request *req, int error, 388290001Sglebius const char *reason); 389290001Sglebius 390290001Sglebius/** 391290001Sglebius * Send an HTML reply to the client. 392290001Sglebius * 393290001Sglebius * The body of the reply consists of the data in databuf. After calling 394290001Sglebius * evhttp_send_reply() databuf will be empty, but the buffer is still 395290001Sglebius * owned by the caller and needs to be deallocated by the caller if 396290001Sglebius * necessary. 397290001Sglebius * 398290001Sglebius * @param req a request object 399290001Sglebius * @param code the HTTP response code to send 400290001Sglebius * @param reason a brief message to send with the response code 401290001Sglebius * @param databuf the body of the response 402290001Sglebius */ 403290001SglebiusEVENT2_EXPORT_SYMBOL 404290001Sglebiusvoid evhttp_send_reply(struct evhttp_request *req, int code, 405290001Sglebius const char *reason, struct evbuffer *databuf); 406290001Sglebius 407290001Sglebius/* Low-level response interface, for streaming/chunked replies */ 408290001Sglebius 409290001Sglebius/** 410290001Sglebius Initiate a reply that uses Transfer-Encoding chunked. 411290001Sglebius 412290001Sglebius This allows the caller to stream the reply back to the client and is 413290001Sglebius useful when either not all of the reply data is immediately available 414290001Sglebius or when sending very large replies. 415290001Sglebius 416290001Sglebius The caller needs to supply data chunks with evhttp_send_reply_chunk() 417290001Sglebius and complete the reply by calling evhttp_send_reply_end(). 418290001Sglebius 419290001Sglebius @param req a request object 420290001Sglebius @param code the HTTP response code to send 421290001Sglebius @param reason a brief message to send with the response code 422290001Sglebius*/ 423290001SglebiusEVENT2_EXPORT_SYMBOL 424290001Sglebiusvoid evhttp_send_reply_start(struct evhttp_request *req, int code, 425290001Sglebius const char *reason); 426290001Sglebius 427290001Sglebius/** 428290001Sglebius Send another data chunk as part of an ongoing chunked reply. 429290001Sglebius 430290001Sglebius The reply chunk consists of the data in databuf. After calling 431290001Sglebius evhttp_send_reply_chunk() databuf will be empty, but the buffer is 432290001Sglebius still owned by the caller and needs to be deallocated by the caller 433290001Sglebius if necessary. 434290001Sglebius 435290001Sglebius @param req a request object 436290001Sglebius @param databuf the data chunk to send as part of the reply. 437290001Sglebius*/ 438290001SglebiusEVENT2_EXPORT_SYMBOL 439290001Sglebiusvoid evhttp_send_reply_chunk(struct evhttp_request *req, 440290001Sglebius struct evbuffer *databuf); 441290001Sglebius 442290001Sglebius/** 443290001Sglebius Send another data chunk as part of an ongoing chunked reply. 444290001Sglebius 445290001Sglebius The reply chunk consists of the data in databuf. After calling 446290001Sglebius evhttp_send_reply_chunk() databuf will be empty, but the buffer is 447290001Sglebius still owned by the caller and needs to be deallocated by the caller 448290001Sglebius if necessary. 449290001Sglebius 450290001Sglebius @param req a request object 451290001Sglebius @param databuf the data chunk to send as part of the reply. 452290001Sglebius @param cb callback funcion 453290001Sglebius @param call back's argument. 454290001Sglebius*/ 455290001SglebiusEVENT2_EXPORT_SYMBOL 456290001Sglebiusvoid evhttp_send_reply_chunk_with_cb(struct evhttp_request *, struct evbuffer *, 457290001Sglebius void (*cb)(struct evhttp_connection *, void *), void *arg); 458290001Sglebius 459290001Sglebius/** 460290001Sglebius Complete a chunked reply, freeing the request as appropriate. 461290001Sglebius 462290001Sglebius @param req a request object 463290001Sglebius*/ 464290001SglebiusEVENT2_EXPORT_SYMBOL 465290001Sglebiusvoid evhttp_send_reply_end(struct evhttp_request *req); 466290001Sglebius 467290001Sglebius/* 468290001Sglebius * Interfaces for making requests 469290001Sglebius */ 470290001Sglebius 471290001Sglebius/** The different request types supported by evhttp. These are as specified 472290001Sglebius * in RFC2616, except for PATCH which is specified by RFC5789. 473290001Sglebius * 474290001Sglebius * By default, only some of these methods are accepted and passed to user 475290001Sglebius * callbacks; use evhttp_set_allowed_methods() to change which methods 476290001Sglebius * are allowed. 477290001Sglebius */ 478290001Sglebiusenum evhttp_cmd_type { 479290001Sglebius EVHTTP_REQ_GET = 1 << 0, 480290001Sglebius EVHTTP_REQ_POST = 1 << 1, 481290001Sglebius EVHTTP_REQ_HEAD = 1 << 2, 482290001Sglebius EVHTTP_REQ_PUT = 1 << 3, 483290001Sglebius EVHTTP_REQ_DELETE = 1 << 4, 484290001Sglebius EVHTTP_REQ_OPTIONS = 1 << 5, 485290001Sglebius EVHTTP_REQ_TRACE = 1 << 6, 486290001Sglebius EVHTTP_REQ_CONNECT = 1 << 7, 487290001Sglebius EVHTTP_REQ_PATCH = 1 << 8 488290001Sglebius}; 489290001Sglebius 490290001Sglebius/** a request object can represent either a request or a reply */ 491290001Sglebiusenum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE }; 492290001Sglebius 493290001Sglebius/** 494290001Sglebius * Create and return a connection object that can be used to for making HTTP 495290001Sglebius * requests. The connection object tries to resolve address and establish the 496290001Sglebius * connection when it is given an http request object. 497290001Sglebius * 498290001Sglebius * @param base the event_base to use for handling the connection 499290001Sglebius * @param dnsbase the dns_base to use for resolving host names; if not 500290001Sglebius * specified host name resolution will block. 501290001Sglebius * @param bev a bufferevent to use for connecting to the server; if NULL, a 502290001Sglebius * socket-based bufferevent will be created. This buffrevent will be freed 503290001Sglebius * when the connection closes. It must have no fd set on it. 504290001Sglebius * @param address the address to which to connect 505290001Sglebius * @param port the port to connect to 506290001Sglebius * @return an evhttp_connection object that can be used for making requests 507290001Sglebius */ 508290001SglebiusEVENT2_EXPORT_SYMBOL 509290001Sglebiusstruct evhttp_connection *evhttp_connection_base_bufferevent_new( 510290001Sglebius struct event_base *base, struct evdns_base *dnsbase, struct bufferevent* bev, const char *address, unsigned short port); 511290001Sglebius 512290001Sglebius/** 513290001Sglebius * Return the bufferevent that an evhttp_connection is using. 514290001Sglebius */ 515290001SglebiusEVENT2_EXPORT_SYMBOL 516290001Sglebiusstruct bufferevent* evhttp_connection_get_bufferevent(struct evhttp_connection *evcon); 517290001Sglebius 518290001Sglebius/** 519290001Sglebius * Return the HTTP server associated with this connection, or NULL. 520290001Sglebius */ 521290001SglebiusEVENT2_EXPORT_SYMBOL 522290001Sglebiusstruct evhttp *evhttp_connection_get_server(struct evhttp_connection *evcon); 523290001Sglebius 524290001Sglebius/** 525290001Sglebius * Creates a new request object that needs to be filled in with the request 526290001Sglebius * parameters. The callback is executed when the request completed or an 527290001Sglebius * error occurred. 528290001Sglebius */ 529290001SglebiusEVENT2_EXPORT_SYMBOL 530290001Sglebiusstruct evhttp_request *evhttp_request_new( 531290001Sglebius void (*cb)(struct evhttp_request *, void *), void *arg); 532290001Sglebius 533290001Sglebius/** 534290001Sglebius * Enable delivery of chunks to requestor. 535290001Sglebius * @param cb will be called after every read of data with the same argument 536290001Sglebius * as the completion callback. Will never be called on an empty 537290001Sglebius * response. May drain the input buffer; it will be drained 538290001Sglebius * automatically on return. 539290001Sglebius */ 540290001SglebiusEVENT2_EXPORT_SYMBOL 541290001Sglebiusvoid evhttp_request_set_chunked_cb(struct evhttp_request *, 542290001Sglebius void (*cb)(struct evhttp_request *, void *)); 543290001Sglebius 544290001Sglebius/** 545290001Sglebius * Register callback for additional parsing of request headers. 546290001Sglebius * @param cb will be called after receiving and parsing the full header. 547290001Sglebius * It allows analyzing the header and possibly closing the connection 548290001Sglebius * by returning a value < 0. 549290001Sglebius */ 550290001SglebiusEVENT2_EXPORT_SYMBOL 551290001Sglebiusvoid evhttp_request_set_header_cb(struct evhttp_request *, 552290001Sglebius int (*cb)(struct evhttp_request *, void *)); 553290001Sglebius 554290001Sglebius/** 555290001Sglebius * The different error types supported by evhttp 556290001Sglebius * 557290001Sglebius * @see evhttp_request_set_error_cb() 558290001Sglebius */ 559290001Sglebiusenum evhttp_request_error { 560290001Sglebius /** 561290001Sglebius * Timeout reached, also @see evhttp_connection_set_timeout() 562290001Sglebius */ 563290001Sglebius EVREQ_HTTP_TIMEOUT, 564290001Sglebius /** 565290001Sglebius * EOF reached 566290001Sglebius */ 567290001Sglebius EVREQ_HTTP_EOF, 568290001Sglebius /** 569290001Sglebius * Error while reading header, or invalid header 570290001Sglebius */ 571290001Sglebius EVREQ_HTTP_INVALID_HEADER, 572290001Sglebius /** 573290001Sglebius * Error encountered while reading or writing 574290001Sglebius */ 575290001Sglebius EVREQ_HTTP_BUFFER_ERROR, 576290001Sglebius /** 577290001Sglebius * The evhttp_cancel_request() called on this request. 578290001Sglebius */ 579290001Sglebius EVREQ_HTTP_REQUEST_CANCEL, 580290001Sglebius /** 581290001Sglebius * Body is greater then evhttp_connection_set_max_body_size() 582290001Sglebius */ 583290001Sglebius EVREQ_HTTP_DATA_TOO_LONG 584290001Sglebius}; 585290001Sglebius/** 586290001Sglebius * Set a callback for errors 587290001Sglebius * @see evhttp_request_error for error types. 588290001Sglebius * 589290001Sglebius * On error, both the error callback and the regular callback will be called, 590290001Sglebius * error callback is called before the regular callback. 591290001Sglebius **/ 592290001SglebiusEVENT2_EXPORT_SYMBOL 593290001Sglebiusvoid evhttp_request_set_error_cb(struct evhttp_request *, 594290001Sglebius void (*)(enum evhttp_request_error, void *)); 595290001Sglebius 596290001Sglebius/** 597290001Sglebius * Set a callback to be called on request completion of evhttp_send_* function. 598290001Sglebius * 599290001Sglebius * The callback function will be called on the completion of the request after 600290001Sglebius * the output data has been written and before the evhttp_request object 601290001Sglebius * is destroyed. This can be useful for tracking resources associated with a 602290001Sglebius * request (ex: timing metrics). 603290001Sglebius * 604290001Sglebius * @param req a request object 605290001Sglebius * @param cb callback function that will be called on request completion 606290001Sglebius * @param cb_arg an additional context argument for the callback 607290001Sglebius */ 608290001SglebiusEVENT2_EXPORT_SYMBOL 609290001Sglebiusvoid evhttp_request_set_on_complete_cb(struct evhttp_request *req, 610290001Sglebius void (*cb)(struct evhttp_request *, void *), void *cb_arg); 611290001Sglebius 612290001Sglebius/** Frees the request object and removes associated events. */ 613290001SglebiusEVENT2_EXPORT_SYMBOL 614290001Sglebiusvoid evhttp_request_free(struct evhttp_request *req); 615290001Sglebius 616290001Sglebius/** 617290001Sglebius * Create and return a connection object that can be used to for making HTTP 618290001Sglebius * requests. The connection object tries to resolve address and establish the 619290001Sglebius * connection when it is given an http request object. 620290001Sglebius * 621290001Sglebius * @param base the event_base to use for handling the connection 622290001Sglebius * @param dnsbase the dns_base to use for resolving host names; if not 623290001Sglebius * specified host name resolution will block. 624290001Sglebius * @param address the address to which to connect 625290001Sglebius * @param port the port to connect to 626290001Sglebius * @return an evhttp_connection object that can be used for making requests 627290001Sglebius */ 628290001SglebiusEVENT2_EXPORT_SYMBOL 629290001Sglebiusstruct evhttp_connection *evhttp_connection_base_new( 630290001Sglebius struct event_base *base, struct evdns_base *dnsbase, 631290001Sglebius const char *address, unsigned short port); 632290001Sglebius 633290001Sglebius/** 634290001Sglebius * Set family hint for DNS requests. 635290001Sglebius */ 636290001Sglebiusvoid evhttp_connection_set_family(struct evhttp_connection *evcon, 637290001Sglebius int family); 638290001Sglebius 639290001Sglebius/** Takes ownership of the request object 640290001Sglebius * 641290001Sglebius * Can be used in a request callback to keep onto the request until 642290001Sglebius * evhttp_request_free() is explicitly called by the user. 643290001Sglebius */ 644290001SglebiusEVENT2_EXPORT_SYMBOL 645290001Sglebiusvoid evhttp_request_own(struct evhttp_request *req); 646290001Sglebius 647290001Sglebius/** Returns 1 if the request is owned by the user */ 648290001SglebiusEVENT2_EXPORT_SYMBOL 649290001Sglebiusint evhttp_request_is_owned(struct evhttp_request *req); 650290001Sglebius 651290001Sglebius/** 652290001Sglebius * Returns the connection object associated with the request or NULL 653290001Sglebius * 654290001Sglebius * The user needs to either free the request explicitly or call 655290001Sglebius * evhttp_send_reply_end(). 656290001Sglebius */ 657290001SglebiusEVENT2_EXPORT_SYMBOL 658290001Sglebiusstruct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req); 659290001Sglebius 660290001Sglebius/** 661290001Sglebius * Returns the underlying event_base for this connection 662290001Sglebius */ 663290001SglebiusEVENT2_EXPORT_SYMBOL 664290001Sglebiusstruct event_base *evhttp_connection_get_base(struct evhttp_connection *req); 665290001Sglebius 666290001SglebiusEVENT2_EXPORT_SYMBOL 667290001Sglebiusvoid evhttp_connection_set_max_headers_size(struct evhttp_connection *evcon, 668290001Sglebius ev_ssize_t new_max_headers_size); 669290001Sglebius 670290001SglebiusEVENT2_EXPORT_SYMBOL 671290001Sglebiusvoid evhttp_connection_set_max_body_size(struct evhttp_connection* evcon, 672290001Sglebius ev_ssize_t new_max_body_size); 673290001Sglebius 674290001Sglebius/** Frees an http connection */ 675290001SglebiusEVENT2_EXPORT_SYMBOL 676290001Sglebiusvoid evhttp_connection_free(struct evhttp_connection *evcon); 677290001Sglebius 678290001Sglebius/** Disowns a given connection object 679290001Sglebius * 680290001Sglebius * Can be used to tell libevent to free the connection object after 681290001Sglebius * the last request has completed or failed. 682290001Sglebius */ 683290001SglebiusEVENT2_EXPORT_SYMBOL 684290001Sglebiusvoid evhttp_connection_free_on_completion(struct evhttp_connection *evcon); 685290001Sglebius 686290001Sglebius/** sets the ip address from which http connections are made */ 687290001SglebiusEVENT2_EXPORT_SYMBOL 688290001Sglebiusvoid evhttp_connection_set_local_address(struct evhttp_connection *evcon, 689290001Sglebius const char *address); 690290001Sglebius 691290001Sglebius/** sets the local port from which http connections are made */ 692290001SglebiusEVENT2_EXPORT_SYMBOL 693290001Sglebiusvoid evhttp_connection_set_local_port(struct evhttp_connection *evcon, 694290001Sglebius ev_uint16_t port); 695290001Sglebius 696290001Sglebius/** Sets the timeout in seconds for events related to this connection */ 697290001SglebiusEVENT2_EXPORT_SYMBOL 698290001Sglebiusvoid evhttp_connection_set_timeout(struct evhttp_connection *evcon, 699290001Sglebius int timeout_in_secs); 700290001Sglebius 701290001Sglebius/** Sets the timeout for events related to this connection. Takes a struct 702290001Sglebius * timeval. */ 703290001SglebiusEVENT2_EXPORT_SYMBOL 704290001Sglebiusvoid evhttp_connection_set_timeout_tv(struct evhttp_connection *evcon, 705290001Sglebius const struct timeval *tv); 706290001Sglebius 707290001Sglebius/** Sets the delay before retrying requests on this connection. This is only 708290001Sglebius * used if evhttp_connection_set_retries is used to make the number of retries 709290001Sglebius * at least one. Each retry after the first is twice as long as the one before 710290001Sglebius * it. */ 711290001SglebiusEVENT2_EXPORT_SYMBOL 712290001Sglebiusvoid evhttp_connection_set_initial_retry_tv(struct evhttp_connection *evcon, 713290001Sglebius const struct timeval *tv); 714290001Sglebius 715290001Sglebius/** Sets the retry limit for this connection - -1 repeats indefinitely */ 716290001SglebiusEVENT2_EXPORT_SYMBOL 717290001Sglebiusvoid evhttp_connection_set_retries(struct evhttp_connection *evcon, 718290001Sglebius int retry_max); 719290001Sglebius 720290001Sglebius/** Set a callback for connection close. */ 721290001SglebiusEVENT2_EXPORT_SYMBOL 722290001Sglebiusvoid evhttp_connection_set_closecb(struct evhttp_connection *evcon, 723290001Sglebius void (*)(struct evhttp_connection *, void *), void *); 724290001Sglebius 725290001Sglebius/** Get the remote address and port associated with this connection. */ 726290001SglebiusEVENT2_EXPORT_SYMBOL 727290001Sglebiusvoid evhttp_connection_get_peer(struct evhttp_connection *evcon, 728290001Sglebius char **address, ev_uint16_t *port); 729290001Sglebius 730290001Sglebius/** Get the remote address associated with this connection. 731290001Sglebius * extracted from getpeername(). 732290001Sglebius * 733290001Sglebius * @return NULL if getpeername() return non success, 734290001Sglebius * or connection is not connected, 735290001Sglebius * otherwise it return pointer to struct sockaddr_storage */ 736290001SglebiusEVENT2_EXPORT_SYMBOL 737290001Sglebiusconst struct sockaddr* 738290001Sglebiusevhttp_connection_get_addr(struct evhttp_connection *evcon); 739290001Sglebius 740290001Sglebius/** 741290001Sglebius Make an HTTP request over the specified connection. 742290001Sglebius 743290001Sglebius The connection gets ownership of the request. On failure, the 744290001Sglebius request object is no longer valid as it has been freed. 745290001Sglebius 746290001Sglebius @param evcon the evhttp_connection object over which to send the request 747290001Sglebius @param req the previously created and configured request object 748290001Sglebius @param type the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc. 749290001Sglebius @param uri the URI associated with the request 750290001Sglebius @return 0 on success, -1 on failure 751290001Sglebius @see evhttp_cancel_request() 752290001Sglebius*/ 753290001SglebiusEVENT2_EXPORT_SYMBOL 754290001Sglebiusint evhttp_make_request(struct evhttp_connection *evcon, 755290001Sglebius struct evhttp_request *req, 756290001Sglebius enum evhttp_cmd_type type, const char *uri); 757290001Sglebius 758290001Sglebius/** 759290001Sglebius Cancels a pending HTTP request. 760290001Sglebius 761290001Sglebius Cancels an ongoing HTTP request. The callback associated with this request 762290001Sglebius is not executed and the request object is freed. If the request is 763290001Sglebius currently being processed, e.g. it is ongoing, the corresponding 764290001Sglebius evhttp_connection object is going to get reset. 765290001Sglebius 766290001Sglebius A request cannot be canceled if its callback has executed already. A request 767290001Sglebius may be canceled reentrantly from its chunked callback. 768290001Sglebius 769290001Sglebius @param req the evhttp_request to cancel; req becomes invalid after this call. 770290001Sglebius*/ 771290001SglebiusEVENT2_EXPORT_SYMBOL 772290001Sglebiusvoid evhttp_cancel_request(struct evhttp_request *req); 773290001Sglebius 774290001Sglebius/** 775290001Sglebius * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986. 776290001Sglebius */ 777290001Sglebiusstruct evhttp_uri; 778290001Sglebius 779290001Sglebius/** Returns the request URI */ 780290001SglebiusEVENT2_EXPORT_SYMBOL 781290001Sglebiusconst char *evhttp_request_get_uri(const struct evhttp_request *req); 782290001Sglebius/** Returns the request URI (parsed) */ 783290001SglebiusEVENT2_EXPORT_SYMBOL 784290001Sglebiusconst struct evhttp_uri *evhttp_request_get_evhttp_uri(const struct evhttp_request *req); 785290001Sglebius/** Returns the request command */ 786290001SglebiusEVENT2_EXPORT_SYMBOL 787290001Sglebiusenum evhttp_cmd_type evhttp_request_get_command(const struct evhttp_request *req); 788290001Sglebius 789290001SglebiusEVENT2_EXPORT_SYMBOL 790290001Sglebiusint evhttp_request_get_response_code(const struct evhttp_request *req); 791290001SglebiusEVENT2_EXPORT_SYMBOL 792290001Sglebiusconst char * evhttp_request_get_response_code_line(const struct evhttp_request *req); 793290001Sglebius 794290001Sglebius/** Returns the input headers */ 795290001SglebiusEVENT2_EXPORT_SYMBOL 796290001Sglebiusstruct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req); 797290001Sglebius/** Returns the output headers */ 798290001SglebiusEVENT2_EXPORT_SYMBOL 799290001Sglebiusstruct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req); 800290001Sglebius/** Returns the input buffer */ 801290001SglebiusEVENT2_EXPORT_SYMBOL 802290001Sglebiusstruct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req); 803290001Sglebius/** Returns the output buffer */ 804290001SglebiusEVENT2_EXPORT_SYMBOL 805290001Sglebiusstruct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req); 806290001Sglebius/** Returns the host associated with the request. If a client sends an absolute 807290001Sglebius URI, the host part of that is preferred. Otherwise, the input headers are 808290001Sglebius searched for a Host: header. NULL is returned if no absolute URI or Host: 809290001Sglebius header is provided. */ 810290001SglebiusEVENT2_EXPORT_SYMBOL 811290001Sglebiusconst char *evhttp_request_get_host(struct evhttp_request *req); 812290001Sglebius 813290001Sglebius/* Interfaces for dealing with HTTP headers */ 814290001Sglebius 815290001Sglebius/** 816290001Sglebius Finds the value belonging to a header. 817290001Sglebius 818290001Sglebius @param headers the evkeyvalq object in which to find the header 819290001Sglebius @param key the name of the header to find 820290001Sglebius @returns a pointer to the value for the header or NULL if the header 821290001Sglebius could not be found. 822290001Sglebius @see evhttp_add_header(), evhttp_remove_header() 823290001Sglebius*/ 824290001SglebiusEVENT2_EXPORT_SYMBOL 825290001Sglebiusconst char *evhttp_find_header(const struct evkeyvalq *headers, 826290001Sglebius const char *key); 827290001Sglebius 828290001Sglebius/** 829290001Sglebius Removes a header from a list of existing headers. 830290001Sglebius 831290001Sglebius @param headers the evkeyvalq object from which to remove a header 832290001Sglebius @param key the name of the header to remove 833290001Sglebius @returns 0 if the header was removed, -1 otherwise. 834290001Sglebius @see evhttp_find_header(), evhttp_add_header() 835290001Sglebius*/ 836290001SglebiusEVENT2_EXPORT_SYMBOL 837290001Sglebiusint evhttp_remove_header(struct evkeyvalq *headers, const char *key); 838290001Sglebius 839290001Sglebius/** 840290001Sglebius Adds a header to a list of existing headers. 841290001Sglebius 842290001Sglebius @param headers the evkeyvalq object to which to add a header 843290001Sglebius @param key the name of the header 844290001Sglebius @param value the value belonging to the header 845290001Sglebius @returns 0 on success, -1 otherwise. 846290001Sglebius @see evhttp_find_header(), evhttp_clear_headers() 847290001Sglebius*/ 848290001SglebiusEVENT2_EXPORT_SYMBOL 849290001Sglebiusint evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value); 850290001Sglebius 851290001Sglebius/** 852290001Sglebius Removes all headers from the header list. 853290001Sglebius 854290001Sglebius @param headers the evkeyvalq object from which to remove all headers 855290001Sglebius*/ 856290001SglebiusEVENT2_EXPORT_SYMBOL 857290001Sglebiusvoid evhttp_clear_headers(struct evkeyvalq *headers); 858290001Sglebius 859290001Sglebius/* Miscellaneous utility functions */ 860290001Sglebius 861290001Sglebius 862290001Sglebius/** 863290001Sglebius Helper function to encode a string for inclusion in a URI. All 864290001Sglebius characters are replaced by their hex-escaped (%22) equivalents, 865290001Sglebius except for characters explicitly unreserved by RFC3986 -- that is, 866290001Sglebius ASCII alphanumeric characters, hyphen, dot, underscore, and tilde. 867290001Sglebius 868290001Sglebius The returned string must be freed by the caller. 869290001Sglebius 870290001Sglebius @param str an unencoded string 871290001Sglebius @return a newly allocated URI-encoded string or NULL on failure 872290001Sglebius */ 873290001SglebiusEVENT2_EXPORT_SYMBOL 874290001Sglebiuschar *evhttp_encode_uri(const char *str); 875290001Sglebius 876290001Sglebius/** 877290001Sglebius As evhttp_encode_uri, but if 'size' is nonnegative, treat the string 878290001Sglebius as being 'size' bytes long. This allows you to encode strings that 879290001Sglebius may contain 0-valued bytes. 880290001Sglebius 881290001Sglebius The returned string must be freed by the caller. 882290001Sglebius 883290001Sglebius @param str an unencoded string 884290001Sglebius @param size the length of the string to encode, or -1 if the string 885290001Sglebius is NUL-terminated 886290001Sglebius @param space_to_plus if true, space characters in 'str' are encoded 887290001Sglebius as +, not %20. 888290001Sglebius @return a newly allocate URI-encoded string, or NULL on failure. 889290001Sglebius */ 890290001SglebiusEVENT2_EXPORT_SYMBOL 891290001Sglebiuschar *evhttp_uriencode(const char *str, ev_ssize_t size, int space_to_plus); 892290001Sglebius 893290001Sglebius/** 894290001Sglebius Helper function to sort of decode a URI-encoded string. Unlike 895290001Sglebius evhttp_get_decoded_uri, it decodes all plus characters that appear 896290001Sglebius _after_ the first question mark character, but no plusses that occur 897290001Sglebius before. This is not a good way to decode URIs in whole or in part. 898290001Sglebius 899290001Sglebius The returned string must be freed by the caller 900290001Sglebius 901290001Sglebius @deprecated This function is deprecated; you probably want to use 902290001Sglebius evhttp_get_decoded_uri instead. 903290001Sglebius 904290001Sglebius @param uri an encoded URI 905290001Sglebius @return a newly allocated unencoded URI or NULL on failure 906290001Sglebius */ 907290001SglebiusEVENT2_EXPORT_SYMBOL 908290001Sglebiuschar *evhttp_decode_uri(const char *uri); 909290001Sglebius 910290001Sglebius/** 911290001Sglebius Helper function to decode a URI-escaped string or HTTP parameter. 912290001Sglebius 913290001Sglebius If 'decode_plus' is 1, then we decode the string as an HTTP parameter 914290001Sglebius value, and convert all plus ('+') characters to spaces. If 915290001Sglebius 'decode_plus' is 0, we leave all plus characters unchanged. 916290001Sglebius 917290001Sglebius The returned string must be freed by the caller. 918290001Sglebius 919290001Sglebius @param uri a URI-encode encoded URI 920290001Sglebius @param decode_plus determines whether we convert '+' to space. 921290001Sglebius @param size_out if size_out is not NULL, *size_out is set to the size of the 922290001Sglebius returned string 923290001Sglebius @return a newly allocated unencoded URI or NULL on failure 924290001Sglebius */ 925290001SglebiusEVENT2_EXPORT_SYMBOL 926290001Sglebiuschar *evhttp_uridecode(const char *uri, int decode_plus, 927290001Sglebius size_t *size_out); 928290001Sglebius 929290001Sglebius/** 930290001Sglebius Helper function to parse out arguments in a query. 931290001Sglebius 932290001Sglebius Parsing a URI like 933290001Sglebius 934290001Sglebius http://foo.com/?q=test&s=some+thing 935290001Sglebius 936290001Sglebius will result in two entries in the key value queue. 937290001Sglebius 938290001Sglebius The first entry is: key="q", value="test" 939290001Sglebius The second entry is: key="s", value="some thing" 940290001Sglebius 941290001Sglebius @deprecated This function is deprecated as of Libevent 2.0.9. Use 942290001Sglebius evhttp_uri_parse and evhttp_parse_query_str instead. 943290001Sglebius 944290001Sglebius @param uri the request URI 945290001Sglebius @param headers the head of the evkeyval queue 946290001Sglebius @return 0 on success, -1 on failure 947290001Sglebius */ 948290001SglebiusEVENT2_EXPORT_SYMBOL 949290001Sglebiusint evhttp_parse_query(const char *uri, struct evkeyvalq *headers); 950290001Sglebius 951290001Sglebius/** 952290001Sglebius Helper function to parse out arguments from the query portion of an 953290001Sglebius HTTP URI. 954290001Sglebius 955290001Sglebius Parsing a query string like 956290001Sglebius 957290001Sglebius q=test&s=some+thing 958290001Sglebius 959290001Sglebius will result in two entries in the key value queue. 960290001Sglebius 961290001Sglebius The first entry is: key="q", value="test" 962290001Sglebius The second entry is: key="s", value="some thing" 963290001Sglebius 964290001Sglebius @param query_parse the query portion of the URI 965290001Sglebius @param headers the head of the evkeyval queue 966290001Sglebius @return 0 on success, -1 on failure 967290001Sglebius */ 968290001SglebiusEVENT2_EXPORT_SYMBOL 969290001Sglebiusint evhttp_parse_query_str(const char *uri, struct evkeyvalq *headers); 970290001Sglebius 971290001Sglebius/** 972290001Sglebius * Escape HTML character entities in a string. 973290001Sglebius * 974290001Sglebius * Replaces <, >, ", ' and & with <, >, ", 975290001Sglebius * ' and & correspondingly. 976290001Sglebius * 977290001Sglebius * The returned string needs to be freed by the caller. 978290001Sglebius * 979290001Sglebius * @param html an unescaped HTML string 980290001Sglebius * @return an escaped HTML string or NULL on error 981290001Sglebius */ 982290001SglebiusEVENT2_EXPORT_SYMBOL 983290001Sglebiuschar *evhttp_htmlescape(const char *html); 984290001Sglebius 985290001Sglebius/** 986290001Sglebius * Return a new empty evhttp_uri with no fields set. 987290001Sglebius */ 988290001SglebiusEVENT2_EXPORT_SYMBOL 989290001Sglebiusstruct evhttp_uri *evhttp_uri_new(void); 990290001Sglebius 991290001Sglebius/** 992290001Sglebius * Changes the flags set on a given URI. See EVHTTP_URI_* for 993290001Sglebius * a list of flags. 994290001Sglebius **/ 995290001SglebiusEVENT2_EXPORT_SYMBOL 996290001Sglebiusvoid evhttp_uri_set_flags(struct evhttp_uri *uri, unsigned flags); 997290001Sglebius 998290001Sglebius/** Return the scheme of an evhttp_uri, or NULL if there is no scheme has 999290001Sglebius * been set and the evhttp_uri contains a Relative-Ref. */ 1000290001SglebiusEVENT2_EXPORT_SYMBOL 1001290001Sglebiusconst char *evhttp_uri_get_scheme(const struct evhttp_uri *uri); 1002290001Sglebius/** 1003290001Sglebius * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo 1004290001Sglebius * set. 1005290001Sglebius */ 1006290001SglebiusEVENT2_EXPORT_SYMBOL 1007290001Sglebiusconst char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri); 1008290001Sglebius/** 1009290001Sglebius * Return the host part of an evhttp_uri, or NULL if it has no host set. 1010290001Sglebius * The host may either be a regular hostname (conforming to the RFC 3986 1011290001Sglebius * "regname" production), or an IPv4 address, or the empty string, or a 1012290001Sglebius * bracketed IPv6 address, or a bracketed 'IP-Future' address. 1013290001Sglebius * 1014290001Sglebius * Note that having a NULL host means that the URI has no authority 1015290001Sglebius * section, but having an empty-string host means that the URI has an 1016290001Sglebius * authority section with no host part. For example, 1017290001Sglebius * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd" 1018290001Sglebius * has a host of "". 1019290001Sglebius */ 1020290001SglebiusEVENT2_EXPORT_SYMBOL 1021290001Sglebiusconst char *evhttp_uri_get_host(const struct evhttp_uri *uri); 1022290001Sglebius/** Return the port part of an evhttp_uri, or -1 if there is no port set. */ 1023290001SglebiusEVENT2_EXPORT_SYMBOL 1024290001Sglebiusint evhttp_uri_get_port(const struct evhttp_uri *uri); 1025290001Sglebius/** Return the path part of an evhttp_uri, or NULL if it has no path set */ 1026290001SglebiusEVENT2_EXPORT_SYMBOL 1027290001Sglebiusconst char *evhttp_uri_get_path(const struct evhttp_uri *uri); 1028290001Sglebius/** Return the query part of an evhttp_uri (excluding the leading "?"), or 1029290001Sglebius * NULL if it has no query set */ 1030290001SglebiusEVENT2_EXPORT_SYMBOL 1031290001Sglebiusconst char *evhttp_uri_get_query(const struct evhttp_uri *uri); 1032290001Sglebius/** Return the fragment part of an evhttp_uri (excluding the leading "#"), 1033290001Sglebius * or NULL if it has no fragment set */ 1034290001SglebiusEVENT2_EXPORT_SYMBOL 1035290001Sglebiusconst char *evhttp_uri_get_fragment(const struct evhttp_uri *uri); 1036290001Sglebius 1037290001Sglebius/** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL. 1038290001Sglebius * Returns 0 on success, -1 if scheme is not well-formed. */ 1039290001SglebiusEVENT2_EXPORT_SYMBOL 1040290001Sglebiusint evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme); 1041290001Sglebius/** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL. 1042290001Sglebius * Returns 0 on success, -1 if userinfo is not well-formed. */ 1043290001SglebiusEVENT2_EXPORT_SYMBOL 1044290001Sglebiusint evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo); 1045290001Sglebius/** Set the host of an evhttp_uri, or clear the host if host==NULL. 1046290001Sglebius * Returns 0 on success, -1 if host is not well-formed. */ 1047290001SglebiusEVENT2_EXPORT_SYMBOL 1048290001Sglebiusint evhttp_uri_set_host(struct evhttp_uri *uri, const char *host); 1049290001Sglebius/** Set the port of an evhttp_uri, or clear the port if port==-1. 1050290001Sglebius * Returns 0 on success, -1 if port is not well-formed. */ 1051290001SglebiusEVENT2_EXPORT_SYMBOL 1052290001Sglebiusint evhttp_uri_set_port(struct evhttp_uri *uri, int port); 1053290001Sglebius/** Set the path of an evhttp_uri, or clear the path if path==NULL. 1054290001Sglebius * Returns 0 on success, -1 if path is not well-formed. */ 1055290001SglebiusEVENT2_EXPORT_SYMBOL 1056290001Sglebiusint evhttp_uri_set_path(struct evhttp_uri *uri, const char *path); 1057290001Sglebius/** Set the query of an evhttp_uri, or clear the query if query==NULL. 1058290001Sglebius * The query should not include a leading "?". 1059290001Sglebius * Returns 0 on success, -1 if query is not well-formed. */ 1060290001SglebiusEVENT2_EXPORT_SYMBOL 1061290001Sglebiusint evhttp_uri_set_query(struct evhttp_uri *uri, const char *query); 1062290001Sglebius/** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL. 1063290001Sglebius * The fragment should not include a leading "#". 1064290001Sglebius * Returns 0 on success, -1 if fragment is not well-formed. */ 1065290001SglebiusEVENT2_EXPORT_SYMBOL 1066290001Sglebiusint evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment); 1067290001Sglebius 1068290001Sglebius/** 1069290001Sglebius * Helper function to parse a URI-Reference as specified by RFC3986. 1070290001Sglebius * 1071290001Sglebius * This function matches the URI-Reference production from RFC3986, 1072290001Sglebius * which includes both URIs like 1073290001Sglebius * 1074290001Sglebius * scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment] 1075290001Sglebius * 1076290001Sglebius * and relative-refs like 1077290001Sglebius * 1078290001Sglebius * [path][?query][#fragment] 1079290001Sglebius * 1080290001Sglebius * Any optional elements portions not present in the original URI are 1081290001Sglebius * left set to NULL in the resulting evhttp_uri. If no port is 1082290001Sglebius * specified, the port is set to -1. 1083290001Sglebius * 1084290001Sglebius * Note that no decoding is performed on percent-escaped characters in 1085290001Sglebius * the string; if you want to parse them, use evhttp_uridecode or 1086290001Sglebius * evhttp_parse_query_str as appropriate. 1087290001Sglebius * 1088290001Sglebius * Note also that most URI schemes will have additional constraints that 1089290001Sglebius * this function does not know about, and cannot check. For example, 1090290001Sglebius * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable 1091290001Sglebius * mailto url, http://www.example.com:99999/ is not a reasonable HTTP 1092290001Sglebius * URL, and ftp:username@example.com is not a reasonable FTP URL. 1093290001Sglebius * Nevertheless, all of these URLs conform to RFC3986, and this function 1094290001Sglebius * accepts all of them as valid. 1095290001Sglebius * 1096290001Sglebius * @param source_uri the request URI 1097290001Sglebius * @param flags Zero or more EVHTTP_URI_* flags to affect the behavior 1098290001Sglebius * of the parser. 1099290001Sglebius * @return uri container to hold parsed data, or NULL if there is error 1100290001Sglebius * @see evhttp_uri_free() 1101290001Sglebius */ 1102290001SglebiusEVENT2_EXPORT_SYMBOL 1103290001Sglebiusstruct evhttp_uri *evhttp_uri_parse_with_flags(const char *source_uri, 1104290001Sglebius unsigned flags); 1105290001Sglebius 1106290001Sglebius/** Tolerate URIs that do not conform to RFC3986. 1107290001Sglebius * 1108290001Sglebius * Unfortunately, some HTTP clients generate URIs that, according to RFC3986, 1109290001Sglebius * are not conformant URIs. If you need to support these URIs, you can 1110290001Sglebius * do so by passing this flag to evhttp_uri_parse_with_flags. 1111290001Sglebius * 1112290001Sglebius * Currently, these changes are: 1113290001Sglebius * <ul> 1114290001Sglebius * <li> Nonconformant URIs are allowed to contain otherwise unreasonable 1115290001Sglebius * characters in their path, query, and fragment components. 1116290001Sglebius * </ul> 1117290001Sglebius */ 1118290001Sglebius#define EVHTTP_URI_NONCONFORMANT 0x01 1119290001Sglebius 1120290001Sglebius/** Alias for evhttp_uri_parse_with_flags(source_uri, 0) */ 1121290001SglebiusEVENT2_EXPORT_SYMBOL 1122290001Sglebiusstruct evhttp_uri *evhttp_uri_parse(const char *source_uri); 1123290001Sglebius 1124290001Sglebius/** 1125290001Sglebius * Free all memory allocated for a parsed uri. Only use this for URIs 1126290001Sglebius * generated by evhttp_uri_parse. 1127290001Sglebius * 1128290001Sglebius * @param uri container with parsed data 1129290001Sglebius * @see evhttp_uri_parse() 1130290001Sglebius */ 1131290001SglebiusEVENT2_EXPORT_SYMBOL 1132290001Sglebiusvoid evhttp_uri_free(struct evhttp_uri *uri); 1133290001Sglebius 1134290001Sglebius/** 1135290001Sglebius * Join together the uri parts from parsed data to form a URI-Reference. 1136290001Sglebius * 1137290001Sglebius * Note that no escaping of reserved characters is done on the members 1138290001Sglebius * of the evhttp_uri, so the generated string might not be a valid URI 1139290001Sglebius * unless the members of evhttp_uri are themselves valid. 1140290001Sglebius * 1141290001Sglebius * @param uri container with parsed data 1142290001Sglebius * @param buf destination buffer 1143290001Sglebius * @param limit destination buffer size 1144290001Sglebius * @return an joined uri as string or NULL on error 1145290001Sglebius * @see evhttp_uri_parse() 1146290001Sglebius */ 1147290001SglebiusEVENT2_EXPORT_SYMBOL 1148290001Sglebiuschar *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit); 1149290001Sglebius 1150290001Sglebius#ifdef __cplusplus 1151290001Sglebius} 1152290001Sglebius#endif 1153290001Sglebius 1154290001Sglebius#endif /* EVENT2_HTTP_H_INCLUDED_ */ 1155