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