root/opal/mca/event/libevent2022/libevent/include/event2/http.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


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

/* [<][>][^][v][top][bottom][index][help] */