From 9aa483ebcba67bf1137ff79312315386eda94352 Mon Sep 17 00:00:00 2001 From: Stephan Bosch Date: Sun, 15 May 2016 00:22:12 +0200 Subject: [PATCH] uri-util: Added documentation for all functions in header. --- src/lib/uri-util.h | 133 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 1 deletion(-) diff --git a/src/lib/uri-util.h b/src/lib/uri-util.h index 74bb5a526d..7a7e4bf7e1 100644 --- a/src/lib/uri-util.h +++ b/src/lib/uri-util.h @@ -13,10 +13,11 @@ struct uri_host { }; struct uri_authority { + /* encoded userinfo part; e.g. "user:pass" */ const char *enc_userinfo; struct uri_host host; - in_port_t port; + in_port_t port; /* 0 means no port specified */ }; struct uri_parser { @@ -28,45 +29,130 @@ struct uri_parser { string_t *tmpbuf; }; +/* parse one instance of percent encoding. Returns 1 for success, + 0 if none is preset at the current parser position, and -1 in + case of error. The decoded character is returned in ch_r upon + success */ int uri_parse_pct_encoded(struct uri_parser *parser, unsigned char *ch_r); +/* parse characters as long as these comply with the the 'unreserved' + syntax. Returns 1 if characters were found, 0 if none were found, + and -1 if there was an error */ int uri_parse_unreserved(struct uri_parser *parser, string_t *part); +/* the same as uri_parse_unreserved(), but the allowed characters are + extended to 'unreserved / pct-encoded', meaning that percent encoding + is allowed */ int uri_parse_unreserved_pct(struct uri_parser *parser, string_t *part); +/* decode percent-encoded data from the 'data' parameter, up until the + 'until' parameter. If the latter is NULL, data is decoded up until the + '\0' character. The decoded data is allocated on the parser pool and + returned in decoded_r. Any errors are written to the parser object. */ bool uri_data_decode(struct uri_parser *parser, const char *data, const char *until, const char **decoded_r) ATTR_NULL(3); +/* cut the 'scheme ":"' part from the URI. The uri_p pointer is updated to + point just past the ":". Returns 0 on success and -1 on error. The + result is returned in the scheme_r parameter. This can be NULL to use + this function for merely checking the presence of a valid scheme. */ int uri_cut_scheme(const char **uri_p, const char **scheme_r) ATTR_NULL(2); + +/* parse the URI 'scheme ":"' part. Returns 1 if successful, 0 if the first + character is not valid for a scheme, and -1 in case of error. The + result parameter scheme_r can be NULL to use this function for merely + checking the presence of a valid scheme. */ int uri_parse_scheme(struct uri_parser *parser, const char **scheme_r) ATTR_NULL(2); +/* parse a DNS host name. A host name is a sequence of domain name labels + separated by '.', as defined in Section 3.5 of RFC 1034 and Section + 2.1 of RFC 1123. Returns 1 if successful, 0 if the first character is + not valid for a host name, and -1 in case of error. The result parameter + host_name_r can be NULL to use this function for merely checking the + presence of a valid host name. The result is allocated from the data + stack. + */ int uri_parse_host_name_dns(struct uri_parser *parser, const char **host_name_r) ATTR_NULL(2); +/* parse the URI 'host' syntax, which is either an IP address literal or + a registered (host) name. If dns_name is TRUE, this function expects + a host name, as defined in Section 3.5 of RFC 1034 and Section + 2.1 of RFC 1123. Otherwise, a generic registered name syntax is allowed. + An IP address literal is always allowed. Returns 1 if successful, 0 if + the first character is not valid for a host name, and -1 in case of + error. The provided host struct is filled in with the parsed data, all + allocated from the parser pool. The host parameter can be NULL to use + this function for merely checking for valid 'host' syntax. + */ int uri_parse_host(struct uri_parser *parser, struct uri_host *host, bool dns_name) ATTR_NULL(2); +/* parse the URI 'authority' syntax. If dns_name is TRUE, this function + expects a host name for the 'host' part, as defined in Section 3.5 of + RFC 1034 and Section 2.1 of RFC 1123. Otherwise, a generic registered + name syntax is allowed. Returns 1 if successful, 0 if the first + character is not valid for the 'authority' syntax and -1 in case of + error. The provided uri_authority struct is filled in with the parsed + data, all allocated from the parser pool. The auth parameter can be + NULL to use this function for merely checking for valid 'authority' + syntax. + */ int uri_parse_authority(struct uri_parser *parser, struct uri_authority *auth, bool dns_name) ATTR_NULL(2); +/* identical to uri_parse_authority(), except that this function parses + '"//" authority', rather than 'authority'. + */ int uri_parse_slashslash_authority(struct uri_parser *parser, struct uri_authority *auth, bool dns_name) ATTR_NULL(2); +/* parse the URI 'segment' syntax. Returns 1 if successful, 0 if the first + character is not valid for the 'segment' syntax and -1 in case of + error. The result is allocated from the parser pool. Percent encoding is + not decoded in the result. The result parameter can be NULL to use this + function for merely checking for valid 'segment' syntax. + */ int uri_parse_path_segment(struct uri_parser *parser, const char **segment_r) ATTR_NULL(2); +/* parse the URI 'path' syntax. This also resolves '..' and '.' segments in + the path. If the path is relative, the relative_r parameter indicates + how many segments the base path must be moved towards root (as caused by + leading '..' segments). Returns 1 if successful, 0 if the first character + is not valid for the 'segment' syntax and -1 in case of error. The result + is a NULL-terminated string list allocated from the parser pool. Percent + encoding is not decoded in the result. The result parameter can be NULL + to use this function for merely checking for valid 'path' syntax. + */ int uri_parse_path(struct uri_parser *parser, int *relative_r, const char *const **path_r) ATTR_NULL(2,3); +/* parse the URI 'query' syntax. Returns 1 if successful, 0 if the first + character is not valid for the 'query' syntax and -1 in case of + error. The result is allocated from the parser pool. Percent encoding is + not decoded in the result. The result parameter can be NULL to use this + function for merely checking for valid 'query' syntax. + */ int uri_parse_query(struct uri_parser *parser, const char **query_r) ATTR_NULL(2); +/* parse the URI 'fragment' syntax. Returns 1 if successful, 0 if the first + character is not valid for the 'fragment' syntax and -1 in case of + error. The result is allocated from the parser pool. Percent encoding is + not decoded in the result. The result parameter can be NULL to use this + function for merely checking for valid 'fragment' syntax. + */ int uri_parse_fragment(struct uri_parser *parser, const char **fragment_r) ATTR_NULL(2); +/* initialize the URI parser with the provided data */ void uri_parser_init_data(struct uri_parser *parser, pool_t pool, const unsigned char *data, size_t size); +/* initialize the URI parser with the provided '\0'-terminated string */ void uri_parser_init(struct uri_parser *parser, pool_t pool, const char *uri); +/* returns the temporary buffer associated with this parser. Can be used + for higher-level parsing activities. */ string_t *uri_parser_get_tmpbuf(struct uri_parser *parser, size_t size); @@ -74,6 +160,7 @@ string_t *uri_parser_get_tmpbuf(struct uri_parser *parser, * Generic URI manipulation */ +/* copy uri_host struct from src to dest and allocate it on pool */ void uri_host_copy(pool_t pool, struct uri_host *dest, const struct uri_host *src); @@ -81,35 +168,79 @@ void uri_host_copy(pool_t pool, struct uri_host *dest, * Generic URI construction */ +/* encodes the '\0'-terminated data using the percent encoding. The + esc_table is a 256 byte lookup table. If none of the esc_mask bits are + set at the character's position in the esc_table, a character needs + to be encoded. Also, when esc_extra contains a character, it needs to + be encoded. All other characters are copied verbatim to the out buffer. + */ void uri_data_encode(string_t *out, const unsigned char esc_table[256], unsigned char esc_mask, const char *esc_extra, const char *data) ATTR_NULL(4); +/* append the provided scheme to the out buffer */ void uri_append_scheme(string_t *out, const char *scheme); +/* append partial user data (i.e. some part of what comes before '@') to + the out buffer. No '@' is produced. Characters are percent-encoded when + necessary. Characters in esc are always percent-encoded, even when these + are valid 'userinfo' characters. */ void uri_append_user_data(string_t *out, const char *esc, const char *data) ATTR_NULL(2); +/* append userinfo and '@' to the out buffer. Characters in userinfo are + percent-encoded when necessary.*/ void uri_append_userinfo(string_t *out, const char *userinfo); +/* append the host name to the out buffer. Characters are percent-encoded + when necessary.*/ void uri_append_host_name(string_t *out, const char *name); +/* append the host IP address to the out buffer. */ void uri_append_host_ip(string_t *out, const struct ip_addr *host_ip); +/* encode the URI host struct to the out buffer. */ void uri_append_host(string_t *out, const struct uri_host *host); +/* append the port to the out buffer. */ void uri_append_port(string_t *out, in_port_t port); +/* append partial path segment data to the out buffer. No '/' is produced. + Characters are percent-encoded when necessary. Characters in esc are + always percent-encoded, even when these are valid 'segment' characters. + */ void uri_append_path_segment_data(string_t *out, const char *esc, const char *data) ATTR_NULL(2); +/* append a full path segment to the out buffer. A leading '/' is + produced. Characters are percent-encoded when necessary. */ void uri_append_path_segment(string_t *out, const char *segment); +/* append partial path data to the out buffer. The data may include '/', + which is not encoded. Characters are percent-encoded when necessary. + Characters in esc are always percent-encoded, even when these are + valid 'path' characters.*/ void uri_append_path_data(string_t *out, const char *esc, const char *data) ATTR_NULL(2); +/* append a full path to the out buffer. A leading '/' is produced. The + data may include more '/', which is not encoded. Characters are + percent-encoded when necessary. + */ void uri_append_path(string_t *out, const char *path); +/* append partial query data to the out buffer. No leading '?' is + produced. Characters are percent-encoded when necessary. Characters + in esc are always percent-encoded, even when these are valid 'query' + characters.*/ void uri_append_query_data(string_t *out, const char *esc, const char *data) ATTR_NULL(2); +/* append a full URI query part to the out buffer. A leading '?' is + produced. Characters are percent-encoded when necessary. */ void uri_append_query(string_t *out, const char *query); +/* append partial fragment data to the out buffer. No leading '#' is + produced. Characters are percent-encoded when necessary. Characters + in esc are always percent-encoded, even when these are valid + 'fragment' characters.*/ void uri_append_fragment_data(string_t *out, const char *esc, const char *data) ATTR_NULL(2); +/* append a full URI fragment part to the out buffer. A leading '#' is + produced. Characters are percent-encoded when necessary. */ void uri_append_fragment(string_t *out, const char *fragment); #endif