diff options
| -rw-r--r-- | docs/man/libnng.3.adoc | 16 | ||||
| -rw-r--r-- | docs/man/nng_url.5.adoc | 71 | ||||
| -rw-r--r-- | docs/man/nng_url_clone.3.adoc | 52 | ||||
| -rw-r--r-- | docs/man/nng_url_free.3.adoc | 44 | ||||
| -rw-r--r-- | docs/man/nng_url_parse.3.adoc | 83 | ||||
| -rw-r--r-- | docs/ref/SUMMARY.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/util/index.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/util/nng_url.md | 76 |
8 files changed, 86 insertions, 258 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 7187446b..a6541b52 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -253,16 +253,16 @@ to observe program behaviors and as an aid in troubleshooting. |xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics |=== -=== URL Object +// === URL Object -Common functionality is supplied for parsing and handling -universal resource locators (URLS). +// Common functionality is supplied for parsing and handling +// universal resource locators (URLS). -|=== -|xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure -|xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure -|xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string -|=== +// |=== +// |xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure +// |xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure +// |xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string +// |=== === Logging Support diff --git a/docs/man/nng_url.5.adoc b/docs/man/nng_url.5.adoc deleted file mode 100644 index 2e01b9de..00000000 --- a/docs/man/nng_url.5.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_url(5) -// -// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_url - Universal Resource Locator object - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -typedef struct nng_url { - 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; ----- - -== DESCRIPTION - -(((URL)))(((address, socket))) -An `nng_url` is a structure used for -representing URLs. -These structures are created by parsing string formatted URLs with -xref:nng_url_parse.3.adoc[`nng_url_parse()`]. - -Applications may access individual fields, but must not free or -alter them, as the underlying memory is managed by the library. - -The fields are as follows: - -[horizontal] -`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 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 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 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 - -[.text-left] -xref:nng_url_clone.3.adoc[nng_url_clone(3)], -xref:nng_url_free.3.adoc[nng_url_free(3)], -xref:nng_url_parse.3.adoc[nng_url_parse(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_url_clone.3.adoc b/docs/man/nng_url_clone.3.adoc deleted file mode 100644 index 0e6ef15f..00000000 --- a/docs/man/nng_url_clone.3.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_url_clone(3) -// -// 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 -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_url_clone - clone URL structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -int nng_url_clone(nng_url **dup, nng_url *orig); ----- - -== DESCRIPTION - -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. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. - -== SEE ALSO - -[.text-left] -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 deleted file mode 100644 index 27ff871e..00000000 --- a/docs/man/nng_url_free.3.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= nng_url_free(3) -// -// 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 -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_url_free - free a URL structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_url_free(nng_url *url); ----- - -== DESCRIPTION - -The `nng_url_free()` function deallocates the _url_ entirely, including -any of its members. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.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 deleted file mode 100644 index 15d8137d..00000000 --- a/docs/man/nng_url_parse.3.adoc +++ /dev/null @@ -1,83 +0,0 @@ -= nng_url_parse(3) -// -// 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 -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_url_parse - create URL structure from a string - -== SYNOPSIS - -[source, c] ----- -#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 -https://tools.ietf.org/html/rfc3986[RFC 3986] compliant URL, and creates -an -xref:nng_url.5.adoc[`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 -xref:nng_url_free.3.adoc[`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 - https://tools.ietf.org/html/rfc3986#section-2.3[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 - https://tools.ietf.org/html/rfc3986#section-6.2.2.3[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. - -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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. -`NNG_EINVAL`:: An invalid URL was supplied. - - -== SEE ALSO - -[.text-left] -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)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index d19bd8e0..d3272742 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -31,6 +31,7 @@ - [nng_socket_pair](./api/util/nng_socket_pair.md) - [nng_strdup](./api/util/nng_strdup.md) - [nng_strerror](./api/util/nng_strerror.md) + - [nng_url](./api/util/nng_url.md) - [nng_version](./api/util/nng_version.md) - [Transports](./tran/index.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 0a3cb891..a4dcbf12 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -15,4 +15,5 @@ of other uses. - [nng_socket_pair](nng_socket_pair.md) --- create a connected pair of BSD sockets - [nng_strdup](nng_strdup.md) --- duplicate string - [nng_strerror](nng_strerror.md) --- return an error description +- [nng_url](nng_url.md) --- Universal Resource Locator object - [nng_version](nng_version.md) --- report library version diff --git a/docs/ref/api/util/nng_url.md b/docs/ref/api/util/nng_url.md new file mode 100644 index 00000000..4da2ab97 --- /dev/null +++ b/docs/ref/api/util/nng_url.md @@ -0,0 +1,76 @@ +# nng_url + +## NAME + +nng_url --- Universal Resource Locator object + +## SYNOPSIS + +```c +#include <nng/nng.h> + +typedef struct nng_url { + 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; + +int nng_url_parse(nng_url **urlp, const char *str); +int nng_url_clone(nng_url **dup, nng_url *url); +void nng_url_free(nng_url *url); +``` + +## DESCRIPTION + +An {{i:`nng_url`}}{{hi:URL}}{{hi:Universal Resource Locator}} is a structure used for representing URLs. +These structures are created by parsing string formatted URLs with {{i:`nng_url_parse`}}. + +An `nng_url` may be cloned using the {{i:`nng_url_clone`}} function. +The original _url_ is duplicated into the location specified by _dup_. + +When no longer needed, `nng_url` objects may be freed using {{i:`nng_url_free`}}. + +> [!IMPORTANT] +> Only `nng_url_free` should be used to deallocate `nng_url` objects. + +### URL Fields + +Applications may access individual fields, but must not free or +alter them, as the underlying memory is managed by the library. + +The fields of an `nng_url` object are as follows: + +- `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 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 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 Request-URI. 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 +> [RFC 3986](https://tools.ietf.org/html/rfc3986). + +## RETURN VALUES + +The `nng_url_parse` and `nng_url_clone` functions return zero on success, or a non-zero +error value. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. +- `NNG_EINVAL`: The supplied string does not represent a valid URL. |