Merge branch 'http_uri_parse'

1 files changed, 151 insertions, 3 deletions

diff --git a/include/event2/http.h b/include/event2/http.h
index a4cbbcc8..5e96934d 100644
--- a/include/event2/http.h
+++ b/include/event2/http.h
@@ -578,7 +578,7 @@ char *evhttp_uridecode(const char *uri, int decode_plus,
 /**
    Helper function to parse out arguments in a query.
 
-   Parsing a uri like
+   Parsing a URI like
 
       http://foo.com/?q=test&s=some+thing
 
@@ -587,17 +587,41 @@ char *evhttp_uridecode(const char *uri, int decode_plus,
    The first entry is: key="q", value="test"
    The second entry is: key="s", value="some thing"
 
+   @deprecated This function is deprecated as of Libevent 2.0.9.  Use
+     evhttp_uri_parse and evhttp_parse_query_str instead.
+
    @param uri the request URI
    @param headers the head of the evkeyval queue
    @return 0 on success, -1 on failure
  */
 #define evhttp_parse_query(uri, headers) \
-	evhttp_parse_query__checked_20((uri), (headers))
+	evhttp_parse_query__checked_20((uri), (headers), 1)
+
+/**
+   Helper function to parse out arguments from the query portion of an
+   HTTP URI.
+
+   Parsing a query string like
+
+     q=test&s=some+thing
+
+   will result in two entries in the key value queue.
+
+   The first entry is: key="q", value="test"
+   The second entry is: key="s", value="some thing"
+
+   @param query_parse the query portion of the URI
+   @param headers the head of the evkeyval queue
+   @return 0 on success, -1 on failure
+ */
+#define evhttp_parse_query_str(query, headers)			\
+	evhttp_parse_query__checked_20((uri), (headers), 0)
 
 /* Do not call this function directly; it is a temporary alias introduced
  * to avoid changing the old signature for evhttp_parse_query
  */
-int evhttp_parse_query__checked_20(const char *uri, struct evkeyvalq *headers);
+int evhttp_parse_query__checked_20(const char *uri, struct evkeyvalq *headers,
+    int is_whole_url);
 
 /**
  * Escape HTML character entities in a string.
@@ -612,6 +636,130 @@ int evhttp_parse_query__checked_20(const char *uri, struct evkeyvalq *headers);
  */
 char *evhttp_htmlescape(const char *html);
 
+/**
+ * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986.
+ */
+struct evhttp_uri;
+
+/**
+ * Return a new empty evhttp_uri with no fields set.
+ */
+struct evhttp_uri *evhttp_uri_new(void);
+
+/** Return the scheme of an evhttp_uri, or NULL if there is no scheme has
+ * been set and the evhttp_uri contains a Relative-Ref. */
+const char *evhttp_uri_get_scheme(const struct evhttp_uri *uri);
+/**
+ * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo
+ * set.
+ */
+const char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri);
+/**
+ * Return the host part of an evhttp_uri, or NULL if it has no host set.
+ * The host may either be a regular hostname (conforming to the RFC 3986
+ * "regname" production), or an IPv4 address, or the empty string, or a
+ * bracketed IPv6 address, or a bracketed 'IP-Future' address.
+ *
+ * Note that having a NULL host means that the URI has no authority
+ * section, but having an empty-string host means that the URI has an
+ * authority section with no host part.  For example,
+ * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd"
+ * has a host of "".
+ */
+const char *evhttp_uri_get_host(const struct evhttp_uri *uri);
+/** Return the port part of an evhttp_uri, or -1 if there is no port set. */
+int evhttp_uri_get_port(const struct evhttp_uri *uri);
+/** Return the path part of an evhttp_uri, or NULL if it has no path set */
+const char *evhttp_uri_get_path(const struct evhttp_uri *uri);
+/** Return the query part of an evhttp_uri (excluding the leading "?"), or
+ * NULL if it has no query set */
+const char *evhttp_uri_get_query(const struct evhttp_uri *uri);
+/** Return the fragment part of an evhttp_uri (excluding the leading "#"),
+ * or NULL if it has no fragment set */
+const char *evhttp_uri_get_fragment(const struct evhttp_uri *uri);
+
+/** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL.
+ * Returns 0 on success, -1 if scheme is not well-formed. */
+int evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme);
+/** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL.
+ * Returns 0 on success, -1 if userinfo is not well-formed. */
+int evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo);
+/** Set the host of an evhttp_uri, or clear the host if host==NULL.
+ * Returns 0 on success, -1 if host is not well-formed. */
+int evhttp_uri_set_host(struct evhttp_uri *uri, const char *host);
+/** Set the port of an evhttp_uri, or clear the port if port==-1.
+ * Returns 0 on success, -1 if port is not well-formed. */
+int evhttp_uri_set_port(struct evhttp_uri *uri, int port);
+/** Set the path of an evhttp_uri, or clear the path if path==NULL.
+ * Returns 0 on success, -1 if path is not well-formed. */
+int evhttp_uri_set_path(struct evhttp_uri *uri, const char *path);
+/** Set the query of an evhttp_uri, or clear the query if query==NULL.
+ * The query should not include a leading "?".
+ * Returns 0 on success, -1 if query is not well-formed. */
+int evhttp_uri_set_query(struct evhttp_uri *uri, const char *query);
+/** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL.
+ * The fragment should not include a leading "#".
+ * Returns 0 on success, -1 if fragment is not well-formed. */
+int evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment);
+
+/**
+ * Helper function to parse a URI-Reference as specified by RFC3986.
+ *
+ * This function matches the URI-Reference production from RFC3986,
+ * which includes both URIs like
+ *
+ *    scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment]
+ *
+ *  and relative-refs like
+ *
+ *    [path][?query][#fragment]
+ *
+ * Any optional elements portions not present in the original URI are
+ * left set to NULL in the resulting evhttp_uri.  If no port is
+ * specified, the port is set to -1.
+ *
+ * Note that no decoding is performed on percent-escaped characters in
+ * the string; if you want to parse them, use evhttp_uridecode or
+ * evhttp_parse_query_str as appropriate.
+ *
+ * Note also that most URI schemes will have additional constraints that
+ * this function does not know about, and cannot check.  For example,
+ * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable
+ * mailto url, http://www.example.com:99999/ is not a reasonable HTTP
+ * URL, and ftp:username@example.com is not a reasonable FTP URL.
+ * Nevertheless, all of these URLs conform to RFC3986, and this function
+ * accepts all of them as valid.
+ *
+ * @param source_uri the request URI
+ * @return uri container to hold parsed data, or NULL if there is error
+ * @see evhttp_uri_free()
+ */
+struct evhttp_uri *evhttp_uri_parse(const char *source_uri);
+
+/**
+ * Free all memory allocated for a parsed uri.  Only use this for URIs
+ * generated by evhttp_uri_parse.
+ *
+ * @param uri container with parsed data
+ * @see evhttp_uri_parse()
+ */
+void evhttp_uri_free(struct evhttp_uri *uri);
+
+/**
+ * Join together the uri parts from parsed data to form a URI-Reference.
+ *
+ * Note that no escaping of reserved characters is done on the members
+ * of the evhttp_uri, so the generated string might not be a valid URI
+ * unless the members of evhttp_uri are themselves valid.
+ *
+ * @param uri container with parsed data
+ * @param buf destination buffer
+ * @param limit destination buffer size
+ * @return an joined uri as string or NULL on error
+   @see evhttp_uri_parse()
+ */
+char *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit);
+
 #ifdef __cplusplus
 }
 #endif