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