2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2010 Niels Provos and Nick Mathewson
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
27 #ifndef _EVENT2_HTTP_H_
28 #define _EVENT2_HTTP_H_
31 #include <event2/util.h>
37 /* In case we haven't included the right headers yet. */
43 * Basic support for HTTP serving.
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.
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 */
68 struct evhttp_request;
70 struct evhttp_bound_socket;
71 struct evconnlistener;
74 * Create a new HTTP server.
76 * @param base (optional) the event base to receive the HTTP events
77 * @return a pointer to a newly initialized evhttp server structure
80 struct evhttp *evhttp_new(struct event_base *base);
83 * Binds an HTTP server on the specified address and port.
85 * Can be called multiple times to bind the same http server
86 * to multiple different ports.
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()
94 int evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port);
97 * Like evhttp_bind_socket(), but returns a handle for referencing the socket.
99 * The returned pointer is not valid after \a http is freed.
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()
107 struct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port);
110 * Makes an HTTP server accept connections on the specified socket.
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.
117 * Can be called multiple times to have the http server listen to
118 * multiple different sockets.
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()
125 int evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd);
128 * Like evhttp_accept_socket(), but returns a handle for referencing the socket.
130 * The returned pointer is not valid after \a http is freed.
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()
137 struct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd);
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
144 struct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener);
147 * Return the listener used to implement a bound socket.
149 struct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound);
152 * Makes an HTTP server stop accepting connections on the specified socket
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.
157 * This function does not close the socket.
159 * \a bound_socket is an invalid pointer after this call returns.
161 * @param http a pointer to an evhttp object
162 * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
163 * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
165 void evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket);
168 * Get the raw file descriptor referenced by an evhttp_bound_socket.
170 * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
171 * @return the file descriptor used by the bound socket
172 * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
174 evutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket);
177 * Free the previously created HTTP server.
179 * Works only if no requests are currently being served.
181 * @param http the evhttp server object to be freed
182 * @see evhttp_start()
184 void evhttp_free(struct evhttp* http);
187 void evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size);
189 void evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size);
192 Sets the what HTTP methods are supported in requests accepted by this
193 server, and passed to user callbacks.
195 If not supported they will generate a "405 Method not allowed" response.
197 By default this includes the following methods: GET, POST, HEAD, PUT, DELETE
199 @param http the http server on which to set the methods
200 @param methods bit mask constructed from evhttp_cmd_type values
202 void evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods);
205 Set a callback for a specified URI
207 @param http the http sever on which to set the callback
208 @param path the path for which to invoke the callback
209 @param cb the callback function that gets invoked on requesting path
210 @param cb_arg an additional context argument for the callback
211 @return 0 on success, -1 if the callback existed already, -2 on failure
213 int evhttp_set_cb(struct evhttp *http, const char *path,
214 void (*cb)(struct evhttp_request *, void *), void *cb_arg);
216 /** Removes the callback for a specified URI */
217 int evhttp_del_cb(struct evhttp *, const char *);
220 Set a callback for all requests that are not caught by specific callbacks
222 Invokes the specified callback for all requests that do not match any of
223 the previously specified request paths. This is catchall for requests not
224 specifically configured with evhttp_set_cb().
226 @param http the evhttp server object for which to set the callback
227 @param cb the callback to invoke for any unmatched requests
228 @param arg an context argument for the callback
230 void evhttp_set_gencb(struct evhttp *http,
231 void (*cb)(struct evhttp_request *, void *), void *arg);
234 Adds a virtual host to the http server.
236 A virtual host is a newly initialized evhttp object that has request
237 callbacks set on it via evhttp_set_cb() or evhttp_set_gencb(). It
238 most not have any listing sockets associated with it.
240 If the virtual host has not been removed by the time that evhttp_free()
241 is called on the main http server, it will be automatically freed, too.
243 It is possible to have hierarchical vhosts. For example: A vhost
244 with the pattern *.example.com may have other vhosts with patterns
245 foo.example.com and bar.example.com associated with it.
247 @param http the evhttp object to which to add a virtual host
248 @param pattern the glob pattern against which the hostname is matched.
249 The match is case insensitive and follows otherwise regular shell
251 @param vhost the virtual host to add the regular http server.
252 @return 0 on success, -1 on failure
253 @see evhttp_remove_virtual_host()
255 int evhttp_add_virtual_host(struct evhttp* http, const char *pattern,
256 struct evhttp* vhost);
259 Removes a virtual host from the http server.
261 @param http the evhttp object from which to remove the virtual host
262 @param vhost the virtual host to remove from the regular http server.
263 @return 0 on success, -1 on failure
264 @see evhttp_add_virtual_host()
266 int evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost);
269 Add a server alias to an http object. The http object can be a virtual
270 host or the main server.
272 @param http the evhttp object
273 @param alias the alias to add
274 @see evhttp_add_remove_alias()
276 int evhttp_add_server_alias(struct evhttp *http, const char *alias);
279 Remove a server alias from an http object.
281 @param http the evhttp object
282 @param alias the alias to remove
283 @see evhttp_add_server_alias()
285 int evhttp_remove_server_alias(struct evhttp *http, const char *alias);
288 * Set the timeout for an HTTP request.
290 * @param http an evhttp object
291 * @param timeout_in_secs the timeout, in seconds
293 void evhttp_set_timeout(struct evhttp *http, int timeout_in_secs);
295 /* Request/Response functionality */
298 * Send an HTML error message to the client.
300 * @param req a request object
301 * @param error the HTTP error code
302 * @param reason a brief explanation of the error. If this is NULL, we'll
303 * just use the standard meaning of the error code.
305 void evhttp_send_error(struct evhttp_request *req, int error,
309 * Send an HTML reply to the client.
311 * The body of the reply consists of the data in databuf. After calling
312 * evhttp_send_reply() databuf will be empty, but the buffer is still
313 * owned by the caller and needs to be deallocated by the caller if
316 * @param req a request object
317 * @param code the HTTP response code to send
318 * @param reason a brief message to send with the response code
319 * @param databuf the body of the response
321 void evhttp_send_reply(struct evhttp_request *req, int code,
322 const char *reason, struct evbuffer *databuf);
324 /* Low-level response interface, for streaming/chunked replies */
327 Initiate a reply that uses Transfer-Encoding chunked.
329 This allows the caller to stream the reply back to the client and is
330 useful when either not all of the reply data is immediately available
331 or when sending very large replies.
333 The caller needs to supply data chunks with evhttp_send_reply_chunk()
334 and complete the reply by calling evhttp_send_reply_end().
336 @param req a request object
337 @param code the HTTP response code to send
338 @param reason a brief message to send with the response code
340 void evhttp_send_reply_start(struct evhttp_request *req, int code,
344 Send another data chunk as part of an ongoing chunked reply.
346 The reply chunk consists of the data in databuf. After calling
347 evhttp_send_reply_chunk() databuf will be empty, but the buffer is
348 still owned by the caller and needs to be deallocated by the caller
351 @param req a request object
352 @param databuf the data chunk to send as part of the reply.
354 void evhttp_send_reply_chunk(struct evhttp_request *req,
355 struct evbuffer *databuf);
357 Complete a chunked reply.
359 @param req a request object
361 void evhttp_send_reply_end(struct evhttp_request *req);
364 * Interfaces for making requests
367 /** The different request types supported by evhttp. These are as specified
368 * in RFC2616, except for PATCH which is specified by RFC5789.
370 * By default, only some of these methods are accepted and passed to user
371 * callbacks; use evhttp_set_allowed_methods() to change which methods
374 enum evhttp_cmd_type {
375 EVHTTP_REQ_GET = 1 << 0,
376 EVHTTP_REQ_POST = 1 << 1,
377 EVHTTP_REQ_HEAD = 1 << 2,
378 EVHTTP_REQ_PUT = 1 << 3,
379 EVHTTP_REQ_DELETE = 1 << 4,
380 EVHTTP_REQ_OPTIONS = 1 << 5,
381 EVHTTP_REQ_TRACE = 1 << 6,
382 EVHTTP_REQ_CONNECT = 1 << 7,
383 EVHTTP_REQ_PATCH = 1 << 8
386 /** a request object can represent either a request or a reply */
387 enum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE };
390 * Creates a new request object that needs to be filled in with the request
391 * parameters. The callback is executed when the request completed or an
394 struct evhttp_request *evhttp_request_new(
395 void (*cb)(struct evhttp_request *, void *), void *arg);
398 * Enable delivery of chunks to requestor.
399 * @param cb will be called after every read of data with the same argument
400 * as the completion callback. Will never be called on an empty
401 * response. May drain the input buffer; it will be drained
402 * automatically on return.
404 void evhttp_request_set_chunked_cb(struct evhttp_request *,
405 void (*cb)(struct evhttp_request *, void *));
407 /** Frees the request object and removes associated events. */
408 void evhttp_request_free(struct evhttp_request *req);
413 * A connection object that can be used to for making HTTP requests. The
414 * connection object tries to resolve address and establish the connection
415 * when it is given an http request object.
417 * @param base the event_base to use for handling the connection
418 * @param dnsbase the dns_base to use for resolving host names; if not
419 * specified host name resolution will block.
420 * @param address the address to which to connect
421 * @param port the port to connect to
422 * @return an evhttp_connection object that can be used for making requests
424 struct evhttp_connection *evhttp_connection_base_new(
425 struct event_base *base, struct evdns_base *dnsbase,
426 const char *address, unsigned short port);
428 /** Takes ownership of the request object
430 * Can be used in a request callback to keep onto the request until
431 * evhttp_request_free() is explicitly called by the user.
433 void evhttp_request_own(struct evhttp_request *req);
435 /** Returns 1 if the request is owned by the user */
436 int evhttp_request_is_owned(struct evhttp_request *req);
439 * Returns the connection object associated with the request or NULL
441 * The user needs to either free the request explicitly or call
442 * evhttp_send_reply_end().
444 struct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req);
447 * Returns the underlying event_base for this connection
449 struct event_base *evhttp_connection_get_base(struct evhttp_connection *req);
451 void evhttp_connection_set_max_headers_size(struct evhttp_connection *evcon,
452 ev_ssize_t new_max_headers_size);
454 void evhttp_connection_set_max_body_size(struct evhttp_connection* evcon,
455 ev_ssize_t new_max_body_size);
457 /** Frees an http connection */
458 void evhttp_connection_free(struct evhttp_connection *evcon);
460 /** sets the ip address from which http connections are made */
461 void evhttp_connection_set_local_address(struct evhttp_connection *evcon,
462 const char *address);
464 /** sets the local port from which http connections are made */
465 void evhttp_connection_set_local_port(struct evhttp_connection *evcon,
468 /** Sets the timeout for events related to this connection */
469 void evhttp_connection_set_timeout(struct evhttp_connection *evcon,
470 int timeout_in_secs);
472 /** Sets the retry limit for this connection - -1 repeats indefinitely */
473 void evhttp_connection_set_retries(struct evhttp_connection *evcon,
476 /** Set a callback for connection close. */
477 void evhttp_connection_set_closecb(struct evhttp_connection *evcon,
478 void (*)(struct evhttp_connection *, void *), void *);
480 /** Get the remote address and port associated with this connection. */
481 void evhttp_connection_get_peer(struct evhttp_connection *evcon,
482 char **address, ev_uint16_t *port);
485 Make an HTTP request over the specified connection.
487 The connection gets ownership of the request. On failure, the
488 request object is no longer valid as it has been freed.
490 @param evcon the evhttp_connection object over which to send the request
491 @param req the previously created and configured request object
492 @param type the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc.
493 @param uri the URI associated with the request
494 @return 0 on success, -1 on failure
495 @see evhttp_cancel_request()
497 int evhttp_make_request(struct evhttp_connection *evcon,
498 struct evhttp_request *req,
499 enum evhttp_cmd_type type, const char *uri);
502 Cancels a pending HTTP request.
504 Cancels an ongoing HTTP request. The callback associated with this request
505 is not executed and the request object is freed. If the request is
506 currently being processed, e.g. it is ongoing, the corresponding
507 evhttp_connection object is going to get reset.
509 A request cannot be canceled if its callback has executed already. A request
510 may be canceled reentrantly from its chunked callback.
512 @param req the evhttp_request to cancel; req becomes invalid after this call.
514 void evhttp_cancel_request(struct evhttp_request *req);
517 * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986.
521 /** Returns the request URI */
522 const char *evhttp_request_get_uri(const struct evhttp_request *req);
523 /** Returns the request URI (parsed) */
524 const struct evhttp_uri *evhttp_request_get_evhttp_uri(const struct evhttp_request *req);
525 /** Returns the request command */
526 enum evhttp_cmd_type evhttp_request_get_command(const struct evhttp_request *req);
528 int evhttp_request_get_response_code(const struct evhttp_request *req);
530 /** Returns the input headers */
531 struct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req);
532 /** Returns the output headers */
533 struct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req);
534 /** Returns the input buffer */
535 struct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req);
536 /** Returns the output buffer */
537 struct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req);
538 /** Returns the host associated with the request. If a client sends an absolute
539 URI, the host part of that is preferred. Otherwise, the input headers are
540 searched for a Host: header. NULL is returned if no absolute URI or Host:
541 header is provided. */
542 const char *evhttp_request_get_host(struct evhttp_request *req);
544 /* Interfaces for dealing with HTTP headers */
547 Finds the value belonging to a header.
549 @param headers the evkeyvalq object in which to find the header
550 @param key the name of the header to find
551 @returns a pointer to the value for the header or NULL if the header
553 @see evhttp_add_header(), evhttp_remove_header()
555 const char *evhttp_find_header(const struct evkeyvalq *headers,
559 Removes a header from a list of existing headers.
561 @param headers the evkeyvalq object from which to remove a header
562 @param key the name of the header to remove
563 @returns 0 if the header was removed, -1 otherwise.
564 @see evhttp_find_header(), evhttp_add_header()
566 int evhttp_remove_header(struct evkeyvalq *headers, const char *key);
569 Adds a header to a list of existing headers.
571 @param headers the evkeyvalq object to which to add a header
572 @param key the name of the header
573 @param value the value belonging to the header
574 @returns 0 on success, -1 otherwise.
575 @see evhttp_find_header(), evhttp_clear_headers()
577 int evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value);
580 Removes all headers from the header list.
582 @param headers the evkeyvalq object from which to remove all headers
584 void evhttp_clear_headers(struct evkeyvalq *headers);
586 /* Miscellaneous utility functions */
590 Helper function to encode a string for inclusion in a URI. All
591 characters are replaced by their hex-escaped (%22) equivalents,
592 except for characters explicitly unreserved by RFC3986 -- that is,
593 ASCII alphanumeric characters, hyphen, dot, underscore, and tilde.
595 The returned string must be freed by the caller.
597 @param str an unencoded string
598 @return a newly allocated URI-encoded string or NULL on failure
600 char *evhttp_encode_uri(const char *str);
603 As evhttp_encode_uri, but if 'size' is nonnegative, treat the string
604 as being 'size' bytes long. This allows you to encode strings that
605 may contain 0-valued bytes.
607 The returned string must be freed by the caller.
609 @param str an unencoded string
610 @param size the length of the string to encode, or -1 if the string
612 @param space_to_plus if true, space characters in 'str' are encoded
614 @return a newly allocate URI-encoded string, or NULL on failure.
616 char *evhttp_uriencode(const char *str, ev_ssize_t size, int space_to_plus);
619 Helper function to sort of decode a URI-encoded string. Unlike
620 evhttp_get_decoded_uri, it decodes all plus characters that appear
621 _after_ the first question mark character, but no plusses that occur
622 before. This is not a good way to decode URIs in whole or in part.
624 The returned string must be freed by the caller
626 @deprecated This function is deprecated; you probably want to use
627 evhttp_get_decoded_uri instead.
629 @param uri an encoded URI
630 @return a newly allocated unencoded URI or NULL on failure
632 char *evhttp_decode_uri(const char *uri);
635 Helper function to decode a URI-escaped string or HTTP parameter.
637 If 'decode_plus' is 1, then we decode the string as an HTTP parameter
638 value, and convert all plus ('+') characters to spaces. If
639 'decode_plus' is 0, we leave all plus characters unchanged.
641 The returned string must be freed by the caller.
643 @param uri a URI-encode encoded URI
644 @param decode_plus determines whether we convert '+' to sapce.
645 @param size_out if size_out is not NULL, *size_out is set to the size of the
647 @return a newly allocated unencoded URI or NULL on failure
649 char *evhttp_uridecode(const char *uri, int decode_plus,
653 Helper function to parse out arguments in a query.
657 http://foo.com/?q=test&s=some+thing
659 will result in two entries in the key value queue.
661 The first entry is: key="q", value="test"
662 The second entry is: key="s", value="some thing"
664 @deprecated This function is deprecated as of Libevent 2.0.9. Use
665 evhttp_uri_parse and evhttp_parse_query_str instead.
667 @param uri the request URI
668 @param headers the head of the evkeyval queue
669 @return 0 on success, -1 on failure
671 int evhttp_parse_query(const char *uri, struct evkeyvalq *headers);
674 Helper function to parse out arguments from the query portion of an
677 Parsing a query string like
681 will result in two entries in the key value queue.
683 The first entry is: key="q", value="test"
684 The second entry is: key="s", value="some thing"
686 @param query_parse the query portion of the URI
687 @param headers the head of the evkeyval queue
688 @return 0 on success, -1 on failure
690 int evhttp_parse_query_str(const char *uri, struct evkeyvalq *headers);
693 * Escape HTML character entities in a string.
695 * Replaces <, >, ", ' and & with <, >, ",
696 * ' and & correspondingly.
698 * The returned string needs to be freed by the caller.
700 * @param html an unescaped HTML string
701 * @return an escaped HTML string or NULL on error
703 char *evhttp_htmlescape(const char *html);
706 * Return a new empty evhttp_uri with no fields set.
708 struct evhttp_uri *evhttp_uri_new(void);
710 /** Return the scheme of an evhttp_uri, or NULL if there is no scheme has
711 * been set and the evhttp_uri contains a Relative-Ref. */
712 const char *evhttp_uri_get_scheme(const struct evhttp_uri *uri);
714 * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo
717 const char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri);
719 * Return the host part of an evhttp_uri, or NULL if it has no host set.
720 * The host may either be a regular hostname (conforming to the RFC 3986
721 * "regname" production), or an IPv4 address, or the empty string, or a
722 * bracketed IPv6 address, or a bracketed 'IP-Future' address.
724 * Note that having a NULL host means that the URI has no authority
725 * section, but having an empty-string host means that the URI has an
726 * authority section with no host part. For example,
727 * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd"
730 const char *evhttp_uri_get_host(const struct evhttp_uri *uri);
731 /** Return the port part of an evhttp_uri, or -1 if there is no port set. */
732 int evhttp_uri_get_port(const struct evhttp_uri *uri);
733 /** Return the path part of an evhttp_uri, or NULL if it has no path set */
734 const char *evhttp_uri_get_path(const struct evhttp_uri *uri);
735 /** Return the query part of an evhttp_uri (excluding the leading "?"), or
736 * NULL if it has no query set */
737 const char *evhttp_uri_get_query(const struct evhttp_uri *uri);
738 /** Return the fragment part of an evhttp_uri (excluding the leading "#"),
739 * or NULL if it has no fragment set */
740 const char *evhttp_uri_get_fragment(const struct evhttp_uri *uri);
742 /** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL.
743 * Returns 0 on success, -1 if scheme is not well-formed. */
744 int evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme);
745 /** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL.
746 * Returns 0 on success, -1 if userinfo is not well-formed. */
747 int evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo);
748 /** Set the host of an evhttp_uri, or clear the host if host==NULL.
749 * Returns 0 on success, -1 if host is not well-formed. */
750 int evhttp_uri_set_host(struct evhttp_uri *uri, const char *host);
751 /** Set the port of an evhttp_uri, or clear the port if port==-1.
752 * Returns 0 on success, -1 if port is not well-formed. */
753 int evhttp_uri_set_port(struct evhttp_uri *uri, int port);
754 /** Set the path of an evhttp_uri, or clear the path if path==NULL.
755 * Returns 0 on success, -1 if path is not well-formed. */
756 int evhttp_uri_set_path(struct evhttp_uri *uri, const char *path);
757 /** Set the query of an evhttp_uri, or clear the query if query==NULL.
758 * The query should not include a leading "?".
759 * Returns 0 on success, -1 if query is not well-formed. */
760 int evhttp_uri_set_query(struct evhttp_uri *uri, const char *query);
761 /** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL.
762 * The fragment should not include a leading "#".
763 * Returns 0 on success, -1 if fragment is not well-formed. */
764 int evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment);
767 * Helper function to parse a URI-Reference as specified by RFC3986.
769 * This function matches the URI-Reference production from RFC3986,
770 * which includes both URIs like
772 * scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment]
774 * and relative-refs like
776 * [path][?query][#fragment]
778 * Any optional elements portions not present in the original URI are
779 * left set to NULL in the resulting evhttp_uri. If no port is
780 * specified, the port is set to -1.
782 * Note that no decoding is performed on percent-escaped characters in
783 * the string; if you want to parse them, use evhttp_uridecode or
784 * evhttp_parse_query_str as appropriate.
786 * Note also that most URI schemes will have additional constraints that
787 * this function does not know about, and cannot check. For example,
788 * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable
789 * mailto url, http://www.example.com:99999/ is not a reasonable HTTP
790 * URL, and ftp:username@example.com is not a reasonable FTP URL.
791 * Nevertheless, all of these URLs conform to RFC3986, and this function
792 * accepts all of them as valid.
794 * @param source_uri the request URI
795 * @return uri container to hold parsed data, or NULL if there is error
796 * @see evhttp_uri_free()
798 struct evhttp_uri *evhttp_uri_parse(const char *source_uri);
801 * Free all memory allocated for a parsed uri. Only use this for URIs
802 * generated by evhttp_uri_parse.
804 * @param uri container with parsed data
805 * @see evhttp_uri_parse()
807 void evhttp_uri_free(struct evhttp_uri *uri);
810 * Join together the uri parts from parsed data to form a URI-Reference.
812 * Note that no escaping of reserved characters is done on the members
813 * of the evhttp_uri, so the generated string might not be a valid URI
814 * unless the members of evhttp_uri are themselves valid.
816 * @param uri container with parsed data
817 * @param buf destination buffer
818 * @param limit destination buffer size
819 * @return an joined uri as string or NULL on error
820 @see evhttp_uri_parse()
822 char *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit);
828 #endif /* _EVENT2_HTTP_H_ */