api: introduce NNG 2.0 compatible nng_dialer_get_url and nng_listener_get_url

This is meant to help applications start adopting new interfaces before converting to NNG 2.0

8 files changed, 62 insertions, 3 deletions

diff --git a/docs/man/nng_dialer_get.3.adoc b/docs/man/nng_dialer_get.3.adoc
index 5084c1b3..6750a535 100644
--- a/docs/man/nng_dialer_get.3.adoc
+++ b/docs/man/nng_dialer_get.3.adoc
@@ -37,6 +37,8 @@ int nng_dialer_get_string(nng_dialer d, const char *opt, char **strp);
 
 int nng_dialer_get_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
 
+int nng_dialer_get_url(nng_dialer d, const nng_url **url);
+
 ----
 
 == DESCRIPTION
@@ -117,6 +119,9 @@ referenced by _u64p_.
 This is typically used for options related to identifiers, network
 numbers, and similar.
 
+`nng_dialer_get_url()`::
+This function is used to obtain the URL that dialer is configured for.
+
 == RETURN VALUES
 
 These functions returns 0 on success, and non-zero otherwise.
diff --git a/docs/man/nng_listener_get.3.adoc b/docs/man/nng_listener_get.3.adoc
index 83ae6986..3be8cfd9 100644
--- a/docs/man/nng_listener_get.3.adoc
+++ b/docs/man/nng_listener_get.3.adoc
@@ -1,6 +1,6 @@
 = nng_listener_get(3)
 //
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 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
@@ -37,6 +37,8 @@ int nng_listener_get_string(nng_listener l, const char *opt, char **strp);
 
 int nng_listener_get_uint64(nng_listener l, const char *opt, uint64_t *u64p);
 
+int nng_listener_get_url(nng_listener l, const nng_url **url);
+
 ----
 
 == DESCRIPTION
@@ -115,6 +117,13 @@ referenced by _u64p_.
 This is typically used for options related to identifiers, network
 numbers, and similar.
 
+`nng_listener_get_url()`::
+This function is used to obtain the URL that listener is configured for.
+This is the actual URL, and may different that what was requested.
+For example, when using TCP, if port 0 was requested, but then the listener
+was started, a real port will have been chosen by the operating system.
+This URL will reflect that final port, so it can be used for dialing.
+
 == RETURN VALUES
 
 These functions return 0 on success, and non-zero otherwise.
diff --git a/include/nng/nng.h b/include/nng/nng.h
index 8a2eda36..e5e6cf7d 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -1706,6 +1706,10 @@ NNG_DECL void nng_cv_wake(nng_cv *);
 // that no waiter starves forever.
 NNG_DECL void nng_cv_wake1(nng_cv *);
 
+// New URL accessors for endpoints - from NNG 2.0.
+NNG_DECL int nng_dialer_get_url(nng_dialer, const nng_url **);
+NNG_DECL int nng_listener_get_url(nng_listener, const nng_url **);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/core/dialer.c b/src/core/dialer.c
index 722a0868..8679e4a3 100644
--- a/src/core/dialer.c
+++ b/src/core/dialer.c
@@ -558,6 +558,12 @@ nni_dialer_getopt(
 	return (nni_sock_getopt(d->d_sock, name, valp, szp, t));
 }
 
+const nng_url *
+nni_dialer_url(nni_dialer *d)
+{
+	return (d->d_url);
+}
+
 void
 nni_dialer_add_stat(nni_dialer *d, nni_stat_item *item)
 {
diff --git a/src/core/dialer.h b/src/core/dialer.h
index 7bc1547d..619a2101 100644
--- a/src/core/dialer.h
+++ b/src/core/dialer.h
@@ -1,5 +1,5 @@
 //
-// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2018 Devolutions <info@devolutions.net>
 //
@@ -25,6 +25,7 @@ extern int nni_dialer_setopt(
     nni_dialer *, const char *, const void *, size_t, nni_type);
 extern int nni_dialer_getopt(
     nni_dialer *, const char *, void *, size_t *, nni_type);
+extern const nng_url *nni_dialer_url(nni_dialer *);
 extern void nni_dialer_add_stat(nni_dialer *, nni_stat_item *);
 extern void nni_dialer_bump_error(nni_dialer *, int);
 
diff --git a/src/core/listener.c b/src/core/listener.c
index 65fe5a9f..e0b1b5a2 100644
--- a/src/core/listener.c
+++ b/src/core/listener.c
@@ -507,6 +507,12 @@ nni_listener_getopt(
 	return (nni_sock_getopt(l->l_sock, name, val, szp, t));
 }
 
+const nng_url *
+nni_listener_url(nni_listener *l)
+{
+	return (l->l_url);
+}
+
 void
 nni_listener_add_stat(nni_listener *l, nni_stat_item *item)
 {
diff --git a/src/core/listener.h b/src/core/listener.h
index c6c0b5d3..0451f203 100644
--- a/src/core/listener.h
+++ b/src/core/listener.h
@@ -1,5 +1,5 @@
 //
-// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2018 Devolutions <info@devolutions.net>
 //
@@ -25,6 +25,7 @@ extern int nni_listener_setopt(
     nni_listener *, const char *, const void *, size_t, nni_type);
 extern int nni_listener_getopt(
     nni_listener *, const char *, void *, size_t *, nni_type);
+extern const nng_url *nni_listener_url(nni_listener *);
 extern void nni_listener_add_stat(nni_listener *, nni_stat_item *);
 extern void nni_listener_bump_error(nni_listener *, int);
 
diff --git a/src/nng.c b/src/nng.c
index 529cd800..69f2f747 100644
--- a/src/nng.c
+++ b/src/nng.c
@@ -2314,3 +2314,30 @@ nng_udp_multicast_membership(nng_udp *udp, nng_sockaddr *sa, bool join)
 	return (
 	    nni_plat_udp_multicast_membership((nni_plat_udp *) udp, sa, join));
 }
+
+
+int
+nng_dialer_get_url(nng_dialer id, const nng_url **urlp)
+{
+       int         rv;
+       nni_dialer *d;
+       if ((rv = nni_dialer_find(&d, id.id)) != 0) {
+               return (rv);
+       }
+       *urlp = nni_dialer_url(d);
+       nni_dialer_rele(d);
+       return (0);
+}
+
+int
+nng_listener_get_url(nng_listener id, const nng_url **urlp)
+{
+       int           rv;
+       nni_listener *l;
+       if ((rv = nni_listener_find(&l, id.id)) != 0) {
+               return (rv);
+       }
+       *urlp = nni_listener_url(l);
+       nni_listener_rele(l);
+       return (0);
+}