diff options
| -rw-r--r-- | docs/man/nng_url.5.adoc | 39 | ||||
| -rw-r--r-- | docs/man/nng_url_clone.3.adoc | 8 | ||||
| -rw-r--r-- | docs/man/nng_url_free.3.adoc | 3 | ||||
| -rw-r--r-- | docs/man/nng_url_parse.3.adoc | 27 |
4 files changed, 38 insertions, 39 deletions
diff --git a/docs/man/nng_url.5.adoc b/docs/man/nng_url.5.adoc index e9e59bbc..9fed7e0a 100644 --- a/docs/man/nng_url.5.adoc +++ b/docs/man/nng_url.5.adoc @@ -1,4 +1,4 @@ -= nng_sockaddr(5) += nng_url(5) // // Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // @@ -19,16 +19,16 @@ nng_url - Universal Resource Locator object #include <nng/nng.h> typedef struct nng_url { - char *u_rawurl; // never NULL - char *u_scheme; // never NULL - char *u_userinfo; // will be NULL if not specified - char *u_host; // including colon and port - char *u_hostname; // name only, will be "" if not specified - char *u_port; // port, will be "" if not specified - char *u_path; // path, will be "" if not specified - char *u_query; // without '?', will be NULL if not specified - char *u_fragment; // without '#', will be NULL if not specified - char *u_requri; // includes query and fragment, "" if not specified + char *u_rawurl; + char *u_scheme; + char *u_userinfo; + char *u_host; + char *u_hostname; + char *u_port; + char *u_path; + char *u_query; + char *u_fragment; + char *u_requri; } nng_url; ---- @@ -46,16 +46,21 @@ alter them, as the underlying memory is managed by the library. The fields are as follows: [horizontal] -`u_rawurl`:: The raw URL string, un-modified. This will never be `NULL`. -`u_scheme`:: The URL scheme, such as "`http`" or "`inproc`". This will never be `NULL`. +`u_rawurl`:: The unparsed URL string. This will never be `NULL`. +`u_scheme`:: The URL scheme, such as "`http`" or "`inproc`". Always lower case. This will never be `NULL`. `u_userinfo`:: This username and password if supplied in the URL string. Will be `NULL` when not present. -`u_host`:: The full host and port, separated by a colon. +`u_host`:: The full host part of the URL, including the port if present (separated by a colon.) `u_hostname`:: The name of the host, and may be the empty string in some cases. `u_port`:: The port. May be empty if irrelevant or not specified. -`u_path`:: The extended path, typically used with HTTP or WebSockets. Will be empty string if not specified. -`u_query`:: The query string (typically following `?` in the URL.) Will be `NULL` if not present. +`u_path`:: The path, typically used with HTTP or WebSockets. Will be empty string if not specified. +`u_query`:: The query info (typically following `?` in the URL.) Will be `NULL` if not present. `u_fragment`:: This is used for specifying an anchor, the part after `#` in a URL. Will be `NULL` if not present. -`u_requri`:: The full URI (the part after the host and port). Will be the empty string if not specified. +`u_requri`:: The full Request-URI (path[?query][#fragment]). Will be the empty string if not specified. + +NOTE: Other fields may also be present, but only those documented here are safe for application use. + +TIP: More information about Universal Resource Locators can be found in +https://tools.ietf.org/html/rfc3986[RFC 3986]. == SEE ALSO diff --git a/docs/man/nng_url_clone.3.adoc b/docs/man/nng_url_clone.3.adoc index b77f316f..0e6ef15f 100644 --- a/docs/man/nng_url_clone.3.adoc +++ b/docs/man/nng_url_clone.3.adoc @@ -1,6 +1,6 @@ = nng_url_clone(3) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -28,6 +28,11 @@ The `nng_url_clone()` makes a clone of the original URL structure _orig_, and saves the result in the location pointed by _dup_. This clone includes fully duplicating each of the member fields. +The new +xref:nng_url.5.adoc[`nng_url`] structure can be disposed of +using +xref:nng_url_free.3.adoc[`nng_url_free()`] when it is no longer needed. + == RETURN VALUES This function returns 0 on success, and non-zero otherwise. @@ -43,4 +48,5 @@ This function returns 0 on success, and non-zero otherwise. xref:nng_url_free.3.adoc[nng_url_free(3)], xref:nng_url_parse.3.adoc[nng_url_parse(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_url.5.adoc[nng_url(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_url_free.3.adoc b/docs/man/nng_url_free.3.adoc index 208a584c..27ff871e 100644 --- a/docs/man/nng_url_free.3.adoc +++ b/docs/man/nng_url_free.3.adoc @@ -1,6 +1,6 @@ = nng_url_free(3) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -40,4 +40,5 @@ None. [.text-left] xref:nng_url_clone.3.adoc[nng_url_clone(3)], xref:nng_url_parse.3.adoc[nng_url_parse(3)], +xref:nng_url.5.adoc[nng_url(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_url_parse.3.adoc b/docs/man/nng_url_parse.3.adoc index 10ca695f..15d8137d 100644 --- a/docs/man/nng_url_parse.3.adoc +++ b/docs/man/nng_url_parse.3.adoc @@ -1,6 +1,6 @@ = nng_url_parse(3) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -26,26 +26,12 @@ int nng_url_parse(nng_url **urlp, const char *str); The `nng_url_parse()` function parses the string _str_ containing an https://tools.ietf.org/html/rfc3986[RFC 3986] compliant URL, and creates -a structure containing the results. A pointer to the resulting structure -is stored in _urlp_. +an +xref:nng_url.5.adoc[`nng_url`] structure containing the results. +A pointer to the resulting structure is stored in _urlp_. -The `nng_url` structure has at least the following members: - -[source, c] ----- -struct nng_url { - char *u_rawurl; // Unparsed URL, with minimal canonicalization. - char *u_scheme; // Scheme, such as "http"; always lower case. - char *u_userinfo; // Userinfo component, or NULL. - char *u_host; // Full host, including port if present. - char *u_hostname; // Hostname only (or address), or empty string. - char *u_port; // Port number, may be default or empty string. - char *u_path; // Path if present, empty string otherwise. - char *u_query; // Query info if present, NULL otherwise. - char *u_fragment; // Fragment if present, NULL otherwise. - char *u_requri; // Request-URI (path[?query][#fragment]) -}; ----- +The structure may disposed of when no longer needed by calling +xref:nng_url_free.3.adoc[`nng_url_free()`]. === URL Canonicalization @@ -93,4 +79,5 @@ This function returns 0 on success, and non-zero otherwise. xref:nng_url_clone.3.adoc[nng_url_clone(3)], xref:nng_url_free.3.adoc[nng_url_free(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_url.5.adoc[nng_url(5)], xref:nng.7.adoc[nng(7)] |