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
       <https://tools.ietf.org/html/rfc3986> 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
           <https://tools.ietf.org/html/rfc3986#section-2.3> 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
           <https://tools.ietf.org/html/rfc3986#section-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.

           Tip
           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)

                                            2024-10-11                           NNG_URL_PARSE(3)