1 /* 2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 #ifndef EVENT2_HTTP_H_INCLUDED_ 28 #define EVENT2_HTTP_H_INCLUDED_ 29 30 /* For int types. */ 31 #include <event2/util.h> 32 #include <event2/visibility.h> 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* In case we haven't included the right headers yet. */ 39 struct evbuffer; 40 struct event_base; 41 struct bufferevent; 42 struct evhttp_connection; 43 44 /** @file event2/http.h 45 * 46 * Basic support for HTTP serving. 47 * 48 * As Libevent is a library for dealing with event notification and most 49 * interesting applications are networked today, I have often found the 50 * need to write HTTP code. The following prototypes and definitions provide 51 * an application with a minimal interface for making HTTP requests and for 52 * creating a very simple HTTP server. 53 */ 54 55 /* Response codes */ 56 #define HTTP_OK 200 /**< request completed ok */ 57 #define HTTP_NOCONTENT 204 /**< request does not have content */ 58 #define HTTP_MOVEPERM 301 /**< the uri moved permanently */ 59 #define HTTP_MOVETEMP 302 /**< the uri moved temporarily */ 60 #define HTTP_NOTMODIFIED 304 /**< page was not modified from last */ 61 #define HTTP_BADREQUEST 400 /**< invalid http request was made */ 62 #define HTTP_NOTFOUND 404 /**< could not find content for uri */ 63 #define HTTP_BADMETHOD 405 /**< method not allowed for this uri */ 64 #define HTTP_ENTITYTOOLARGE 413 /**< */ 65 #define HTTP_EXPECTATIONFAILED 417 /**< we can't handle this expectation */ 66 #define HTTP_INTERNAL 500 /**< internal error */ 67 #define HTTP_NOTIMPLEMENTED 501 /**< not implemented */ 68 #define HTTP_SERVUNAVAIL 503 /**< the server is not available */ 69 70 struct evhttp; 71 struct evhttp_request; 72 struct evkeyvalq; 73 struct evhttp_bound_socket; 74 struct evconnlistener; 75 struct evdns_base; 76 77 /** 78 * Create a new HTTP server. 79 * 80 * @param base (optional) the event base to receive the HTTP events 81 * @return a pointer to a newly initialized evhttp server structure or NULL 82 * on error 83 * @see evhttp_free() 84 */ 85 EVENT2_EXPORT_SYMBOL 86 struct evhttp *evhttp_new(struct event_base *base); 87 88 /** 89 * Binds an HTTP server on the specified address and port. 90 * 91 * Can be called multiple times to bind the same http server 92 * to multiple different ports. 93 * 94 * @param http a pointer to an evhttp object 95 * @param address a string containing the IP address to listen(2) on 96 * @param port the port number to listen on 97 * @return 0 on success, -1 on failure. 98 * @see evhttp_accept_socket() 99 */ 100 EVENT2_EXPORT_SYMBOL 101 int evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port); 102 103 /** 104 * Like evhttp_bind_socket(), but returns a handle for referencing the socket. 105 * 106 * The returned pointer is not valid after \a http is freed. 107 * 108 * @param http a pointer to an evhttp object 109 * @param address a string containing the IP address to listen(2) on 110 * @param port the port number to listen on 111 * @return Handle for the socket on success, NULL on failure. 112 * @see evhttp_bind_socket(), evhttp_del_accept_socket() 113 */ 114 EVENT2_EXPORT_SYMBOL 115 struct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port); 116 117 /** 118 * Makes an HTTP server accept connections on the specified socket. 119 * 120 * This may be useful to create a socket and then fork multiple instances 121 * of an http server, or when a socket has been communicated via file 122 * descriptor passing in situations where an http servers does not have 123 * permissions to bind to a low-numbered port. 124 * 125 * Can be called multiple times to have the http server listen to 126 * multiple different sockets. 127 * 128 * @param http a pointer to an evhttp object 129 * @param fd a socket fd that is ready for accepting connections 130 * @return 0 on success, -1 on failure. 131 * @see evhttp_bind_socket() 132 */ 133 EVENT2_EXPORT_SYMBOL 134 int evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd); 135 136 /** 137 * Like evhttp_accept_socket(), but returns a handle for referencing the socket. 138 * 139 * The returned pointer is not valid after \a http is freed. 140 * 141 * @param http a pointer to an evhttp object 142 * @param fd a socket fd that is ready for accepting connections 143 * @return Handle for the socket on success, NULL on failure. 144 * @see evhttp_accept_socket(), evhttp_del_accept_socket() 145 */ 146 EVENT2_EXPORT_SYMBOL 147 struct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd); 148 149 /** 150 * The most low-level evhttp_bind/accept method: takes an evconnlistener, and 151 * returns an evhttp_bound_socket. The listener will be freed when the bound 152 * socket is freed. 153 */ 154 EVENT2_EXPORT_SYMBOL 155 struct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener); 156 157 /** 158 * Return the listener used to implement a bound socket. 159 */ 160 EVENT2_EXPORT_SYMBOL 161 struct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound); 162 163 typedef void evhttp_bound_socket_foreach_fn(struct evhttp_bound_socket *, void *); 164 /** 165 * Applies the function specified in the first argument to all 166 * evhttp_bound_sockets associated with "http". The user must not 167 * attempt to free or remove any connections, sockets or listeners 168 * in the callback "function". 169 * 170 * @param http pointer to an evhttp object 171 * @param function function to apply to every bound socket 172 * @param argument pointer value passed to function for every socket iterated 173 */ 174 EVENT2_EXPORT_SYMBOL 175 void evhttp_foreach_bound_socket(struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument); 176 177 /** 178 * Makes an HTTP server stop accepting connections on the specified socket 179 * 180 * This may be useful when a socket has been sent via file descriptor passing 181 * and is no longer needed by the current process. 182 * 183 * If you created this bound socket with evhttp_bind_socket_with_handle or 184 * evhttp_accept_socket_with_handle, this function closes the fd you provided. 185 * If you created this bound socket with evhttp_bind_listener, this function 186 * frees the listener you provided. 187 * 188 * \a bound_socket is an invalid pointer after this call returns. 189 * 190 * @param http a pointer to an evhttp object 191 * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 192 * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 193 */ 194 EVENT2_EXPORT_SYMBOL 195 void evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket); 196 197 /** 198 * Get the raw file descriptor referenced by an evhttp_bound_socket. 199 * 200 * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle 201 * @return the file descriptor used by the bound socket 202 * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle() 203 */ 204 EVENT2_EXPORT_SYMBOL 205 evutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket); 206 207 /** 208 * Free the previously created HTTP server. 209 * 210 * Works only if no requests are currently being served. 211 * 212 * @param http the evhttp server object to be freed 213 * @see evhttp_start() 214 */ 215 EVENT2_EXPORT_SYMBOL 216 void evhttp_free(struct evhttp* http); 217 218 /** XXX Document. */ 219 EVENT2_EXPORT_SYMBOL 220 void evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size); 221 /** XXX Document. */ 222 EVENT2_EXPORT_SYMBOL 223 void evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size); 224 225 /** 226 Set the value to use for the Content-Type header when none was provided. If 227 the content type string is NULL, the Content-Type header will not be 228 automatically added. 229 230 @param http the http server on which to set the default content type 231 @param content_type the value for the Content-Type header 232 */ 233 EVENT2_EXPORT_SYMBOL 234 void evhttp_set_default_content_type(struct evhttp *http, 235 const char *content_type); 236 237 /** 238 Sets the what HTTP methods are supported in requests accepted by this 239 server, and passed to user callbacks. 240 241 If not supported they will generate a "405 Method not allowed" response. 242 243 By default this includes the following methods: GET, POST, HEAD, PUT, DELETE 244 245 @param http the http server on which to set the methods 246 @param methods bit mask constructed from evhttp_cmd_type values 247 */ 248 EVENT2_EXPORT_SYMBOL 249 void evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods); 250 251 /** 252 Set a callback for a specified URI 253 254 @param http the http sever on which to set the callback 255 @param path the path for which to invoke the callback 256 @param cb the callback function that gets invoked on requesting path 257 @param cb_arg an additional context argument for the callback 258 @return 0 on success, -1 if the callback existed already, -2 on failure 259 */ 260 EVENT2_EXPORT_SYMBOL 261 int evhttp_set_cb(struct evhttp *http, const char *path, 262 void (*cb)(struct evhttp_request *, void *), void *cb_arg); 263 264 /** Removes the callback for a specified URI */ 265 EVENT2_EXPORT_SYMBOL 266 int evhttp_del_cb(struct evhttp *, const char *); 267 268 /** 269 Set a callback for all requests that are not caught by specific callbacks 270 271 Invokes the specified callback for all requests that do not match any of 272 the previously specified request paths. This is catchall for requests not 273 specifically configured with evhttp_set_cb(). 274 275 @param http the evhttp server object for which to set the callback 276 @param cb the callback to invoke for any unmatched requests 277 @param arg an context argument for the callback 278 */ 279 EVENT2_EXPORT_SYMBOL 280 void evhttp_set_gencb(struct evhttp *http, 281 void (*cb)(struct evhttp_request *, void *), void *arg); 282 283 /** 284 Set a callback used to create new bufferevents for connections 285 to a given evhttp object. 286 287 You can use this to override the default bufferevent type -- for example, 288 to make this evhttp object use SSL bufferevents rather than unencrypted 289 ones. 290 291 New bufferevents must be allocated with no fd set on them. 292 293 @param http the evhttp server object for which to set the callback 294 @param cb the callback to invoke for incoming connections 295 @param arg an context argument for the callback 296 */ 297 EVENT2_EXPORT_SYMBOL 298 void evhttp_set_bevcb(struct evhttp *http, 299 struct bufferevent *(*cb)(struct event_base *, void *), void *arg); 300 301 /** 302 Adds a virtual host to the http server. 303 304 A virtual host is a newly initialized evhttp object that has request 305 callbacks set on it via evhttp_set_cb() or evhttp_set_gencb(). It 306 most not have any listing sockets associated with it. 307 308 If the virtual host has not been removed by the time that evhttp_free() 309 is called on the main http server, it will be automatically freed, too. 310 311 It is possible to have hierarchical vhosts. For example: A vhost 312 with the pattern *.example.com may have other vhosts with patterns 313 foo.example.com and bar.example.com associated with it. 314 315 @param http the evhttp object to which to add a virtual host 316 @param pattern the glob pattern against which the hostname is matched. 317 The match is case insensitive and follows otherwise regular shell 318 matching. 319 @param vhost the virtual host to add the regular http server. 320 @return 0 on success, -1 on failure 321 @see evhttp_remove_virtual_host() 322 */ 323 EVENT2_EXPORT_SYMBOL 324 int evhttp_add_virtual_host(struct evhttp* http, const char *pattern, 325 struct evhttp* vhost); 326 327 /** 328 Removes a virtual host from the http server. 329 330 @param http the evhttp object from which to remove the virtual host 331 @param vhost the virtual host to remove from the regular http server. 332 @return 0 on success, -1 on failure 333 @see evhttp_add_virtual_host() 334 */ 335 EVENT2_EXPORT_SYMBOL 336 int evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost); 337 338 /** 339 Add a server alias to an http object. The http object can be a virtual 340 host or the main server. 341 342 @param http the evhttp object 343 @param alias the alias to add 344 @see evhttp_add_remove_alias() 345 */ 346 EVENT2_EXPORT_SYMBOL 347 int evhttp_add_server_alias(struct evhttp *http, const char *alias); 348 349 /** 350 Remove a server alias from an http object. 351 352 @param http the evhttp object 353 @param alias the alias to remove 354 @see evhttp_add_server_alias() 355 */ 356 EVENT2_EXPORT_SYMBOL 357 int evhttp_remove_server_alias(struct evhttp *http, const char *alias); 358 359 /** 360 * Set the timeout for an HTTP request. 361 * 362 * @param http an evhttp object 363 * @param timeout_in_secs the timeout, in seconds 364 */ 365 EVENT2_EXPORT_SYMBOL 366 void evhttp_set_timeout(struct evhttp *http, int timeout_in_secs); 367 368 /** 369 * Set the timeout for an HTTP request. 370 * 371 * @param http an evhttp object 372 * @param tv the timeout, or NULL 373 */ 374 EVENT2_EXPORT_SYMBOL 375 void evhttp_set_timeout_tv(struct evhttp *http, const struct timeval* tv); 376 377 /* Read all the clients body, and only after this respond with an error if the 378 * clients body exceed max_body_size */ 379 #define EVHTTP_SERVER_LINGERING_CLOSE 0x0001 380 /** 381 * Set connection flags for HTTP server. 382 * 383 * @see EVHTTP_SERVER_* 384 * @return 0 on success, otherwise non zero (for example if flag doesn't 385 * supported). 386 */ 387 EVENT2_EXPORT_SYMBOL 388 int evhttp_set_flags(struct evhttp *http, int flags); 389 390 /* Request/Response functionality */ 391 392 /** 393 * Send an HTML error message to the client. 394 * 395 * @param req a request object 396 * @param error the HTTP error code 397 * @param reason a brief explanation of the error. If this is NULL, we'll 398 * just use the standard meaning of the error code. 399 */ 400 EVENT2_EXPORT_SYMBOL 401 void evhttp_send_error(struct evhttp_request *req, int error, 402 const char *reason); 403 404 /** 405 * Send an HTML reply to the client. 406 * 407 * The body of the reply consists of the data in databuf. After calling 408 * evhttp_send_reply() databuf will be empty, but the buffer is still 409 * owned by the caller and needs to be deallocated by the caller if 410 * necessary. 411 * 412 * @param req a request object 413 * @param code the HTTP response code to send 414 * @param reason a brief message to send with the response code 415 * @param databuf the body of the response 416 */ 417 EVENT2_EXPORT_SYMBOL 418 void evhttp_send_reply(struct evhttp_request *req, int code, 419 const char *reason, struct evbuffer *databuf); 420 421 /* Low-level response interface, for streaming/chunked replies */ 422 423 /** 424 Initiate a reply that uses Transfer-Encoding chunked. 425 426 This allows the caller to stream the reply back to the client and is 427 useful when either not all of the reply data is immediately available 428 or when sending very large replies. 429 430 The caller needs to supply data chunks with evhttp_send_reply_chunk() 431 and complete the reply by calling evhttp_send_reply_end(). 432 433 @param req a request object 434 @param code the HTTP response code to send 435 @param reason a brief message to send with the response code 436 */ 437 EVENT2_EXPORT_SYMBOL 438 void evhttp_send_reply_start(struct evhttp_request *req, int code, 439 const char *reason); 440 441 /** 442 Send another data chunk as part of an ongoing chunked reply. 443 444 The reply chunk consists of the data in databuf. After calling 445 evhttp_send_reply_chunk() databuf will be empty, but the buffer is 446 still owned by the caller and needs to be deallocated by the caller 447 if necessary. 448 449 @param req a request object 450 @param databuf the data chunk to send as part of the reply. 451 */ 452 EVENT2_EXPORT_SYMBOL 453 void evhttp_send_reply_chunk(struct evhttp_request *req, 454 struct evbuffer *databuf); 455 456 /** 457 Send another data chunk as part of an ongoing chunked reply. 458 459 The reply chunk consists of the data in databuf. After calling 460 evhttp_send_reply_chunk() databuf will be empty, but the buffer is 461 still owned by the caller and needs to be deallocated by the caller 462 if necessary. 463 464 @param req a request object 465 @param databuf the data chunk to send as part of the reply. 466 @param cb callback funcion 467 @param call back's argument. 468 */ 469 EVENT2_EXPORT_SYMBOL 470 void evhttp_send_reply_chunk_with_cb(struct evhttp_request *, struct evbuffer *, 471 void (*cb)(struct evhttp_connection *, void *), void *arg); 472 473 /** 474 Complete a chunked reply, freeing the request as appropriate. 475 476 @param req a request object 477 */ 478 EVENT2_EXPORT_SYMBOL 479 void evhttp_send_reply_end(struct evhttp_request *req); 480 481 /* 482 * Interfaces for making requests 483 */ 484 485 /** The different request types supported by evhttp. These are as specified 486 * in RFC2616, except for PATCH which is specified by RFC5789. 487 * 488 * By default, only some of these methods are accepted and passed to user 489 * callbacks; use evhttp_set_allowed_methods() to change which methods 490 * are allowed. 491 */ 492 enum evhttp_cmd_type { 493 EVHTTP_REQ_GET = 1 << 0, 494 EVHTTP_REQ_POST = 1 << 1, 495 EVHTTP_REQ_HEAD = 1 << 2, 496 EVHTTP_REQ_PUT = 1 << 3, 497 EVHTTP_REQ_DELETE = 1 << 4, 498 EVHTTP_REQ_OPTIONS = 1 << 5, 499 EVHTTP_REQ_TRACE = 1 << 6, 500 EVHTTP_REQ_CONNECT = 1 << 7, 501 EVHTTP_REQ_PATCH = 1 << 8 502 }; 503 504 /** a request object can represent either a request or a reply */ 505 enum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE }; 506 507 /** 508 * Create and return a connection object that can be used to for making HTTP 509 * requests. The connection object tries to resolve address and establish the 510 * connection when it is given an http request object. 511 * 512 * @param base the event_base to use for handling the connection 513 * @param dnsbase the dns_base to use for resolving host names; if not 514 * specified host name resolution will block. 515 * @param bev a bufferevent to use for connecting to the server; if NULL, a 516 * socket-based bufferevent will be created. This buffrevent will be freed 517 * when the connection closes. It must have no fd set on it. 518 * @param address the address to which to connect 519 * @param port the port to connect to 520 * @return an evhttp_connection object that can be used for making requests or 521 * NULL on error 522 */ 523 EVENT2_EXPORT_SYMBOL 524 struct evhttp_connection *evhttp_connection_base_bufferevent_new( 525 struct event_base *base, struct evdns_base *dnsbase, struct bufferevent* bev, const char *address, ev_uint16_t port); 526 527 /** 528 * Return the bufferevent that an evhttp_connection is using. 529 */ 530 EVENT2_EXPORT_SYMBOL 531 struct bufferevent* evhttp_connection_get_bufferevent(struct evhttp_connection *evcon); 532 533 /** 534 * Return the HTTP server associated with this connection, or NULL. 535 */ 536 EVENT2_EXPORT_SYMBOL 537 struct evhttp *evhttp_connection_get_server(struct evhttp_connection *evcon); 538 539 /** 540 * Creates a new request object that needs to be filled in with the request 541 * parameters. The callback is executed when the request completed or an 542 * error occurred. 543 */ 544 EVENT2_EXPORT_SYMBOL 545 struct evhttp_request *evhttp_request_new( 546 void (*cb)(struct evhttp_request *, void *), void *arg); 547 548 /** 549 * Enable delivery of chunks to requestor. 550 * @param cb will be called after every read of data with the same argument 551 * as the completion callback. Will never be called on an empty 552 * response. May drain the input buffer; it will be drained 553 * automatically on return. 554 */ 555 EVENT2_EXPORT_SYMBOL 556 void evhttp_request_set_chunked_cb(struct evhttp_request *, 557 void (*cb)(struct evhttp_request *, void *)); 558 559 /** 560 * Register callback for additional parsing of request headers. 561 * @param cb will be called after receiving and parsing the full header. 562 * It allows analyzing the header and possibly closing the connection 563 * by returning a value < 0. 564 */ 565 EVENT2_EXPORT_SYMBOL 566 void evhttp_request_set_header_cb(struct evhttp_request *, 567 int (*cb)(struct evhttp_request *, void *)); 568 569 /** 570 * The different error types supported by evhttp 571 * 572 * @see evhttp_request_set_error_cb() 573 */ 574 enum evhttp_request_error { 575 /** 576 * Timeout reached, also @see evhttp_connection_set_timeout() 577 */ 578 EVREQ_HTTP_TIMEOUT, 579 /** 580 * EOF reached 581 */ 582 EVREQ_HTTP_EOF, 583 /** 584 * Error while reading header, or invalid header 585 */ 586 EVREQ_HTTP_INVALID_HEADER, 587 /** 588 * Error encountered while reading or writing 589 */ 590 EVREQ_HTTP_BUFFER_ERROR, 591 /** 592 * The evhttp_cancel_request() called on this request. 593 */ 594 EVREQ_HTTP_REQUEST_CANCEL, 595 /** 596 * Body is greater then evhttp_connection_set_max_body_size() 597 */ 598 EVREQ_HTTP_DATA_TOO_LONG 599 }; 600 /** 601 * Set a callback for errors 602 * @see evhttp_request_error for error types. 603 * 604 * On error, both the error callback and the regular callback will be called, 605 * error callback is called before the regular callback. 606 **/ 607 EVENT2_EXPORT_SYMBOL 608 void evhttp_request_set_error_cb(struct evhttp_request *, 609 void (*)(enum evhttp_request_error, void *)); 610 611 /** 612 * Set a callback to be called on request completion of evhttp_send_* function. 613 * 614 * The callback function will be called on the completion of the request after 615 * the output data has been written and before the evhttp_request object 616 * is destroyed. This can be useful for tracking resources associated with a 617 * request (ex: timing metrics). 618 * 619 * @param req a request object 620 * @param cb callback function that will be called on request completion 621 * @param cb_arg an additional context argument for the callback 622 */ 623 EVENT2_EXPORT_SYMBOL 624 void evhttp_request_set_on_complete_cb(struct evhttp_request *req, 625 void (*cb)(struct evhttp_request *, void *), void *cb_arg); 626 627 /** Frees the request object and removes associated events. */ 628 EVENT2_EXPORT_SYMBOL 629 void evhttp_request_free(struct evhttp_request *req); 630 631 /** 632 * Create and return a connection object that can be used to for making HTTP 633 * requests. The connection object tries to resolve address and establish the 634 * connection when it is given an http request object. 635 * 636 * @param base the event_base to use for handling the connection 637 * @param dnsbase the dns_base to use for resolving host names; if not 638 * specified host name resolution will block. 639 * @param address the address to which to connect 640 * @param port the port to connect to 641 * @return an evhttp_connection object that can be used for making requests or 642 * NULL on error 643 */ 644 EVENT2_EXPORT_SYMBOL 645 struct evhttp_connection *evhttp_connection_base_new( 646 struct event_base *base, struct evdns_base *dnsbase, 647 const char *address, ev_uint16_t port); 648 649 /** 650 * Set family hint for DNS requests. 651 */ 652 EVENT2_EXPORT_SYMBOL 653 void evhttp_connection_set_family(struct evhttp_connection *evcon, 654 int family); 655 656 /* reuse connection address on retry */ 657 #define EVHTTP_CON_REUSE_CONNECTED_ADDR 0x0008 658 /* Try to read error, since server may already send and close 659 * connection, but if at that time we have some data to send then we 660 * can send get EPIPE and fail, while we can read that HTTP error. */ 661 #define EVHTTP_CON_READ_ON_WRITE_ERROR 0x0010 662 /* @see EVHTTP_SERVER_LINGERING_CLOSE */ 663 #define EVHTTP_CON_LINGERING_CLOSE 0x0020 664 /* Padding for public flags, @see EVHTTP_CON_* in http-internal.h */ 665 #define EVHTTP_CON_PUBLIC_FLAGS_END 0x100000 666 /** 667 * Set connection flags. 668 * 669 * @see EVHTTP_CON_* 670 * @return 0 on success, otherwise non zero (for example if flag doesn't 671 * supported). 672 */ 673 EVENT2_EXPORT_SYMBOL 674 int evhttp_connection_set_flags(struct evhttp_connection *evcon, 675 int flags); 676 677 /** Takes ownership of the request object 678 * 679 * Can be used in a request callback to keep onto the request until 680 * evhttp_request_free() is explicitly called by the user. 681 */ 682 EVENT2_EXPORT_SYMBOL 683 void evhttp_request_own(struct evhttp_request *req); 684 685 /** Returns 1 if the request is owned by the user */ 686 EVENT2_EXPORT_SYMBOL 687 int evhttp_request_is_owned(struct evhttp_request *req); 688 689 /** 690 * Returns the connection object associated with the request or NULL 691 * 692 * The user needs to either free the request explicitly or call 693 * evhttp_send_reply_end(). 694 */ 695 EVENT2_EXPORT_SYMBOL 696 struct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req); 697 698 /** 699 * Returns the underlying event_base for this connection 700 */ 701 EVENT2_EXPORT_SYMBOL 702 struct event_base *evhttp_connection_get_base(struct evhttp_connection *req); 703 704 EVENT2_EXPORT_SYMBOL 705 void evhttp_connection_set_max_headers_size(struct evhttp_connection *evcon, 706 ev_ssize_t new_max_headers_size); 707 708 EVENT2_EXPORT_SYMBOL 709 void evhttp_connection_set_max_body_size(struct evhttp_connection* evcon, 710 ev_ssize_t new_max_body_size); 711 712 /** Frees an http connection */ 713 EVENT2_EXPORT_SYMBOL 714 void evhttp_connection_free(struct evhttp_connection *evcon); 715 716 /** Disowns a given connection object 717 * 718 * Can be used to tell libevent to free the connection object after 719 * the last request has completed or failed. 720 */ 721 EVENT2_EXPORT_SYMBOL 722 void evhttp_connection_free_on_completion(struct evhttp_connection *evcon); 723 724 /** sets the ip address from which http connections are made */ 725 EVENT2_EXPORT_SYMBOL 726 void evhttp_connection_set_local_address(struct evhttp_connection *evcon, 727 const char *address); 728 729 /** sets the local port from which http connections are made */ 730 EVENT2_EXPORT_SYMBOL 731 void evhttp_connection_set_local_port(struct evhttp_connection *evcon, 732 ev_uint16_t port); 733 734 /** Sets the timeout in seconds for events related to this connection */ 735 EVENT2_EXPORT_SYMBOL 736 void evhttp_connection_set_timeout(struct evhttp_connection *evcon, 737 int timeout_in_secs); 738 739 /** Sets the timeout for events related to this connection. Takes a struct 740 * timeval. */ 741 EVENT2_EXPORT_SYMBOL 742 void evhttp_connection_set_timeout_tv(struct evhttp_connection *evcon, 743 const struct timeval *tv); 744 745 /** Sets the delay before retrying requests on this connection. This is only 746 * used if evhttp_connection_set_retries is used to make the number of retries 747 * at least one. Each retry after the first is twice as long as the one before 748 * it. */ 749 EVENT2_EXPORT_SYMBOL 750 void evhttp_connection_set_initial_retry_tv(struct evhttp_connection *evcon, 751 const struct timeval *tv); 752 753 /** Sets the retry limit for this connection - -1 repeats indefinitely */ 754 EVENT2_EXPORT_SYMBOL 755 void evhttp_connection_set_retries(struct evhttp_connection *evcon, 756 int retry_max); 757 758 /** Set a callback for connection close. */ 759 EVENT2_EXPORT_SYMBOL 760 void evhttp_connection_set_closecb(struct evhttp_connection *evcon, 761 void (*)(struct evhttp_connection *, void *), void *); 762 763 /** Get the remote address and port associated with this connection. */ 764 EVENT2_EXPORT_SYMBOL 765 void evhttp_connection_get_peer(struct evhttp_connection *evcon, 766 char **address, ev_uint16_t *port); 767 768 /** Get the remote address associated with this connection. 769 * extracted from getpeername() OR from nameserver. 770 * 771 * @return NULL if getpeername() return non success, 772 * or connection is not connected, 773 * otherwise it return pointer to struct sockaddr_storage */ 774 EVENT2_EXPORT_SYMBOL 775 const struct sockaddr* 776 evhttp_connection_get_addr(struct evhttp_connection *evcon); 777 778 /** 779 Make an HTTP request over the specified connection. 780 781 The connection gets ownership of the request. On failure, the 782 request object is no longer valid as it has been freed. 783 784 @param evcon the evhttp_connection object over which to send the request 785 @param req the previously created and configured request object 786 @param type the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc. 787 @param uri the URI associated with the request 788 @return 0 on success, -1 on failure 789 @see evhttp_cancel_request() 790 */ 791 EVENT2_EXPORT_SYMBOL 792 int evhttp_make_request(struct evhttp_connection *evcon, 793 struct evhttp_request *req, 794 enum evhttp_cmd_type type, const char *uri); 795 796 /** 797 Cancels a pending HTTP request. 798 799 Cancels an ongoing HTTP request. The callback associated with this request 800 is not executed and the request object is freed. If the request is 801 currently being processed, e.g. it is ongoing, the corresponding 802 evhttp_connection object is going to get reset. 803 804 A request cannot be canceled if its callback has executed already. A request 805 may be canceled reentrantly from its chunked callback. 806 807 @param req the evhttp_request to cancel; req becomes invalid after this call. 808 */ 809 EVENT2_EXPORT_SYMBOL 810 void evhttp_cancel_request(struct evhttp_request *req); 811 812 /** 813 * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986. 814 */ 815 struct evhttp_uri; 816 817 /** Returns the request URI */ 818 EVENT2_EXPORT_SYMBOL 819 const char *evhttp_request_get_uri(const struct evhttp_request *req); 820 /** Returns the request URI (parsed) */ 821 EVENT2_EXPORT_SYMBOL 822 const struct evhttp_uri *evhttp_request_get_evhttp_uri(const struct evhttp_request *req); 823 /** Returns the request command */ 824 EVENT2_EXPORT_SYMBOL 825 enum evhttp_cmd_type evhttp_request_get_command(const struct evhttp_request *req); 826 827 EVENT2_EXPORT_SYMBOL 828 int evhttp_request_get_response_code(const struct evhttp_request *req); 829 EVENT2_EXPORT_SYMBOL 830 const char * evhttp_request_get_response_code_line(const struct evhttp_request *req); 831 832 /** Returns the input headers */ 833 EVENT2_EXPORT_SYMBOL 834 struct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req); 835 /** Returns the output headers */ 836 EVENT2_EXPORT_SYMBOL 837 struct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req); 838 /** Returns the input buffer */ 839 EVENT2_EXPORT_SYMBOL 840 struct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req); 841 /** Returns the output buffer */ 842 EVENT2_EXPORT_SYMBOL 843 struct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req); 844 /** Returns the host associated with the request. If a client sends an absolute 845 URI, the host part of that is preferred. Otherwise, the input headers are 846 searched for a Host: header. NULL is returned if no absolute URI or Host: 847 header is provided. */ 848 EVENT2_EXPORT_SYMBOL 849 const char *evhttp_request_get_host(struct evhttp_request *req); 850 851 /* Interfaces for dealing with HTTP headers */ 852 853 /** 854 Finds the value belonging to a header. 855 856 @param headers the evkeyvalq object in which to find the header 857 @param key the name of the header to find 858 @returns a pointer to the value for the header or NULL if the header 859 could not be found. 860 @see evhttp_add_header(), evhttp_remove_header() 861 */ 862 EVENT2_EXPORT_SYMBOL 863 const char *evhttp_find_header(const struct evkeyvalq *headers, 864 const char *key); 865 866 /** 867 Removes a header from a list of existing headers. 868 869 @param headers the evkeyvalq object from which to remove a header 870 @param key the name of the header to remove 871 @returns 0 if the header was removed, -1 otherwise. 872 @see evhttp_find_header(), evhttp_add_header() 873 */ 874 EVENT2_EXPORT_SYMBOL 875 int evhttp_remove_header(struct evkeyvalq *headers, const char *key); 876 877 /** 878 Adds a header to a list of existing headers. 879 880 @param headers the evkeyvalq object to which to add a header 881 @param key the name of the header 882 @param value the value belonging to the header 883 @returns 0 on success, -1 otherwise. 884 @see evhttp_find_header(), evhttp_clear_headers() 885 */ 886 EVENT2_EXPORT_SYMBOL 887 int evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value); 888 889 /** 890 Removes all headers from the header list. 891 892 @param headers the evkeyvalq object from which to remove all headers 893 */ 894 EVENT2_EXPORT_SYMBOL 895 void evhttp_clear_headers(struct evkeyvalq *headers); 896 897 /* Miscellaneous utility functions */ 898 899 900 /** 901 Helper function to encode a string for inclusion in a URI. All 902 characters are replaced by their hex-escaped (%22) equivalents, 903 except for characters explicitly unreserved by RFC3986 -- that is, 904 ASCII alphanumeric characters, hyphen, dot, underscore, and tilde. 905 906 The returned string must be freed by the caller. 907 908 @param str an unencoded string 909 @return a newly allocated URI-encoded string or NULL on failure 910 */ 911 EVENT2_EXPORT_SYMBOL 912 char *evhttp_encode_uri(const char *str); 913 914 /** 915 As evhttp_encode_uri, but if 'size' is nonnegative, treat the string 916 as being 'size' bytes long. This allows you to encode strings that 917 may contain 0-valued bytes. 918 919 The returned string must be freed by the caller. 920 921 @param str an unencoded string 922 @param size the length of the string to encode, or -1 if the string 923 is NUL-terminated 924 @param space_to_plus if true, space characters in 'str' are encoded 925 as +, not %20. 926 @return a newly allocate URI-encoded string, or NULL on failure. 927 */ 928 EVENT2_EXPORT_SYMBOL 929 char *evhttp_uriencode(const char *str, ev_ssize_t size, int space_to_plus); 930 931 /** 932 Helper function to sort of decode a URI-encoded string. Unlike 933 evhttp_uridecode, it decodes all plus characters that appear 934 _after_ the first question mark character, but no plusses that occur 935 before. This is not a good way to decode URIs in whole or in part. 936 937 The returned string must be freed by the caller 938 939 @deprecated This function is deprecated; you probably want to use 940 evhttp_uridecode instead. 941 942 @param uri an encoded URI 943 @return a newly allocated unencoded URI or NULL on failure 944 */ 945 EVENT2_EXPORT_SYMBOL 946 char *evhttp_decode_uri(const char *uri); 947 948 /** 949 Helper function to decode a URI-escaped string or HTTP parameter. 950 951 If 'decode_plus' is 1, then we decode the string as an HTTP parameter 952 value, and convert all plus ('+') characters to spaces. If 953 'decode_plus' is 0, we leave all plus characters unchanged. 954 955 The returned string must be freed by the caller. 956 957 @param uri a URI-encode encoded URI 958 @param decode_plus determines whether we convert '+' to space. 959 @param size_out if size_out is not NULL, *size_out is set to the size of the 960 returned string 961 @return a newly allocated unencoded URI or NULL on failure 962 */ 963 EVENT2_EXPORT_SYMBOL 964 char *evhttp_uridecode(const char *uri, int decode_plus, 965 size_t *size_out); 966 967 /** 968 Helper function to parse out arguments in a query. 969 970 Parsing a URI like 971 972 http://foo.com/?q=test&s=some+thing 973 974 will result in two entries in the key value queue. 975 976 The first entry is: key="q", value="test" 977 The second entry is: key="s", value="some thing" 978 979 @deprecated This function is deprecated as of Libevent 2.0.9. Use 980 evhttp_uri_parse and evhttp_parse_query_str instead. 981 982 @param uri the request URI 983 @param headers the head of the evkeyval queue 984 @return 0 on success, -1 on failure 985 */ 986 EVENT2_EXPORT_SYMBOL 987 int evhttp_parse_query(const char *uri, struct evkeyvalq *headers); 988 989 /** 990 Helper function to parse out arguments from the query portion of an 991 HTTP URI. 992 993 Parsing a query string like 994 995 q=test&s=some+thing 996 997 will result in two entries in the key value queue. 998 999 The first entry is: key="q", value="test" 1000 The second entry is: key="s", value="some thing" 1001 1002 @param query_parse the query portion of the URI 1003 @param headers the head of the evkeyval queue 1004 @return 0 on success, -1 on failure 1005 */ 1006 EVENT2_EXPORT_SYMBOL 1007 int evhttp_parse_query_str(const char *uri, struct evkeyvalq *headers); 1008 1009 /** 1010 * Escape HTML character entities in a string. 1011 * 1012 * Replaces <, >, ", ' and & with <, >, ", 1013 * ' and & correspondingly. 1014 * 1015 * The returned string needs to be freed by the caller. 1016 * 1017 * @param html an unescaped HTML string 1018 * @return an escaped HTML string or NULL on error 1019 */ 1020 EVENT2_EXPORT_SYMBOL 1021 char *evhttp_htmlescape(const char *html); 1022 1023 /** 1024 * Return a new empty evhttp_uri with no fields set. 1025 */ 1026 EVENT2_EXPORT_SYMBOL 1027 struct evhttp_uri *evhttp_uri_new(void); 1028 1029 /** 1030 * Changes the flags set on a given URI. See EVHTTP_URI_* for 1031 * a list of flags. 1032 **/ 1033 EVENT2_EXPORT_SYMBOL 1034 void evhttp_uri_set_flags(struct evhttp_uri *uri, unsigned flags); 1035 1036 /** Return the scheme of an evhttp_uri, or NULL if there is no scheme has 1037 * been set and the evhttp_uri contains a Relative-Ref. */ 1038 EVENT2_EXPORT_SYMBOL 1039 const char *evhttp_uri_get_scheme(const struct evhttp_uri *uri); 1040 /** 1041 * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo 1042 * set. 1043 */ 1044 EVENT2_EXPORT_SYMBOL 1045 const char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri); 1046 /** 1047 * Return the host part of an evhttp_uri, or NULL if it has no host set. 1048 * The host may either be a regular hostname (conforming to the RFC 3986 1049 * "regname" production), or an IPv4 address, or the empty string, or a 1050 * bracketed IPv6 address, or a bracketed 'IP-Future' address. 1051 * 1052 * Note that having a NULL host means that the URI has no authority 1053 * section, but having an empty-string host means that the URI has an 1054 * authority section with no host part. For example, 1055 * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd" 1056 * has a host of "". 1057 */ 1058 EVENT2_EXPORT_SYMBOL 1059 const char *evhttp_uri_get_host(const struct evhttp_uri *uri); 1060 /** Return the port part of an evhttp_uri, or -1 if there is no port set. */ 1061 EVENT2_EXPORT_SYMBOL 1062 int evhttp_uri_get_port(const struct evhttp_uri *uri); 1063 /** Return the path part of an evhttp_uri, or NULL if it has no path set */ 1064 EVENT2_EXPORT_SYMBOL 1065 const char *evhttp_uri_get_path(const struct evhttp_uri *uri); 1066 /** Return the query part of an evhttp_uri (excluding the leading "?"), or 1067 * NULL if it has no query set */ 1068 EVENT2_EXPORT_SYMBOL 1069 const char *evhttp_uri_get_query(const struct evhttp_uri *uri); 1070 /** Return the fragment part of an evhttp_uri (excluding the leading "#"), 1071 * or NULL if it has no fragment set */ 1072 EVENT2_EXPORT_SYMBOL 1073 const char *evhttp_uri_get_fragment(const struct evhttp_uri *uri); 1074 1075 /** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL. 1076 * Returns 0 on success, -1 if scheme is not well-formed. */ 1077 EVENT2_EXPORT_SYMBOL 1078 int evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme); 1079 /** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL. 1080 * Returns 0 on success, -1 if userinfo is not well-formed. */ 1081 EVENT2_EXPORT_SYMBOL 1082 int evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo); 1083 /** Set the host of an evhttp_uri, or clear the host if host==NULL. 1084 * Returns 0 on success, -1 if host is not well-formed. */ 1085 EVENT2_EXPORT_SYMBOL 1086 int evhttp_uri_set_host(struct evhttp_uri *uri, const char *host); 1087 /** Set the port of an evhttp_uri, or clear the port if port==-1. 1088 * Returns 0 on success, -1 if port is not well-formed. */ 1089 EVENT2_EXPORT_SYMBOL 1090 int evhttp_uri_set_port(struct evhttp_uri *uri, int port); 1091 /** Set the path of an evhttp_uri, or clear the path if path==NULL. 1092 * Returns 0 on success, -1 if path is not well-formed. */ 1093 EVENT2_EXPORT_SYMBOL 1094 int evhttp_uri_set_path(struct evhttp_uri *uri, const char *path); 1095 /** Set the query of an evhttp_uri, or clear the query if query==NULL. 1096 * The query should not include a leading "?". 1097 * Returns 0 on success, -1 if query is not well-formed. */ 1098 EVENT2_EXPORT_SYMBOL 1099 int evhttp_uri_set_query(struct evhttp_uri *uri, const char *query); 1100 /** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL. 1101 * The fragment should not include a leading "#". 1102 * Returns 0 on success, -1 if fragment is not well-formed. */ 1103 EVENT2_EXPORT_SYMBOL 1104 int evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment); 1105 1106 /** 1107 * Helper function to parse a URI-Reference as specified by RFC3986. 1108 * 1109 * This function matches the URI-Reference production from RFC3986, 1110 * which includes both URIs like 1111 * 1112 * scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment] 1113 * 1114 * and relative-refs like 1115 * 1116 * [path][?query][#fragment] 1117 * 1118 * Any optional elements portions not present in the original URI are 1119 * left set to NULL in the resulting evhttp_uri. If no port is 1120 * specified, the port is set to -1. 1121 * 1122 * Note that no decoding is performed on percent-escaped characters in 1123 * the string; if you want to parse them, use evhttp_uridecode or 1124 * evhttp_parse_query_str as appropriate. 1125 * 1126 * Note also that most URI schemes will have additional constraints that 1127 * this function does not know about, and cannot check. For example, 1128 * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable 1129 * mailto url, http://www.example.com:99999/ is not a reasonable HTTP 1130 * URL, and ftp:username@example.com is not a reasonable FTP URL. 1131 * Nevertheless, all of these URLs conform to RFC3986, and this function 1132 * accepts all of them as valid. 1133 * 1134 * @param source_uri the request URI 1135 * @param flags Zero or more EVHTTP_URI_* flags to affect the behavior 1136 * of the parser. 1137 * @return uri container to hold parsed data, or NULL if there is error 1138 * @see evhttp_uri_free() 1139 */ 1140 EVENT2_EXPORT_SYMBOL 1141 struct evhttp_uri *evhttp_uri_parse_with_flags(const char *source_uri, 1142 unsigned flags); 1143 1144 /** Tolerate URIs that do not conform to RFC3986. 1145 * 1146 * Unfortunately, some HTTP clients generate URIs that, according to RFC3986, 1147 * are not conformant URIs. If you need to support these URIs, you can 1148 * do so by passing this flag to evhttp_uri_parse_with_flags. 1149 * 1150 * Currently, these changes are: 1151 * <ul> 1152 * <li> Nonconformant URIs are allowed to contain otherwise unreasonable 1153 * characters in their path, query, and fragment components. 1154 * </ul> 1155 */ 1156 #define EVHTTP_URI_NONCONFORMANT 0x01 1157 1158 /** Alias for evhttp_uri_parse_with_flags(source_uri, 0) */ 1159 EVENT2_EXPORT_SYMBOL 1160 struct evhttp_uri *evhttp_uri_parse(const char *source_uri); 1161 1162 /** 1163 * Free all memory allocated for a parsed uri. Only use this for URIs 1164 * generated by evhttp_uri_parse. 1165 * 1166 * @param uri container with parsed data 1167 * @see evhttp_uri_parse() 1168 */ 1169 EVENT2_EXPORT_SYMBOL 1170 void evhttp_uri_free(struct evhttp_uri *uri); 1171 1172 /** 1173 * Join together the uri parts from parsed data to form a URI-Reference. 1174 * 1175 * Note that no escaping of reserved characters is done on the members 1176 * of the evhttp_uri, so the generated string might not be a valid URI 1177 * unless the members of evhttp_uri are themselves valid. 1178 * 1179 * @param uri container with parsed data 1180 * @param buf destination buffer 1181 * @param limit destination buffer size 1182 * @return an joined uri as string or NULL on error 1183 * @see evhttp_uri_parse() 1184 */ 1185 EVENT2_EXPORT_SYMBOL 1186 char *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit); 1187 1188 #ifdef __cplusplus 1189 } 1190 #endif 1191 1192 #endif /* EVENT2_HTTP_H_INCLUDED_ */ 1193