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