Introduce accessors for nng_url struct and make it opaque.

This provides safety by ensuring that applications do not
depend on the size or layout of nng_url itself.

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}}