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