diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/api/url.md | 52 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 21 |
2 files changed, 52 insertions, 21 deletions
diff --git a/docs/ref/api/url.md b/docs/ref/api/url.md index db9f3be2..62cf66fd 100644 --- a/docs/ref/api/url.md +++ b/docs/ref/api/url.md @@ -20,28 +20,52 @@ typedef struct nng_url { char *u_query; char *u_fragment; } nng_url; + +const char *nng_url_scheme(const nng_url *url); +const char *nng_url_userinfo(const nng_url *url); +const char *nng_url_hostname(const nng_url *url); +uint16_t nng_url_port(const nng_url *url); +const char *nng_url_path(const nng_url *url); +const char *nng_url_query(const nng_url *url); +const char *nng_url_fragment(const nng_url *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 {{i:`nng_url_scheme`}} function returns the scheme, +without any colons or slashes. Values are lower case +strings, like "http" or "inproc" or "tls+tcp4". + +The {{i:`nng_url_userinfo`}} function returns a string corresponding +to the user component of a URL (the part before any `@` sign) if such +a component is present, otherwise it returns `NULL`. + +The {{i:`nng_url_hostname`}} function returns a hostname (which might +actually be an IP address) from the URL, if the URL corresponds to a scheme +that uses hostnames (like "http" or "tcp"). If the URL does not (for example +"inproc" or "ipc" URLs) then it returns `NULL`. -Additionally applications must not depend on the size of this structure. -Obtain one using `nng_parse_url`. +The {{i:`nng_url_port`}} function returns the TCP or UDP port number if the URL +corresponds to a protocol based on TCP or UDP. It returns zero otherwise. +Note that the port number might not have been explicitly specified in the URL. +For example, the port number associated with "http://www.example.com" is 80, +which is the standard port number for HTTP. + +> [!TIP] +> The port number returned by this is in the native machine byte order. +> Be careful when using this with other network-oriented APIs. -The fields of an `nng_url` object are as follows: +The {{i:`nng_url_path`}} function returns the path component of the URL. +This will always be non-`NULL`, but it may be empty. -- `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_hostname`: The name of the host, and may be the empty string in some cases. -- `u_port`: The port. May be zero 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. +The {{i:`nng_url_query`}} and {{i:`nng_url_fragment`}} functions return +the query-information (the part following a '?') and fragment +(the part following a '#') if those components are present, or `NULL` +if they are not. The returned string will not include the leading '?' or '#' +characters. -> [!NOTE] -> Other fields may also be present, but only those documented here are safe for application use. +Note that any strings returned by these functions are only valid until +_url_ is freed with [`nng_url_free`]. ## Format a URL diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index ddad9ff7..1d903215 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -166,14 +166,21 @@ The use of `*` to act as a wild card meaning all local interface addresses is removed. The empty string already performs this function, and unlike `*` is RFC compliant. -## URL Structure Members - -The details of [`nng_url`] have changed as follows: - -- `u_port` is no longer a string, but a `uint16_t` -- `u_scheme` is a `const char *` +## URL Structure Changes + +The details of [`nng_url`] have changed significantly, and direct +access of the structure is no longer permitted. Intead new +accessors functions are provided: + +- `u_scheme` is replaced by [`nng_url_scheme`]. +- `u_port` is replaced by [`nng_url_port`], but this returns a `uint16_t`. +- `u_hostname` is replaced by [`nng_url_hostname`]. +- `u_path` is replaced by [`nng_url_path`]. +- `u_query` is replaced by [`nng_url_query`]. +- `u_fragment` is replaced by [`nng_url_fragment`]. +- `u_userinfo` is replaced by [`nng_url_userinfo`]. - `u_requri` is removed - it can be easily formulated from the other fields. -- `u_host` is removed - use `u_hostname` and `u_port` to construct if needed +- `u_host` is removed - use [`nng_url_hostname`] and [`nng_url_port`] to construct if needed - `u_rawurl` is removed - a "cooked" URL can be obtained from the new [`nng_url_sprintf`] function. {{#include ../xref.md}} |