Add new functions for socket identity.

These functions were added in the main branch for NNG 2.0, and
we add them here to facilitate converting any code that happened
to use the options (`NNG_OPT_PROTO`, `NNG_OPT_PROTONAME`,
`NNG_OPT_PEER`, `NNG_OPT_PEERNAME`, and `NNG_OPT_RAW`.

Its unlikely that many applications need this, but providing these
as a transition aid may help applications start adopting new APIs now.

11 files changed, 266 insertions, 15 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index 6db3318f..f9d03a19 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -165,6 +165,9 @@ if (NNG_ENABLE_DOC)
             nng_sleep_aio
             nng_socket_id
             nng_socket_get
+            nng_socket_proto_id
+            nng_socket_proto_name
+            nng_socket_raw
             nng_socket_set
             nng_stats_free
             nng_stats_get
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 8d006ba8..f1e14ac4 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -53,6 +53,9 @@ The following functions operate on sockets.
 |xref:nng_setopt.3.adoc[nng_setopt()]|set socket option
 |xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option
 |xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier
+|xref:nng_socket_raw.3.adoc[nng_socket_raw()]|is the socket raw
+|xref:nng_socket_proto_id.3.adoc[nng_socket_raw()]|get the socket protocol identifier
+|xref:nng_socket_proto_name.3.adoc[nng_socket_raw()]|get the socket protocol name
 |xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option
 |===
 
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index 94da37a0..7bf2a03b 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -113,6 +113,8 @@ automatically copy message headers from a received message to the corresponding
 reply, whereas in raw mode this is not done.)
 See xref:nng.7.adoc#raw_mode[Raw Mode] for more details.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_raw.3.adoc[`nng_socket_raw`] function instead.
+
 [[NNG_OPT_RECONNMINT]]
 ((`NNG_OPT_RECONNMINT`))::
 (((reconnect time, minimum)))
@@ -326,12 +328,16 @@ application.
 (`int`)
 This read-only option is used to obtain the 16-bit number for the socket's protocol.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_id.3.adoc[`nng_socket_proto_id`] function instead.
+
 [[NNG_OPT_PEER]]
 ((`NNG_OPT_PEER`))::
 (`int`)
 This read-only option is used to obtain the 16-bit number of the
 peer protocol for the socket.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_id.3.adoc[`nng_socket_peer_id`] function instead.
+
 [[NNG_OPT_PEER_GID]]
 ((`NNG_OPT_PEER_GID`))::
 (`uint64_t`)
@@ -370,11 +376,15 @@ Zones (and this option) are only supported on Solaris and illumos systems, on se
 (string)
 This read-only option is used to obtain the name of the peer protocol for the socket.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_name.3.adoc[`nng_socket_peer_name`] function instead.
+
 [[NNG_OPT_PROTONAME]]
 ((`NNG_OPT_PROTONAME`))::
 (string)
 This read-only option is used to obtain the name of the socket's protocol.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_name.3.adoc[`nng_socket_proto_name`] function instead.
+
 == SEE ALSO
 
 [.text-left]
diff --git a/docs/man/nng_socket_proto_id.3.adoc b/docs/man/nng_socket_proto_id.3.adoc
new file mode 100644
index 00000000..95d9dbee
--- /dev/null
+++ b/docs/man/nng_socket_proto_id.3.adoc
@@ -0,0 +1,46 @@
+= nng_socket_proto_id(3)
+//
+// Copyright 2024 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_socket_proto_id - obtain the socket protocol id
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_proto_id(nng_socket s, uint16_t *id);
+int nng_socket_peer_id(nng_socket s, uint16_t *id);
+----
+
+== DESCRIPTION
+
+These functions store the 16-bit protocol identifier of either the socket _s_,
+or its natural peer, in _id_.
+
+TIP: These functions should be used in place of the `NNG_OPT_PROTO` and `NNG_OPT_PEER`
+options in new code.
+
+== RETURN VALUES
+
+These functions return zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_socket_proto_name.3.adoc b/docs/man/nng_socket_proto_name.3.adoc
new file mode 100644
index 00000000..da2f565f
--- /dev/null
+++ b/docs/man/nng_socket_proto_name.3.adoc
@@ -0,0 +1,49 @@
+= nng_socket_proto_name(3)
+//
+// Copyright 2024 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_socket_proto_name - obtain the socket protocol name
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_proto_name(nng_socket s, const char **name);
+int nng_socket_peer_name(nng_socket s, const char **name);
+----
+
+== DESCRIPTION
+
+These functions store the protocol name of either the socket _s_,
+or its natural peer, in _name.
+
+NOTE: The string value obtained by these functions is statically stored
+as part of the program text, and must not be freed or modified.
+
+TIP: These functions should be used in place of the `NNG_OPT_PROTONAME` and `NNG_OPT_PEERNAME`
+options in new code.
+
+== RETURN VALUES
+
+These functions return zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_socket_raw.3.adoc b/docs/man/nng_socket_raw.3.adoc
new file mode 100644
index 00000000..594843b9
--- /dev/null
+++ b/docs/man/nng_socket_raw.3.adoc
@@ -0,0 +1,44 @@
+= nng_socket_raw(3)
+//
+// Copyright 2024 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_socket_raw - return whether socket is cooked or raw
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_raw(nng_socket s, bool *raw);
+----
+
+== DESCRIPTION
+
+The `nng_socket_raw()` function stores `true` in _raw_ if the socket is in raw mode,
+otherwise it stores `false`.
+
+TIP: This function should be used in place of the `NNG_OPT_RAW` option in new code.
+
+== RETURN VALUES
+
+This function returns zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/include/nng/nng.h b/include/nng/nng.h
index f8fb2cac..6ae2af54 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -250,6 +250,14 @@ NNG_DECL int nng_socket_get_ptr(nng_socket, const char *, void **);
 NNG_DECL int nng_socket_get_ms(nng_socket, const char *, nng_duration *);
 NNG_DECL int nng_socket_get_addr(nng_socket, const char *, nng_sockaddr *);
 
+// These functions are used on a socket to get information about it's
+// identity, and the identity of the peer.  Few applications need these.
+NNG_DECL int nng_socket_proto_id(nng_socket id, uint16_t *);
+NNG_DECL int nng_socket_peer_id(nng_socket id, uint16_t *);
+NNG_DECL int nng_socket_proto_name(nng_socket id, const char **);
+NNG_DECL int nng_socket_peer_name(nng_socket id, const char **);
+NNG_DECL int nng_socket_raw(nng_socket, bool *);
+
 // Utility function for getting a printable form of the socket address
 // for display in logs, etc.  It is not intended to be parsed, and the
 // display format may change without notice.  Generally you should alow
@@ -1439,10 +1447,12 @@ NNG_DECL int nng_pipe_getopt_string(
 NNG_DECL void nng_closeall(void) NNG_DEPRECATED;
 
 // THese functions are deprecated, but they really serve no useful purpose.
-NNG_DECL int  nng_stream_set_addr(
-     nng_stream *, const char *, const nng_sockaddr *) NNG_DEPRECATED;
-NNG_DECL int nng_ctx_get_addr(nng_ctx, const char *, nng_sockaddr *) NNG_DEPRECATED;
-NNG_DECL int nng_ctx_set_addr(nng_ctx, const char *, const nng_sockaddr *) NNG_DEPRECATED;
+NNG_DECL int nng_stream_set_addr(
+    nng_stream *, const char *, const nng_sockaddr *) NNG_DEPRECATED;
+NNG_DECL int nng_ctx_get_addr(
+    nng_ctx, const char *, nng_sockaddr *) NNG_DEPRECATED;
+NNG_DECL int nng_ctx_set_addr(
+    nng_ctx, const char *, const nng_sockaddr *) NNG_DEPRECATED;
 
 #endif // NNG_ELIDE_DEPRECATED
 
diff --git a/src/core/socket.c b/src/core/socket.c
index c4e16f70..bf550a24 100644
--- a/src/core/socket.c
+++ b/src/core/socket.c
@@ -877,6 +877,12 @@ nni_sock_peer_name(nni_sock *sock)
 	return (sock->s_peer_id.p_name);
 }
 
+bool
+nni_sock_raw(nni_sock *sock)
+{
+	return ((nni_sock_flags(sock) & NNI_PROTO_FLAG_RAW) != 0);
+}
+
 struct nni_proto_pipe_ops *
 nni_sock_proto_pipe_ops(nni_sock *sock)
 {
diff --git a/src/core/socket.h b/src/core/socket.h
index c4037e96..343310ca 100644
--- a/src/core/socket.h
+++ b/src/core/socket.h
@@ -22,6 +22,7 @@ extern uint16_t    nni_sock_proto_id(nni_sock *);
 extern uint16_t    nni_sock_peer_id(nni_sock *);
 extern const char *nni_sock_proto_name(nni_sock *);
 extern const char *nni_sock_peer_name(nni_sock *);
+extern bool        nni_sock_raw(nni_sock *);
 extern void       *nni_sock_proto_data(nni_sock *);
 extern void        nni_sock_add_stat(nni_sock *, nni_stat_item *);
 
diff --git a/src/nng.c b/src/nng.c
index b5e7430b..60ec10eb 100644
--- a/src/nng.c
+++ b/src/nng.c
@@ -1146,6 +1146,85 @@ nng_socket_get_addr(nng_socket id, const char *n, nng_sockaddr *v)
 }
 
 int
+nng_socket_proto_id(nng_socket id, uint16_t *idp)
+{
+	int       rv;
+	nni_sock *sock;
+
+	if (((rv = nni_init()) != 0) ||
+	    ((rv = nni_sock_find(&sock, id.id)) != 0)) {
+		return (rv);
+	}
+
+	*idp = nni_sock_proto_id(sock);
+	nni_sock_rele(sock);
+	return (0);
+}
+
+int
+nng_socket_peer_id(nng_socket id, uint16_t *idp)
+{
+	int       rv;
+	nni_sock *sock;
+
+	if (((rv = nni_init()) != 0) ||
+	    ((rv = nni_sock_find(&sock, id.id)) != 0)) {
+		return (rv);
+	}
+
+	*idp = nni_sock_peer_id(sock);
+	nni_sock_rele(sock);
+	return (0);
+}
+
+int
+nng_socket_proto_name(nng_socket id, const char **name)
+{
+	int       rv;
+	nni_sock *sock;
+
+	if (((rv = nni_init()) != 0) ||
+	    ((rv = nni_sock_find(&sock, id.id)) != 0)) {
+		return (rv);
+	}
+
+	*name = nni_sock_proto_name(sock);
+	nni_sock_rele(sock);
+	return (0);
+}
+
+int
+nng_socket_peer_name(nng_socket id, const char **name)
+{
+	int       rv;
+	nni_sock *sock;
+
+	if (((rv = nni_init()) != 0) ||
+	    ((rv = nni_sock_find(&sock, id.id)) != 0)) {
+		return (rv);
+	}
+
+	*name = nni_sock_peer_name(sock);
+	nni_sock_rele(sock);
+	return (0);
+}
+
+int
+nng_socket_raw(nng_socket id, bool *rawp)
+{
+	int       rv;
+	nni_sock *sock;
+
+	if (((rv = nni_init()) != 0) ||
+	    ((rv = nni_sock_find(&sock, id.id)) != 0)) {
+		return (rv);
+	}
+	*rawp = nni_sock_raw(sock);
+	nni_sock_rele(sock);
+	return (0);
+}
+
+int
 nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg)
 {
 	int       rv;
diff --git a/src/sp/protocol/bus0/bus_test.c b/src/sp/protocol/bus0/bus_test.c
index 6a214972..f9c1c092 100644
--- a/src/sp/protocol/bus0/bus_test.c
+++ b/src/sp/protocol/bus0/bus_test.c
@@ -1,5 +1,5 @@
 //
-// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
 //
 // This software is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -16,21 +16,19 @@
 void
 test_bus_identity(void)
 {
-	nng_socket s;
-	int        p;
-	char      *n;
+	nng_socket  s;
+	uint16_t    p;
+	const char *n;
 
 	NUTS_PASS(nng_bus0_open(&s));
-	NUTS_PASS(nng_socket_get_int(s, NNG_OPT_PROTO, &p));
+	NUTS_PASS(nng_socket_proto_id(s, &p));
 	NUTS_TRUE(p == NNG_BUS0_SELF);
-	NUTS_PASS(nng_socket_get_int(s, NNG_OPT_PEER, &p));
+	NUTS_PASS(nng_socket_peer_id(s, &p));
 	NUTS_TRUE(p == NNG_BUS0_PEER); // 49
-	NUTS_PASS(nng_socket_get_string(s, NNG_OPT_PROTONAME, &n));
+	NUTS_PASS(nng_socket_proto_name(s, &n));
 	NUTS_MATCH(n, NNG_BUS0_SELF_NAME);
-	nng_strfree(n);
-	NUTS_PASS(nng_socket_get_string(s, NNG_OPT_PEERNAME, &n));
+	NUTS_PASS(nng_socket_peer_name(s, &n));
 	NUTS_MATCH(n, NNG_BUS0_PEER_NAME);
-	nng_strfree(n);
 	NUTS_CLOSE(s);
 }
 
@@ -70,7 +68,7 @@ test_bus_device(void)
 {
 	nng_socket s1, s2, s3;
 	nng_socket none = NNG_SOCKET_INITIALIZER;
-	nng_aio *aio;
+	nng_aio   *aio;
 
 	NUTS_PASS(nng_bus0_open_raw(&s1));
 	NUTS_PASS(nng_bus0_open(&s2));
@@ -372,6 +370,8 @@ test_bus_cooked(void)
 	bool       b;
 
 	NUTS_PASS(nng_bus0_open(&s));
+	NUTS_PASS(nng_socket_raw(s, &b));
+	NUTS_TRUE(!b);
 	NUTS_PASS(nng_socket_get_bool(s, NNG_OPT_RAW, &b));
 	NUTS_TRUE(!b);
 	NUTS_FAIL(nng_socket_set_bool(s, NNG_OPT_RAW, true), NNG_EREADONLY);