This documentation is for the TIP (development tree) of NNG and may represent unreleased changes or functionality that is experimental, and is subject to change before release. The latest released version is v1.8.0. See the documentation for v1.8.0 for the most up-to-date information.

nng_url_parse(3)

NAME

nng_url_parse - create URL structure from a string

SYNOPSIS

#include <nng/nng.h>

int nng_url_parse(nng_url **urlp, const char *str);

DESCRIPTION

The nng_url_parse() function parses the string str containing an RFC 3986 compliant URL, and creates an nng_url structure containing the results. A pointer to the resulting structure is stored in urlp.

The structure may disposed of when no longer needed by calling nng_url_free().

URL Canonicalization

The nng_url_parse() function also canonicalizes the results, as follows:

  1. The URL is parsed into the various components.

  2. The u_scheme, u_hostname, u_host, and u_port members are converted to lower case.

  3. Percent-encoded values for unreserved characters converted to their unencoded forms.

  4. Additionally URL percent-encoded values for characters in the path and with numeric values larger than 127 (i.e. not ASCII) are decoded.

  5. The resulting u_path is checked for invalid UTF-8 sequences, consisting of surrogate pairs, illegal byte sequences, or overlong encodings. If this check fails, then the entire URL is considered invalid, and the function returns NNG_EINVAL.

  6. Path segments consisting of . and .. are resolved as per RFC 3986 6.2.2.3.

  7. Further, empty path segments are removed, meaning that duplicate slash (/) separators are removed from the path.

  8. If a port was not specified, but the scheme defines a default port, then u_port will be filled in with the value of the default port.

Only the u_userinfo, u_query, and u_fragment members will ever be NULL. The other members will be filled in with either default values or the empty string if they cannot be determined from str.

RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

ERRORS

NNG_ENOMEM

Insufficient free memory exists to allocate a message.
NNG_EINVAL

An invalid URL was supplied.

SEE ALSO

nng_url_clone(3), nng_url_free(3), nng_strerror(3), nng_url(5), nng(7)