From 97e113a7027afa9b9c11580d02772b5096c6c5a4 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 22 Oct 2024 20:15:39 -0700 Subject: docs: URL chapter --- docs/ref/SUMMARY.md | 3 +- docs/ref/api/url.md | 87 ++++++++++++++++++++++++++++++++++++++++++++ docs/ref/api/util/nng_url.md | 76 -------------------------------------- 3 files changed, 89 insertions(+), 77 deletions(-) create mode 100644 docs/ref/api/url.md delete mode 100644 docs/ref/api/util/nng_url.md (limited to 'docs') diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index f25b2361..c84de6c6 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -12,6 +12,8 @@ - [Time](./api/time.md) + - [URLs](./api/url.md) + - [Asynchronous Operations](./api/aio/index.md) - [nng_aio](./api/aio/nng_aio.md) @@ -33,7 +35,6 @@ - [nng_opts_parse](./api/util/nng_opts_parse.md) - [nng_strerror](./api/util/nng_strerror.md) - - [nng_url](./api/util/nng_url.md) - [Protocols](./proto/index.md) diff --git a/docs/ref/api/url.md b/docs/ref/api/url.md new file mode 100644 index 00000000..99460a08 --- /dev/null +++ b/docs/ref/api/url.md @@ -0,0 +1,87 @@ +# URLs + +{{i:Universal Resource Locator}}s, or {{i:URL}}s for short, are a standardized +way of representing a network resource, +defined in [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738), +and [RFC 3968](https://datatracker.ietf.org/doc/html/rfc3986). + +In Scalability Protocols, this concept is extended, although it includes schemes +that are not part of the IETF standards. + +## URL Structure + +```c +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; +``` + +### 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. + +## Parse a URL + +```c +int nng_url_parse(nng_url **urlp, const char *str); +``` + +The {{i:`nng_url_parse`}} function parses a URL string (in _str_), +and creates a dynamically allocated `nng_url`, returning it in _urlp_. + +> [!IMPORTANT] +> Only [`nng_url_free`] should be used to deallocate `nng_url` objects. + +## Clone a URL + +```c +int nng_url_clone(nng_url **dup, nng_url *url); +``` + +The {{i:`nng_url_clone`}} function creates a copy of _url_, and returns it in _dup_. + +## Destroy a URL + +```c +void nng_url_free(nng_url *url); +``` + +The {{i:`nng_url_free`}} function destroy an `nng_url` object created with +either [`nng_url_parse`] or [`nng_url_free`]. + +This is the only correct way to destroy an [`nng_url`] object. + +## See Also + +More information about Universal Resource Locators can be found in +[RFC 3986](https://tools.ietf.org/html/rfc3986). + +[`nng_url`]: #url-structure +[`nng_url_parse`]: #parse-a-url +[`nng_url_free`]: #destroy-a-url diff --git a/docs/ref/api/util/nng_url.md b/docs/ref/api/util/nng_url.md deleted file mode 100644 index 4da2ab97..00000000 --- a/docs/ref/api/util/nng_url.md +++ /dev/null @@ -1,76 +0,0 @@ -# nng_url - -## NAME - -nng_url --- Universal Resource Locator object - -## SYNOPSIS - -```c -#include - -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. -- cgit v1.2.3-70-g09d2