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