Document behavior of URI parsing more thoroughly.

Also, move evhttp_uri struct into http.h, since it is part of the API.

include/event2/http.h

@@ -607,30 +607,69 @@ int evhttp_parse_query__checked_20(const char *uri, struct evkeyvalq *headers);
  */
 char *evhttp_htmlescape(const char *html);
 
-struct evhttp_uri;
+/**
+ * A structure to hold a parsed URI.
+ */
+struct evhttp_uri {
+	char *scheme; /* scheme; e.g http, ftp etc */
+	char *host; /* hostname, IP address, or NULL */
+	char *userinfo; /* userinfo (typically username:pass), or NULL */
+	int port; /* port, or zero */
+	char *path; /* path, or "". */
+	char *query; /* query, or NULL */
+	char *fragment; /* fragment or NULL */
+};
 
 /**
-   Helper function to parse out uri.
-
-   Parsing a uri like
-
-      scheme://[[user[:pass]@]foo.com[:port]]/[path][?q=test&s=some+thing][#fragment]
-
-   @param source_uri the request URI
-   @return uri container to hold parsed data, or NULL if there is error
-   @see evhttp_uri_free()
+ * 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 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 the memory allocated for the uri and parsed data
+ * 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()
+ * @see evhttp_uri_parse()
  */
 void evhttp_uri_free(struct evhttp_uri *uri);
 
 /**
- * Join together the uri parts from parsed data
+ * 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

include/event2/http_struct.h

@@ -118,20 +118,6 @@ struct {
 	void (*chunk_cb)(struct evhttp_request *, void *);
 };
 
-/**
- * structure to hold parsed uri
- */
-struct evhttp_uri {
-	char *scheme; /* scheme; e.g http, ftp etc */
-	char *host; /* hostname, IP address, or NULL */
-	char *userinfo; /* userinfo (typically username:pass), or NULL */
-	int port; /* port, or zero */
-	char *path; /* path, or NULL */
-	char *query; /* query, or NULL */
-	char *fragment; /* fragment or NULL */
-};
-
-
 #ifdef __cplusplus
 }
 #endif