1275970Scy/* 2275970Scy * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3275970Scy * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4275970Scy * 5275970Scy * Redistribution and use in source and binary forms, with or without 6275970Scy * modification, are permitted provided that the following conditions 7275970Scy * are met: 8275970Scy * 1. Redistributions of source code must retain the above copyright 9275970Scy * notice, this list of conditions and the following disclaimer. 10275970Scy * 2. Redistributions in binary form must reproduce the above copyright 11275970Scy * notice, this list of conditions and the following disclaimer in the 12275970Scy * documentation and/or other materials provided with the distribution. 13275970Scy * 3. The name of the author may not be used to endorse or promote products 14275970Scy * derived from this software without specific prior written permission. 15275970Scy * 16275970Scy * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17275970Scy * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18275970Scy * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19275970Scy * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20275970Scy * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21275970Scy * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22275970Scy * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23275970Scy * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24275970Scy * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25275970Scy * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26275970Scy */ 27275970Scy#ifndef EVENT2_HTTP_H_INCLUDED_ 28275970Scy#define EVENT2_HTTP_H_INCLUDED_ 29275970Scy 30275970Scy/* For int types. */ 31275970Scy#include <event2/util.h> 32275970Scy#include <event2/visibility.h> 33275970Scy 34275970Scy#ifdef __cplusplus 35275970Scyextern "C" { 36275970Scy#endif 37275970Scy 38275970Scy/* In case we haven't included the right headers yet. */ 39275970Scystruct evbuffer; 40275970Scystruct event_base; 41275970Scystruct bufferevent; 42275970Scystruct evhttp_connection; 43275970Scy 44275970Scy/** @file event2/http.h 45275970Scy * 46275970Scy * Basic support for HTTP serving. 47275970Scy * 48275970Scy * As Libevent is a library for dealing with event notification and most 49275970Scy * interesting applications are networked today, I have often found the 50275970Scy * need to write HTTP code. The following prototypes and definitions provide 51275970Scy * an application with a minimal interface for making HTTP requests and for 52275970Scy * creating a very simple HTTP server. 53275970Scy */ 54275970Scy 55275970Scy/* Response codes */ 56275970Scy#define HTTP_OK 200 /**< request completed ok */ 57275970Scy#define HTTP_NOCONTENT 204 /**< request does not have content */ 58275970Scy#define HTTP_MOVEPERM 301 /**< the uri moved permanently */ 59275970Scy#define HTTP_MOVETEMP 302 /**< the uri moved temporarily */ 60275970Scy#define HTTP_NOTMODIFIED 304 /**< page was not modified from last */ 61275970Scy#define HTTP_BADREQUEST 400 /**< invalid http request was made */ 62275970Scy#define HTTP_NOTFOUND 404 /**< could not find content for uri */ 63275970Scy#define HTTP_BADMETHOD 405 /**< method not allowed for this uri */ 64275970Scy#define HTTP_ENTITYTOOLARGE 413 /**< */ 65275970Scy#define HTTP_EXPECTATIONFAILED 417 /**< we can't handle this expectation */ 66275970Scy#define HTTP_INTERNAL 500 /**< internal error */ 67275970Scy#define HTTP_NOTIMPLEMENTED 501 /**< not implemented */ 68275970Scy#define HTTP_SERVUNAVAIL 503 /**< the server is not available */ 69275970Scy 70275970Scystruct evhttp; 71275970Scystruct evhttp_request; 72275970Scystruct evkeyvalq; 73275970Scystruct evhttp_bound_socket; 74275970Scystruct evconnlistener; 75275970Scystruct evdns_base; 76275970Scy 77275970Scy/** 78275970Scy * Create a new HTTP server. 79275970Scy * 80275970Scy * @param base (optional) the event base to receive the HTTP events 81275970Scy * @return a pointer to a newly initialized evhttp server structure 82275970Scy * @see evhttp_free() 83275970Scy */ 84275970ScyEVENT2_EXPORT_SYMBOL 85275970Scystruct evhttp *evhttp_new(struct event_base *base); 86275970Scy 87275970Scy/** 88275970Scy * Binds an HTTP server on the specified address and port. 89275970Scy * 90275970Scy * Can be called multiple times to bind the same http server 91275970Scy * to multiple different ports. 92275970Scy * 93275970Scy * @param http a pointer to an evhttp object 94275970Scy * @param address a string containing the IP address to listen(2) on 95275970Scy * @param port the port number to listen on 96275970Scy * @return 0 on success, -1 on failure. 97275970Scy * @see evhttp_accept_socket() 98275970Scy */ 99275970ScyEVENT2_EXPORT_SYMBOL 100275970Scyint evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port); 101275970Scy 102275970Scy/** 103275970Scy * Like evhttp_bind_socket(), but returns a handle for referencing the socket. 104275970Scy * 105275970Scy * The returned pointer is not valid after \a http is freed. 106275970Scy * 107275970Scy * @param http a pointer to an evhttp object 108275970Scy * @param address a string containing the IP address to listen(2) on 109275970Scy * @param port the port number to listen on 110275970Scy * @return Handle for the socket on success, NULL on failure. 111275970Scy * @see evhttp_bind_socket(), evhttp_del_accept_socket() 112275970Scy */ 113275970ScyEVENT2_EXPORT_SYMBOL 114275970Scystruct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port); 115275970Scy 116275970Scy/** 117275970Scy * Makes an HTTP server accept connections on the specified socket. 118275970Scy * 119275970Scy * This may be useful to create a socket and then fork multiple instances 120275970Scy * of an http server, or when a socket has been communicated via file 121275970Scy * descriptor passing in situations where an http servers does not have 122275970Scy * permissions to bind to a low-numbered port. 123275970Scy * 124275970Scy * Can be called multiple times to have the http server listen to 125275970Scy * multiple different sockets. 126275970Scy * 127275970Scy * @param http a pointer to an evhttp object 128275970Scy * @param fd a socket fd that is ready for accepting connections 129275970Scy * @return 0 on success, -1 on failure. 130275970Scy * @see evhttp_bind_socket() 131275970Scy */ 132275970ScyEVENT2_EXPORT_SYMBOL 133275970Scyint evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd); 134275970Scy 135275970Scy/** 136275970Scy * Like evhttp_accept_socket(), but returns a handle for referencing the socket. 137275970Scy * 138275970Scy * The returned pointer is not valid after \a http is freed. 139275970Scy * 140275970Scy * @param http a pointer to an evhttp object 141275970Scy * @param fd a socket fd that is ready for accepting connections 142275970Scy * @return Handle for the socket on success, NULL on failure. 143275970Scy * @see evhttp_accept_socket(), evhttp_del_accept_socket() 144275970Scy */ 145275970ScyEVENT2_EXPORT_SYMBOL 146275970Scystruct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd); 147275970Scy 148275970Scy/** 149275970Scy * The most low-level evhttp_bind/accept method: takes an evconnlistener, and 150275970Scy * returns an evhttp_bound_socket. The listener will be freed when the bound 151275970Scy * socket is freed. 152275970Scy */ 153275970ScyEVENT2_EXPORT_SYMBOL 154275970Scystruct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener); 155275970Scy 156275970Scy/** 157275970Scy * Return the listener used to implement a bound socket. 158275970Scy */ 159275970ScyEVENT2_EXPORT_SYMBOL 160275970Scystruct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound); 161275970Scy 162275970Scytypedef void evhttp_bound_socket_foreach_fn(struct evhttp_bound_socket *, void *); 163275970Scy/** 164275970Scy * Applies the function specified in the first argument to all 165275970Scy * evhttp_bound_sockets associated with "http". The user must not 166275970Scy * attempt to free or remove any connections, sockets or listeners 167275970Scy * in the callback "function". 168275970Scy * 169275970Scy * @param http pointer to an evhttp object 170275970Scy * @param function function to apply to every bound socket 171275970Scy * @param argument pointer value passed to function for every socket iterated 172275970Scy */ 173275970ScyEVENT2_EXPORT_SYMBOL 174275970Scyvoid evhttp_foreach_bound_socket(struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument); 175275970Scy 176275970Scy/** 177275970Scy * Makes an HTTP server stop accepting connections on the specified socket 178275970Scy * 179275970Scy * This may be useful when a socket has been sent via file descriptor passing 180275970Scy * and is no longer needed by the current process. 181275970Scy * 182275970Scy * If you created this bound socket with evhttp_bind_socket_with_handle or 183275970Scy * evhttp_accept_socket_with_handle, this function closes the fd you provided. 184275970Scy * If you created this bound socket with evhttp_bind_listener, this function 185275970Scy * frees the listener you provided. 186275970Scy * 187275970Scy * \a bound_socket is an invalid pointer after this call returns. 188275970Scy * 189275970Scy * @param http a pointer to an evhttp object 190275970Scy * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 191275970Scy * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 192275970Scy */ 193275970ScyEVENT2_EXPORT_SYMBOL 194275970Scyvoid evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket); 195275970Scy 196275970Scy/** 197275970Scy * Get the raw file descriptor referenced by an evhttp_bound_socket. 198275970Scy * 199275970Scy * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 200275970Scy * @return the file descriptor used by the bound socket 201275970Scy * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 202275970Scy */ 203275970ScyEVENT2_EXPORT_SYMBOL 204275970Scyevutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket); 205275970Scy 206275970Scy/** 207275970Scy * Free the previously created HTTP server. 208275970Scy * 209275970Scy * Works only if no requests are currently being served. 210275970Scy * 211275970Scy * @param http the evhttp server object to be freed 212275970Scy * @see evhttp_start() 213275970Scy */ 214275970ScyEVENT2_EXPORT_SYMBOL 215275970Scyvoid evhttp_free(struct evhttp* http); 216275970Scy 217275970Scy/** XXX Document. */ 218275970ScyEVENT2_EXPORT_SYMBOL 219275970Scyvoid evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size); 220275970Scy/** XXX Document. */ 221275970ScyEVENT2_EXPORT_SYMBOL 222275970Scyvoid evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size); 223275970Scy 224275970Scy/** 225275970Scy Set the value to use for the Content-Type header when none was provided. If 226275970Scy the content type string is NULL, the Content-Type header will not be 227275970Scy automatically added. 228275970Scy 229275970Scy @param http the http server on which to set the default content type 230275970Scy @param content_type the value for the Content-Type header 231275970Scy*/ 232275970ScyEVENT2_EXPORT_SYMBOL 233275970Scyvoid evhttp_set_default_content_type(struct evhttp *http, 234275970Scy const char *content_type); 235275970Scy 236275970Scy/** 237275970Scy Sets the what HTTP methods are supported in requests accepted by this 238275970Scy server, and passed to user callbacks. 239275970Scy 240275970Scy If not supported they will generate a "405 Method not allowed" response. 241275970Scy 242275970Scy By default this includes the following methods: GET, POST, HEAD, PUT, DELETE 243275970Scy 244275970Scy @param http the http server on which to set the methods 245275970Scy @param methods bit mask constructed from evhttp_cmd_type values 246275970Scy*/ 247275970ScyEVENT2_EXPORT_SYMBOL 248275970Scyvoid evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods); 249275970Scy 250275970Scy/** 251275970Scy Set a callback for a specified URI 252275970Scy 253275970Scy @param http the http sever on which to set the callback 254275970Scy @param path the path for which to invoke the callback 255275970Scy @param cb the callback function that gets invoked on requesting path 256275970Scy @param cb_arg an additional context argument for the callback 257275970Scy @return 0 on success, -1 if the callback existed already, -2 on failure 258275970Scy*/ 259275970ScyEVENT2_EXPORT_SYMBOL 260275970Scyint evhttp_set_cb(struct evhttp *http, const char *path, 261275970Scy void (*cb)(struct evhttp_request *, void *), void *cb_arg); 262275970Scy 263275970Scy/** Removes the callback for a specified URI */ 264275970ScyEVENT2_EXPORT_SYMBOL 265275970Scyint evhttp_del_cb(struct evhttp *, const char *); 266275970Scy 267275970Scy/** 268275970Scy Set a callback for all requests that are not caught by specific callbacks 269275970Scy 270275970Scy Invokes the specified callback for all requests that do not match any of 271275970Scy the previously specified request paths. This is catchall for requests not 272275970Scy specifically configured with evhttp_set_cb(). 273275970Scy 274275970Scy @param http the evhttp server object for which to set the callback 275275970Scy @param cb the callback to invoke for any unmatched requests 276275970Scy @param arg an context argument for the callback 277275970Scy*/ 278275970ScyEVENT2_EXPORT_SYMBOL 279275970Scyvoid evhttp_set_gencb(struct evhttp *http, 280275970Scy void (*cb)(struct evhttp_request *, void *), void *arg); 281275970Scy 282275970Scy/** 283275970Scy Set a callback used to create new bufferevents for connections 284275970Scy to a given evhttp object. 285275970Scy 286275970Scy You can use this to override the default bufferevent type -- for example, 287275970Scy to make this evhttp object use SSL bufferevents rather than unencrypted 288275970Scy ones. 289275970Scy 290275970Scy New bufferevents must be allocated with no fd set on them. 291275970Scy 292275970Scy @param http the evhttp server object for which to set the callback 293275970Scy @param cb the callback to invoke for incoming connections 294275970Scy @param arg an context argument for the callback 295275970Scy */ 296275970ScyEVENT2_EXPORT_SYMBOL 297275970Scyvoid evhttp_set_bevcb(struct evhttp *http, 298275970Scy struct bufferevent *(*cb)(struct event_base *, void *), void *arg); 299275970Scy 300275970Scy/** 301275970Scy Adds a virtual host to the http server. 302275970Scy 303275970Scy A virtual host is a newly initialized evhttp object that has request 304275970Scy callbacks set on it via evhttp_set_cb() or evhttp_set_gencb(). It 305275970Scy most not have any listing sockets associated with it. 306275970Scy 307275970Scy If the virtual host has not been removed by the time that evhttp_free() 308275970Scy is called on the main http server, it will be automatically freed, too. 309275970Scy 310275970Scy It is possible to have hierarchical vhosts. For example: A vhost 311275970Scy with the pattern *.example.com may have other vhosts with patterns 312275970Scy foo.example.com and bar.example.com associated with it. 313275970Scy 314275970Scy @param http the evhttp object to which to add a virtual host 315275970Scy @param pattern the glob pattern against which the hostname is matched. 316275970Scy The match is case insensitive and follows otherwise regular shell 317275970Scy matching. 318275970Scy @param vhost the virtual host to add the regular http server. 319275970Scy @return 0 on success, -1 on failure 320275970Scy @see evhttp_remove_virtual_host() 321275970Scy*/ 322275970ScyEVENT2_EXPORT_SYMBOL 323275970Scyint evhttp_add_virtual_host(struct evhttp* http, const char *pattern, 324275970Scy struct evhttp* vhost); 325275970Scy 326275970Scy/** 327275970Scy Removes a virtual host from the http server. 328275970Scy 329275970Scy @param http the evhttp object from which to remove the virtual host 330275970Scy @param vhost the virtual host to remove from the regular http server. 331275970Scy @return 0 on success, -1 on failure 332275970Scy @see evhttp_add_virtual_host() 333275970Scy*/ 334275970ScyEVENT2_EXPORT_SYMBOL 335275970Scyint evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost); 336275970Scy 337275970Scy/** 338275970Scy Add a server alias to an http object. The http object can be a virtual 339275970Scy host or the main server. 340275970Scy 341275970Scy @param http the evhttp object 342275970Scy @param alias the alias to add 343275970Scy @see evhttp_add_remove_alias() 344275970Scy*/ 345275970ScyEVENT2_EXPORT_SYMBOL 346275970Scyint evhttp_add_server_alias(struct evhttp *http, const char *alias); 347275970Scy 348275970Scy/** 349275970Scy Remove a server alias from an http object. 350275970Scy 351275970Scy @param http the evhttp object 352275970Scy @param alias the alias to remove 353275970Scy @see evhttp_add_server_alias() 354275970Scy*/ 355275970ScyEVENT2_EXPORT_SYMBOL 356275970Scyint evhttp_remove_server_alias(struct evhttp *http, const char *alias); 357275970Scy 358275970Scy/** 359275970Scy * Set the timeout for an HTTP request. 360275970Scy * 361275970Scy * @param http an evhttp object 362275970Scy * @param timeout_in_secs the timeout, in seconds 363275970Scy */ 364275970ScyEVENT2_EXPORT_SYMBOL 365275970Scyvoid evhttp_set_timeout(struct evhttp *http, int timeout_in_secs); 366275970Scy 367275970Scy/** 368275970Scy * Set the timeout for an HTTP request. 369275970Scy * 370275970Scy * @param http an evhttp object 371275970Scy * @param tv the timeout, or NULL 372275970Scy */ 373275970ScyEVENT2_EXPORT_SYMBOL 374275970Scyvoid evhttp_set_timeout_tv(struct evhttp *http, const struct timeval* tv); 375275970Scy 376275970Scy/* Request/Response functionality */ 377275970Scy 378275970Scy/** 379275970Scy * Send an HTML error message to the client. 380275970Scy * 381275970Scy * @param req a request object 382275970Scy * @param error the HTTP error code 383275970Scy * @param reason a brief explanation of the error. If this is NULL, we'll 384275970Scy * just use the standard meaning of the error code. 385275970Scy */ 386275970ScyEVENT2_EXPORT_SYMBOL 387275970Scyvoid evhttp_send_error(struct evhttp_request *req, int error, 388275970Scy const char *reason); 389275970Scy 390275970Scy/** 391275970Scy * Send an HTML reply to the client. 392275970Scy * 393275970Scy * The body of the reply consists of the data in databuf. After calling 394275970Scy * evhttp_send_reply() databuf will be empty, but the buffer is still 395275970Scy * owned by the caller and needs to be deallocated by the caller if 396275970Scy * necessary. 397275970Scy * 398275970Scy * @param req a request object 399275970Scy * @param code the HTTP response code to send 400275970Scy * @param reason a brief message to send with the response code 401275970Scy * @param databuf the body of the response 402275970Scy */ 403275970ScyEVENT2_EXPORT_SYMBOL 404275970Scyvoid evhttp_send_reply(struct evhttp_request *req, int code, 405275970Scy const char *reason, struct evbuffer *databuf); 406275970Scy 407275970Scy/* Low-level response interface, for streaming/chunked replies */ 408275970Scy 409275970Scy/** 410275970Scy Initiate a reply that uses Transfer-Encoding chunked. 411275970Scy 412275970Scy This allows the caller to stream the reply back to the client and is 413275970Scy useful when either not all of the reply data is immediately available 414275970Scy or when sending very large replies. 415275970Scy 416275970Scy The caller needs to supply data chunks with evhttp_send_reply_chunk() 417275970Scy and complete the reply by calling evhttp_send_reply_end(). 418275970Scy 419275970Scy @param req a request object 420275970Scy @param code the HTTP response code to send 421275970Scy @param reason a brief message to send with the response code 422275970Scy*/ 423275970ScyEVENT2_EXPORT_SYMBOL 424275970Scyvoid evhttp_send_reply_start(struct evhttp_request *req, int code, 425275970Scy const char *reason); 426275970Scy 427275970Scy/** 428275970Scy Send another data chunk as part of an ongoing chunked reply. 429275970Scy 430275970Scy The reply chunk consists of the data in databuf. After calling 431275970Scy evhttp_send_reply_chunk() databuf will be empty, but the buffer is 432275970Scy still owned by the caller and needs to be deallocated by the caller 433275970Scy if necessary. 434275970Scy 435275970Scy @param req a request object 436275970Scy @param databuf the data chunk to send as part of the reply. 437275970Scy*/ 438275970ScyEVENT2_EXPORT_SYMBOL 439275970Scyvoid evhttp_send_reply_chunk(struct evhttp_request *req, 440275970Scy struct evbuffer *databuf); 441275970Scy 442275970Scy/** 443275970Scy Send another data chunk as part of an ongoing chunked reply. 444275970Scy 445275970Scy The reply chunk consists of the data in databuf. After calling 446275970Scy evhttp_send_reply_chunk() databuf will be empty, but the buffer is 447275970Scy still owned by the caller and needs to be deallocated by the caller 448275970Scy if necessary. 449275970Scy 450275970Scy @param req a request object 451275970Scy @param databuf the data chunk to send as part of the reply. 452275970Scy @param cb callback funcion 453275970Scy @param call back's argument. 454275970Scy*/ 455275970ScyEVENT2_EXPORT_SYMBOL 456275970Scyvoid evhttp_send_reply_chunk_with_cb(struct evhttp_request *, struct evbuffer *, 457275970Scy void (*cb)(struct evhttp_connection *, void *), void *arg); 458275970Scy 459275970Scy/** 460275970Scy Complete a chunked reply, freeing the request as appropriate. 461275970Scy 462275970Scy @param req a request object 463275970Scy*/ 464275970ScyEVENT2_EXPORT_SYMBOL 465275970Scyvoid evhttp_send_reply_end(struct evhttp_request *req); 466275970Scy 467275970Scy/* 468275970Scy * Interfaces for making requests 469275970Scy */ 470275970Scy 471275970Scy/** The different request types supported by evhttp. These are as specified 472275970Scy * in RFC2616, except for PATCH which is specified by RFC5789. 473275970Scy * 474275970Scy * By default, only some of these methods are accepted and passed to user 475275970Scy * callbacks; use evhttp_set_allowed_methods() to change which methods 476275970Scy * are allowed. 477275970Scy */ 478275970Scyenum evhttp_cmd_type { 479275970Scy EVHTTP_REQ_GET = 1 << 0, 480275970Scy EVHTTP_REQ_POST = 1 << 1, 481275970Scy EVHTTP_REQ_HEAD = 1 << 2, 482275970Scy EVHTTP_REQ_PUT = 1 << 3, 483275970Scy EVHTTP_REQ_DELETE = 1 << 4, 484275970Scy EVHTTP_REQ_OPTIONS = 1 << 5, 485275970Scy EVHTTP_REQ_TRACE = 1 << 6, 486275970Scy EVHTTP_REQ_CONNECT = 1 << 7, 487275970Scy EVHTTP_REQ_PATCH = 1 << 8 488275970Scy}; 489275970Scy 490275970Scy/** a request object can represent either a request or a reply */ 491275970Scyenum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE }; 492275970Scy 493275970Scy/** 494275970Scy * Create and return a connection object that can be used to for making HTTP 495275970Scy * requests. The connection object tries to resolve address and establish the 496275970Scy * connection when it is given an http request object. 497275970Scy * 498275970Scy * @param base the event_base to use for handling the connection 499275970Scy * @param dnsbase the dns_base to use for resolving host names; if not 500275970Scy * specified host name resolution will block. 501275970Scy * @param bev a bufferevent to use for connecting to the server; if NULL, a 502275970Scy * socket-based bufferevent will be created. This buffrevent will be freed 503275970Scy * when the connection closes. It must have no fd set on it. 504275970Scy * @param address the address to which to connect 505275970Scy * @param port the port to connect to 506275970Scy * @return an evhttp_connection object that can be used for making requests 507275970Scy */ 508275970ScyEVENT2_EXPORT_SYMBOL 509275970Scystruct evhttp_connection *evhttp_connection_base_bufferevent_new( 510275970Scy struct event_base *base, struct evdns_base *dnsbase, struct bufferevent* bev, const char *address, unsigned short port); 511275970Scy 512275970Scy/** 513275970Scy * Return the bufferevent that an evhttp_connection is using. 514275970Scy */ 515275970ScyEVENT2_EXPORT_SYMBOL 516275970Scystruct bufferevent* evhttp_connection_get_bufferevent(struct evhttp_connection *evcon); 517275970Scy 518275970Scy/** 519275970Scy * Return the HTTP server associated with this connection, or NULL. 520275970Scy */ 521275970ScyEVENT2_EXPORT_SYMBOL 522275970Scystruct evhttp *evhttp_connection_get_server(struct evhttp_connection *evcon); 523275970Scy 524275970Scy/** 525275970Scy * Creates a new request object that needs to be filled in with the request 526275970Scy * parameters. The callback is executed when the request completed or an 527275970Scy * error occurred. 528275970Scy */ 529275970ScyEVENT2_EXPORT_SYMBOL 530275970Scystruct evhttp_request *evhttp_request_new( 531275970Scy void (*cb)(struct evhttp_request *, void *), void *arg); 532275970Scy 533275970Scy/** 534275970Scy * Enable delivery of chunks to requestor. 535275970Scy * @param cb will be called after every read of data with the same argument 536275970Scy * as the completion callback. Will never be called on an empty 537275970Scy * response. May drain the input buffer; it will be drained 538275970Scy * automatically on return. 539275970Scy */ 540275970ScyEVENT2_EXPORT_SYMBOL 541275970Scyvoid evhttp_request_set_chunked_cb(struct evhttp_request *, 542275970Scy void (*cb)(struct evhttp_request *, void *)); 543275970Scy 544275970Scy/** 545275970Scy * Register callback for additional parsing of request headers. 546275970Scy * @param cb will be called after receiving and parsing the full header. 547275970Scy * It allows analyzing the header and possibly closing the connection 548275970Scy * by returning a value < 0. 549275970Scy */ 550275970ScyEVENT2_EXPORT_SYMBOL 551275970Scyvoid evhttp_request_set_header_cb(struct evhttp_request *, 552275970Scy int (*cb)(struct evhttp_request *, void *)); 553275970Scy 554275970Scy/** 555275970Scy * The different error types supported by evhttp 556275970Scy * 557275970Scy * @see evhttp_request_set_error_cb() 558275970Scy */ 559275970Scyenum evhttp_request_error { 560275970Scy /** 561275970Scy * Timeout reached, also @see evhttp_connection_set_timeout() 562275970Scy */ 563275970Scy EVREQ_HTTP_TIMEOUT, 564275970Scy /** 565275970Scy * EOF reached 566275970Scy */ 567275970Scy EVREQ_HTTP_EOF, 568275970Scy /** 569275970Scy * Error while reading header, or invalid header 570275970Scy */ 571275970Scy EVREQ_HTTP_INVALID_HEADER, 572275970Scy /** 573275970Scy * Error encountered while reading or writing 574275970Scy */ 575275970Scy EVREQ_HTTP_BUFFER_ERROR, 576275970Scy /** 577275970Scy * The evhttp_cancel_request() called on this request. 578275970Scy */ 579275970Scy EVREQ_HTTP_REQUEST_CANCEL, 580275970Scy /** 581275970Scy * Body is greater then evhttp_connection_set_max_body_size() 582275970Scy */ 583275970Scy EVREQ_HTTP_DATA_TOO_LONG 584275970Scy}; 585275970Scy/** 586275970Scy * Set a callback for errors 587275970Scy * @see evhttp_request_error for error types. 588275970Scy * 589275970Scy * On error, both the error callback and the regular callback will be called, 590275970Scy * error callback is called before the regular callback. 591275970Scy **/ 592275970ScyEVENT2_EXPORT_SYMBOL 593275970Scyvoid evhttp_request_set_error_cb(struct evhttp_request *, 594275970Scy void (*)(enum evhttp_request_error, void *)); 595275970Scy 596275970Scy/** 597275970Scy * Set a callback to be called on request completion of evhttp_send_* function. 598275970Scy * 599275970Scy * The callback function will be called on the completion of the request after 600275970Scy * the output data has been written and before the evhttp_request object 601275970Scy * is destroyed. This can be useful for tracking resources associated with a 602275970Scy * request (ex: timing metrics). 603275970Scy * 604275970Scy * @param req a request object 605275970Scy * @param cb callback function that will be called on request completion 606275970Scy * @param cb_arg an additional context argument for the callback 607275970Scy */ 608275970ScyEVENT2_EXPORT_SYMBOL 609275970Scyvoid evhttp_request_set_on_complete_cb(struct evhttp_request *req, 610275970Scy void (*cb)(struct evhttp_request *, void *), void *cb_arg); 611275970Scy 612275970Scy/** Frees the request object and removes associated events. */ 613275970ScyEVENT2_EXPORT_SYMBOL 614275970Scyvoid evhttp_request_free(struct evhttp_request *req); 615275970Scy 616275970Scy/** 617275970Scy * Create and return a connection object that can be used to for making HTTP 618275970Scy * requests. The connection object tries to resolve address and establish the 619275970Scy * connection when it is given an http request object. 620275970Scy * 621275970Scy * @param base the event_base to use for handling the connection 622275970Scy * @param dnsbase the dns_base to use for resolving host names; if not 623275970Scy * specified host name resolution will block. 624275970Scy * @param address the address to which to connect 625275970Scy * @param port the port to connect to 626275970Scy * @return an evhttp_connection object that can be used for making requests 627275970Scy */ 628275970ScyEVENT2_EXPORT_SYMBOL 629275970Scystruct evhttp_connection *evhttp_connection_base_new( 630275970Scy struct event_base *base, struct evdns_base *dnsbase, 631275970Scy const char *address, unsigned short port); 632275970Scy 633282408Scy/** 634282408Scy * Set family hint for DNS requests. 635282408Scy */ 636282408Scyvoid evhttp_connection_set_family(struct evhttp_connection *evcon, 637282408Scy int family); 638282408Scy 639275970Scy/** Takes ownership of the request object 640275970Scy * 641275970Scy * Can be used in a request callback to keep onto the request until 642275970Scy * evhttp_request_free() is explicitly called by the user. 643275970Scy */ 644275970ScyEVENT2_EXPORT_SYMBOL 645275970Scyvoid evhttp_request_own(struct evhttp_request *req); 646275970Scy 647275970Scy/** Returns 1 if the request is owned by the user */ 648275970ScyEVENT2_EXPORT_SYMBOL 649275970Scyint evhttp_request_is_owned(struct evhttp_request *req); 650275970Scy 651275970Scy/** 652275970Scy * Returns the connection object associated with the request or NULL 653275970Scy * 654275970Scy * The user needs to either free the request explicitly or call 655275970Scy * evhttp_send_reply_end(). 656275970Scy */ 657275970ScyEVENT2_EXPORT_SYMBOL 658275970Scystruct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req); 659275970Scy 660275970Scy/** 661275970Scy * Returns the underlying event_base for this connection 662275970Scy */ 663275970ScyEVENT2_EXPORT_SYMBOL 664275970Scystruct event_base *evhttp_connection_get_base(struct evhttp_connection *req); 665275970Scy 666275970ScyEVENT2_EXPORT_SYMBOL 667275970Scyvoid evhttp_connection_set_max_headers_size(struct evhttp_connection *evcon, 668275970Scy ev_ssize_t new_max_headers_size); 669275970Scy 670275970ScyEVENT2_EXPORT_SYMBOL 671275970Scyvoid evhttp_connection_set_max_body_size(struct evhttp_connection* evcon, 672275970Scy ev_ssize_t new_max_body_size); 673275970Scy 674275970Scy/** Frees an http connection */ 675275970ScyEVENT2_EXPORT_SYMBOL 676275970Scyvoid evhttp_connection_free(struct evhttp_connection *evcon); 677275970Scy 678282408Scy/** Disowns a given connection object 679282408Scy * 680282408Scy * Can be used to tell libevent to free the connection object after 681282408Scy * the last request has completed or failed. 682282408Scy */ 683282408ScyEVENT2_EXPORT_SYMBOL 684282408Scyvoid evhttp_connection_free_on_completion(struct evhttp_connection *evcon); 685282408Scy 686275970Scy/** sets the ip address from which http connections are made */ 687275970ScyEVENT2_EXPORT_SYMBOL 688275970Scyvoid evhttp_connection_set_local_address(struct evhttp_connection *evcon, 689275970Scy const char *address); 690275970Scy 691275970Scy/** sets the local port from which http connections are made */ 692275970ScyEVENT2_EXPORT_SYMBOL 693275970Scyvoid evhttp_connection_set_local_port(struct evhttp_connection *evcon, 694275970Scy ev_uint16_t port); 695275970Scy 696275970Scy/** Sets the timeout in seconds for events related to this connection */ 697275970ScyEVENT2_EXPORT_SYMBOL 698275970Scyvoid evhttp_connection_set_timeout(struct evhttp_connection *evcon, 699275970Scy int timeout_in_secs); 700275970Scy 701275970Scy/** Sets the timeout for events related to this connection. Takes a struct 702275970Scy * timeval. */ 703275970ScyEVENT2_EXPORT_SYMBOL 704275970Scyvoid evhttp_connection_set_timeout_tv(struct evhttp_connection *evcon, 705275970Scy const struct timeval *tv); 706275970Scy 707275970Scy/** Sets the delay before retrying requests on this connection. This is only 708275970Scy * used if evhttp_connection_set_retries is used to make the number of retries 709275970Scy * at least one. Each retry after the first is twice as long as the one before 710275970Scy * it. */ 711275970ScyEVENT2_EXPORT_SYMBOL 712275970Scyvoid evhttp_connection_set_initial_retry_tv(struct evhttp_connection *evcon, 713275970Scy const struct timeval *tv); 714275970Scy 715275970Scy/** Sets the retry limit for this connection - -1 repeats indefinitely */ 716275970ScyEVENT2_EXPORT_SYMBOL 717275970Scyvoid evhttp_connection_set_retries(struct evhttp_connection *evcon, 718275970Scy int retry_max); 719275970Scy 720275970Scy/** Set a callback for connection close. */ 721275970ScyEVENT2_EXPORT_SYMBOL 722275970Scyvoid evhttp_connection_set_closecb(struct evhttp_connection *evcon, 723275970Scy void (*)(struct evhttp_connection *, void *), void *); 724275970Scy 725275970Scy/** Get the remote address and port associated with this connection. */ 726275970ScyEVENT2_EXPORT_SYMBOL 727275970Scyvoid evhttp_connection_get_peer(struct evhttp_connection *evcon, 728275970Scy char **address, ev_uint16_t *port); 729275970Scy 730275970Scy/** Get the remote address associated with this connection. 731275970Scy * extracted from getpeername(). 732275970Scy * 733275970Scy * @return NULL if getpeername() return non success, 734275970Scy * or connection is not connected, 735275970Scy * otherwise it return pointer to struct sockaddr_storage */ 736275970ScyEVENT2_EXPORT_SYMBOL 737275970Scyconst struct sockaddr* 738275970Scyevhttp_connection_get_addr(struct evhttp_connection *evcon); 739275970Scy 740275970Scy/** 741275970Scy Make an HTTP request over the specified connection. 742275970Scy 743275970Scy The connection gets ownership of the request. On failure, the 744275970Scy request object is no longer valid as it has been freed. 745275970Scy 746275970Scy @param evcon the evhttp_connection object over which to send the request 747275970Scy @param req the previously created and configured request object 748275970Scy @param type the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc. 749275970Scy @param uri the URI associated with the request 750275970Scy @return 0 on success, -1 on failure 751275970Scy @see evhttp_cancel_request() 752275970Scy*/ 753275970ScyEVENT2_EXPORT_SYMBOL 754275970Scyint evhttp_make_request(struct evhttp_connection *evcon, 755275970Scy struct evhttp_request *req, 756275970Scy enum evhttp_cmd_type type, const char *uri); 757275970Scy 758275970Scy/** 759275970Scy Cancels a pending HTTP request. 760275970Scy 761275970Scy Cancels an ongoing HTTP request. The callback associated with this request 762275970Scy is not executed and the request object is freed. If the request is 763275970Scy currently being processed, e.g. it is ongoing, the corresponding 764275970Scy evhttp_connection object is going to get reset. 765275970Scy 766275970Scy A request cannot be canceled if its callback has executed already. A request 767275970Scy may be canceled reentrantly from its chunked callback. 768275970Scy 769275970Scy @param req the evhttp_request to cancel; req becomes invalid after this call. 770275970Scy*/ 771275970ScyEVENT2_EXPORT_SYMBOL 772275970Scyvoid evhttp_cancel_request(struct evhttp_request *req); 773275970Scy 774275970Scy/** 775275970Scy * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986. 776275970Scy */ 777275970Scystruct evhttp_uri; 778275970Scy 779275970Scy/** Returns the request URI */ 780275970ScyEVENT2_EXPORT_SYMBOL 781275970Scyconst char *evhttp_request_get_uri(const struct evhttp_request *req); 782275970Scy/** Returns the request URI (parsed) */ 783275970ScyEVENT2_EXPORT_SYMBOL 784275970Scyconst struct evhttp_uri *evhttp_request_get_evhttp_uri(const struct evhttp_request *req); 785275970Scy/** Returns the request command */ 786275970ScyEVENT2_EXPORT_SYMBOL 787275970Scyenum evhttp_cmd_type evhttp_request_get_command(const struct evhttp_request *req); 788275970Scy 789275970ScyEVENT2_EXPORT_SYMBOL 790275970Scyint evhttp_request_get_response_code(const struct evhttp_request *req); 791275970ScyEVENT2_EXPORT_SYMBOL 792275970Scyconst char * evhttp_request_get_response_code_line(const struct evhttp_request *req); 793275970Scy 794275970Scy/** Returns the input headers */ 795275970ScyEVENT2_EXPORT_SYMBOL 796275970Scystruct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req); 797275970Scy/** Returns the output headers */ 798275970ScyEVENT2_EXPORT_SYMBOL 799275970Scystruct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req); 800275970Scy/** Returns the input buffer */ 801275970ScyEVENT2_EXPORT_SYMBOL 802275970Scystruct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req); 803275970Scy/** Returns the output buffer */ 804275970ScyEVENT2_EXPORT_SYMBOL 805275970Scystruct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req); 806275970Scy/** Returns the host associated with the request. If a client sends an absolute 807275970Scy URI, the host part of that is preferred. Otherwise, the input headers are 808275970Scy searched for a Host: header. NULL is returned if no absolute URI or Host: 809275970Scy header is provided. */ 810275970ScyEVENT2_EXPORT_SYMBOL 811275970Scyconst char *evhttp_request_get_host(struct evhttp_request *req); 812275970Scy 813275970Scy/* Interfaces for dealing with HTTP headers */ 814275970Scy 815275970Scy/** 816275970Scy Finds the value belonging to a header. 817275970Scy 818275970Scy @param headers the evkeyvalq object in which to find the header 819275970Scy @param key the name of the header to find 820275970Scy @returns a pointer to the value for the header or NULL if the header 821275970Scy could not be found. 822275970Scy @see evhttp_add_header(), evhttp_remove_header() 823275970Scy*/ 824275970ScyEVENT2_EXPORT_SYMBOL 825275970Scyconst char *evhttp_find_header(const struct evkeyvalq *headers, 826275970Scy const char *key); 827275970Scy 828275970Scy/** 829275970Scy Removes a header from a list of existing headers. 830275970Scy 831275970Scy @param headers the evkeyvalq object from which to remove a header 832275970Scy @param key the name of the header to remove 833275970Scy @returns 0 if the header was removed, -1 otherwise. 834275970Scy @see evhttp_find_header(), evhttp_add_header() 835275970Scy*/ 836275970ScyEVENT2_EXPORT_SYMBOL 837275970Scyint evhttp_remove_header(struct evkeyvalq *headers, const char *key); 838275970Scy 839275970Scy/** 840275970Scy Adds a header to a list of existing headers. 841275970Scy 842275970Scy @param headers the evkeyvalq object to which to add a header 843275970Scy @param key the name of the header 844275970Scy @param value the value belonging to the header 845275970Scy @returns 0 on success, -1 otherwise. 846275970Scy @see evhttp_find_header(), evhttp_clear_headers() 847275970Scy*/ 848275970ScyEVENT2_EXPORT_SYMBOL 849275970Scyint evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value); 850275970Scy 851275970Scy/** 852275970Scy Removes all headers from the header list. 853275970Scy 854275970Scy @param headers the evkeyvalq object from which to remove all headers 855275970Scy*/ 856275970ScyEVENT2_EXPORT_SYMBOL 857275970Scyvoid evhttp_clear_headers(struct evkeyvalq *headers); 858275970Scy 859275970Scy/* Miscellaneous utility functions */ 860275970Scy 861275970Scy 862275970Scy/** 863275970Scy Helper function to encode a string for inclusion in a URI. All 864275970Scy characters are replaced by their hex-escaped (%22) equivalents, 865275970Scy except for characters explicitly unreserved by RFC3986 -- that is, 866275970Scy ASCII alphanumeric characters, hyphen, dot, underscore, and tilde. 867275970Scy 868275970Scy The returned string must be freed by the caller. 869275970Scy 870275970Scy @param str an unencoded string 871275970Scy @return a newly allocated URI-encoded string or NULL on failure 872275970Scy */ 873275970ScyEVENT2_EXPORT_SYMBOL 874275970Scychar *evhttp_encode_uri(const char *str); 875275970Scy 876275970Scy/** 877275970Scy As evhttp_encode_uri, but if 'size' is nonnegative, treat the string 878275970Scy as being 'size' bytes long. This allows you to encode strings that 879275970Scy may contain 0-valued bytes. 880275970Scy 881275970Scy The returned string must be freed by the caller. 882275970Scy 883275970Scy @param str an unencoded string 884275970Scy @param size the length of the string to encode, or -1 if the string 885275970Scy is NUL-terminated 886275970Scy @param space_to_plus if true, space characters in 'str' are encoded 887275970Scy as +, not %20. 888275970Scy @return a newly allocate URI-encoded string, or NULL on failure. 889275970Scy */ 890275970ScyEVENT2_EXPORT_SYMBOL 891275970Scychar *evhttp_uriencode(const char *str, ev_ssize_t size, int space_to_plus); 892275970Scy 893275970Scy/** 894275970Scy Helper function to sort of decode a URI-encoded string. Unlike 895275970Scy evhttp_get_decoded_uri, it decodes all plus characters that appear 896275970Scy _after_ the first question mark character, but no plusses that occur 897275970Scy before. This is not a good way to decode URIs in whole or in part. 898275970Scy 899275970Scy The returned string must be freed by the caller 900275970Scy 901275970Scy @deprecated This function is deprecated; you probably want to use 902275970Scy evhttp_get_decoded_uri instead. 903275970Scy 904275970Scy @param uri an encoded URI 905275970Scy @return a newly allocated unencoded URI or NULL on failure 906275970Scy */ 907275970ScyEVENT2_EXPORT_SYMBOL 908275970Scychar *evhttp_decode_uri(const char *uri); 909275970Scy 910275970Scy/** 911275970Scy Helper function to decode a URI-escaped string or HTTP parameter. 912275970Scy 913275970Scy If 'decode_plus' is 1, then we decode the string as an HTTP parameter 914275970Scy value, and convert all plus ('+') characters to spaces. If 915275970Scy 'decode_plus' is 0, we leave all plus characters unchanged. 916275970Scy 917275970Scy The returned string must be freed by the caller. 918275970Scy 919275970Scy @param uri a URI-encode encoded URI 920275970Scy @param decode_plus determines whether we convert '+' to space. 921275970Scy @param size_out if size_out is not NULL, *size_out is set to the size of the 922275970Scy returned string 923275970Scy @return a newly allocated unencoded URI or NULL on failure 924275970Scy */ 925275970ScyEVENT2_EXPORT_SYMBOL 926275970Scychar *evhttp_uridecode(const char *uri, int decode_plus, 927275970Scy size_t *size_out); 928275970Scy 929275970Scy/** 930275970Scy Helper function to parse out arguments in a query. 931275970Scy 932275970Scy Parsing a URI like 933275970Scy 934275970Scy http://foo.com/?q=test&s=some+thing 935275970Scy 936275970Scy will result in two entries in the key value queue. 937275970Scy 938275970Scy The first entry is: key="q", value="test" 939275970Scy The second entry is: key="s", value="some thing" 940275970Scy 941275970Scy @deprecated This function is deprecated as of Libevent 2.0.9. Use 942275970Scy evhttp_uri_parse and evhttp_parse_query_str instead. 943275970Scy 944275970Scy @param uri the request URI 945275970Scy @param headers the head of the evkeyval queue 946275970Scy @return 0 on success, -1 on failure 947275970Scy */ 948275970ScyEVENT2_EXPORT_SYMBOL 949275970Scyint evhttp_parse_query(const char *uri, struct evkeyvalq *headers); 950275970Scy 951275970Scy/** 952275970Scy Helper function to parse out arguments from the query portion of an 953275970Scy HTTP URI. 954275970Scy 955275970Scy Parsing a query string like 956275970Scy 957275970Scy q=test&s=some+thing 958275970Scy 959275970Scy will result in two entries in the key value queue. 960275970Scy 961275970Scy The first entry is: key="q", value="test" 962275970Scy The second entry is: key="s", value="some thing" 963275970Scy 964275970Scy @param query_parse the query portion of the URI 965275970Scy @param headers the head of the evkeyval queue 966275970Scy @return 0 on success, -1 on failure 967275970Scy */ 968275970ScyEVENT2_EXPORT_SYMBOL 969275970Scyint evhttp_parse_query_str(const char *uri, struct evkeyvalq *headers); 970275970Scy 971275970Scy/** 972275970Scy * Escape HTML character entities in a string. 973275970Scy * 974275970Scy * Replaces <, >, ", ' and & with <, >, ", 975275970Scy * ' and & correspondingly. 976275970Scy * 977275970Scy * The returned string needs to be freed by the caller. 978275970Scy * 979275970Scy * @param html an unescaped HTML string 980275970Scy * @return an escaped HTML string or NULL on error 981275970Scy */ 982275970ScyEVENT2_EXPORT_SYMBOL 983275970Scychar *evhttp_htmlescape(const char *html); 984275970Scy 985275970Scy/** 986275970Scy * Return a new empty evhttp_uri with no fields set. 987275970Scy */ 988275970ScyEVENT2_EXPORT_SYMBOL 989275970Scystruct evhttp_uri *evhttp_uri_new(void); 990275970Scy 991275970Scy/** 992275970Scy * Changes the flags set on a given URI. See EVHTTP_URI_* for 993275970Scy * a list of flags. 994275970Scy **/ 995275970ScyEVENT2_EXPORT_SYMBOL 996275970Scyvoid evhttp_uri_set_flags(struct evhttp_uri *uri, unsigned flags); 997275970Scy 998275970Scy/** Return the scheme of an evhttp_uri, or NULL if there is no scheme has 999275970Scy * been set and the evhttp_uri contains a Relative-Ref. */ 1000275970ScyEVENT2_EXPORT_SYMBOL 1001275970Scyconst char *evhttp_uri_get_scheme(const struct evhttp_uri *uri); 1002275970Scy/** 1003275970Scy * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo 1004275970Scy * set. 1005275970Scy */ 1006275970ScyEVENT2_EXPORT_SYMBOL 1007275970Scyconst char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri); 1008275970Scy/** 1009275970Scy * Return the host part of an evhttp_uri, or NULL if it has no host set. 1010275970Scy * The host may either be a regular hostname (conforming to the RFC 3986 1011275970Scy * "regname" production), or an IPv4 address, or the empty string, or a 1012275970Scy * bracketed IPv6 address, or a bracketed 'IP-Future' address. 1013275970Scy * 1014275970Scy * Note that having a NULL host means that the URI has no authority 1015275970Scy * section, but having an empty-string host means that the URI has an 1016275970Scy * authority section with no host part. For example, 1017275970Scy * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd" 1018275970Scy * has a host of "". 1019275970Scy */ 1020275970ScyEVENT2_EXPORT_SYMBOL 1021275970Scyconst char *evhttp_uri_get_host(const struct evhttp_uri *uri); 1022275970Scy/** Return the port part of an evhttp_uri, or -1 if there is no port set. */ 1023275970ScyEVENT2_EXPORT_SYMBOL 1024275970Scyint evhttp_uri_get_port(const struct evhttp_uri *uri); 1025275970Scy/** Return the path part of an evhttp_uri, or NULL if it has no path set */ 1026275970ScyEVENT2_EXPORT_SYMBOL 1027275970Scyconst char *evhttp_uri_get_path(const struct evhttp_uri *uri); 1028275970Scy/** Return the query part of an evhttp_uri (excluding the leading "?"), or 1029275970Scy * NULL if it has no query set */ 1030275970ScyEVENT2_EXPORT_SYMBOL 1031275970Scyconst char *evhttp_uri_get_query(const struct evhttp_uri *uri); 1032275970Scy/** Return the fragment part of an evhttp_uri (excluding the leading "#"), 1033275970Scy * or NULL if it has no fragment set */ 1034275970ScyEVENT2_EXPORT_SYMBOL 1035275970Scyconst char *evhttp_uri_get_fragment(const struct evhttp_uri *uri); 1036275970Scy 1037275970Scy/** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL. 1038275970Scy * Returns 0 on success, -1 if scheme is not well-formed. */ 1039275970ScyEVENT2_EXPORT_SYMBOL 1040275970Scyint evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme); 1041275970Scy/** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL. 1042275970Scy * Returns 0 on success, -1 if userinfo is not well-formed. */ 1043275970ScyEVENT2_EXPORT_SYMBOL 1044275970Scyint evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo); 1045275970Scy/** Set the host of an evhttp_uri, or clear the host if host==NULL. 1046275970Scy * Returns 0 on success, -1 if host is not well-formed. */ 1047275970ScyEVENT2_EXPORT_SYMBOL 1048275970Scyint evhttp_uri_set_host(struct evhttp_uri *uri, const char *host); 1049275970Scy/** Set the port of an evhttp_uri, or clear the port if port==-1. 1050275970Scy * Returns 0 on success, -1 if port is not well-formed. */ 1051275970ScyEVENT2_EXPORT_SYMBOL 1052275970Scyint evhttp_uri_set_port(struct evhttp_uri *uri, int port); 1053275970Scy/** Set the path of an evhttp_uri, or clear the path if path==NULL. 1054275970Scy * Returns 0 on success, -1 if path is not well-formed. */ 1055275970ScyEVENT2_EXPORT_SYMBOL 1056275970Scyint evhttp_uri_set_path(struct evhttp_uri *uri, const char *path); 1057275970Scy/** Set the query of an evhttp_uri, or clear the query if query==NULL. 1058275970Scy * The query should not include a leading "?". 1059275970Scy * Returns 0 on success, -1 if query is not well-formed. */ 1060275970ScyEVENT2_EXPORT_SYMBOL 1061275970Scyint evhttp_uri_set_query(struct evhttp_uri *uri, const char *query); 1062275970Scy/** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL. 1063275970Scy * The fragment should not include a leading "#". 1064275970Scy * Returns 0 on success, -1 if fragment is not well-formed. */ 1065275970ScyEVENT2_EXPORT_SYMBOL 1066275970Scyint evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment); 1067275970Scy 1068275970Scy/** 1069275970Scy * Helper function to parse a URI-Reference as specified by RFC3986. 1070275970Scy * 1071275970Scy * This function matches the URI-Reference production from RFC3986, 1072275970Scy * which includes both URIs like 1073275970Scy * 1074275970Scy * scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment] 1075275970Scy * 1076275970Scy * and relative-refs like 1077275970Scy * 1078275970Scy * [path][?query][#fragment] 1079275970Scy * 1080275970Scy * Any optional elements portions not present in the original URI are 1081275970Scy * left set to NULL in the resulting evhttp_uri. If no port is 1082275970Scy * specified, the port is set to -1. 1083275970Scy * 1084275970Scy * Note that no decoding is performed on percent-escaped characters in 1085275970Scy * the string; if you want to parse them, use evhttp_uridecode or 1086275970Scy * evhttp_parse_query_str as appropriate. 1087275970Scy * 1088275970Scy * Note also that most URI schemes will have additional constraints that 1089275970Scy * this function does not know about, and cannot check. For example, 1090275970Scy * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable 1091275970Scy * mailto url, http://www.example.com:99999/ is not a reasonable HTTP 1092275970Scy * URL, and ftp:username@example.com is not a reasonable FTP URL. 1093275970Scy * Nevertheless, all of these URLs conform to RFC3986, and this function 1094275970Scy * accepts all of them as valid. 1095275970Scy * 1096275970Scy * @param source_uri the request URI 1097275970Scy * @param flags Zero or more EVHTTP_URI_* flags to affect the behavior 1098275970Scy * of the parser. 1099275970Scy * @return uri container to hold parsed data, or NULL if there is error 1100275970Scy * @see evhttp_uri_free() 1101275970Scy */ 1102275970ScyEVENT2_EXPORT_SYMBOL 1103275970Scystruct evhttp_uri *evhttp_uri_parse_with_flags(const char *source_uri, 1104275970Scy unsigned flags); 1105275970Scy 1106275970Scy/** Tolerate URIs that do not conform to RFC3986. 1107275970Scy * 1108275970Scy * Unfortunately, some HTTP clients generate URIs that, according to RFC3986, 1109275970Scy * are not conformant URIs. If you need to support these URIs, you can 1110275970Scy * do so by passing this flag to evhttp_uri_parse_with_flags. 1111275970Scy * 1112275970Scy * Currently, these changes are: 1113275970Scy * <ul> 1114275970Scy * <li> Nonconformant URIs are allowed to contain otherwise unreasonable 1115275970Scy * characters in their path, query, and fragment components. 1116275970Scy * </ul> 1117275970Scy */ 1118275970Scy#define EVHTTP_URI_NONCONFORMANT 0x01 1119275970Scy 1120275970Scy/** Alias for evhttp_uri_parse_with_flags(source_uri, 0) */ 1121275970ScyEVENT2_EXPORT_SYMBOL 1122275970Scystruct evhttp_uri *evhttp_uri_parse(const char *source_uri); 1123275970Scy 1124275970Scy/** 1125275970Scy * Free all memory allocated for a parsed uri. Only use this for URIs 1126275970Scy * generated by evhttp_uri_parse. 1127275970Scy * 1128275970Scy * @param uri container with parsed data 1129275970Scy * @see evhttp_uri_parse() 1130275970Scy */ 1131275970ScyEVENT2_EXPORT_SYMBOL 1132275970Scyvoid evhttp_uri_free(struct evhttp_uri *uri); 1133275970Scy 1134275970Scy/** 1135275970Scy * Join together the uri parts from parsed data to form a URI-Reference. 1136275970Scy * 1137275970Scy * Note that no escaping of reserved characters is done on the members 1138275970Scy * of the evhttp_uri, so the generated string might not be a valid URI 1139275970Scy * unless the members of evhttp_uri are themselves valid. 1140275970Scy * 1141275970Scy * @param uri container with parsed data 1142275970Scy * @param buf destination buffer 1143275970Scy * @param limit destination buffer size 1144275970Scy * @return an joined uri as string or NULL on error 1145275970Scy * @see evhttp_uri_parse() 1146275970Scy */ 1147275970ScyEVENT2_EXPORT_SYMBOL 1148275970Scychar *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit); 1149275970Scy 1150275970Scy#ifdef __cplusplus 1151275970Scy} 1152275970Scy#endif 1153275970Scy 1154275970Scy#endif /* EVENT2_HTTP_H_INCLUDED_ */ 1155