fixes #1071 tran_chkopt can be cleaned up

This is a sweeping cleanup of the transport logic around options,
and also harmonizes the names used when setting or getting options.
Additionally, legacy methods are now moved into a separate file and
can be elided via CMake or a preprocessor define.

Fundamentally, the ability to set to transport options via the socket
is deprecated; there are numerous problems with this and my earlier
approaches to deal with this have been somewhat misguided.  Further
these approaches will not work with future protocol work that is
planned (were some options need to be negotiated with peers at the
time of connection establishment.)

Documentation has been updated to reflect this.  The test suites still
make rather broad use of the older APIs, and will be converted later.

1 files changed, 100 insertions, 126 deletions

diff --git a/include/nng/nng.h b/include/nng/nng.h
index 32861023..20454a17 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -215,34 +215,6 @@ NNG_DECL int nng_close(nng_socket);
 // if the socket is not valid.
 NNG_DECL int nng_socket_id(nng_socket);
 
-// nng_closeall closes all open sockets. Do not call this from
-// a library; it will affect all sockets.
-NNG_DECL void nng_closeall(void);
-
-// nng_setopt sets an option for a specific socket.
-NNG_DECL int nng_setopt(nng_socket, const char *, const void *, size_t);
-NNG_DECL int nng_setopt_bool(nng_socket, const char *, bool);
-NNG_DECL int nng_setopt_int(nng_socket, const char *, int);
-NNG_DECL int nng_setopt_ms(nng_socket, const char *, nng_duration);
-NNG_DECL int nng_setopt_size(nng_socket, const char *, size_t);
-NNG_DECL int nng_setopt_uint64(nng_socket, const char *, uint64_t);
-NNG_DECL int nng_setopt_string(nng_socket, const char *, const char *);
-NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *);
-
-// nng_socket_getopt obtains the option for a socket.
-NNG_DECL int nng_getopt(nng_socket, const char *, void *, size_t *);
-NNG_DECL int nng_getopt_bool(nng_socket, const char *, bool *);
-NNG_DECL int nng_getopt_int(nng_socket, const char *, int *);
-NNG_DECL int nng_getopt_ms(nng_socket, const char *, nng_duration *);
-NNG_DECL int nng_getopt_size(nng_socket, const char *, size_t *);
-NNG_DECL int nng_getopt_uint64(nng_socket, const char *, uint64_t *);
-NNG_DECL int nng_getopt_ptr(nng_socket, const char *, void **);
-
-// nng_getopt_string is special -- it allocates a string to hold the
-// resulting string, which should be freed with nng_strfree when it is
-// no logner needed.
-NNG_DECL int nng_getopt_string(nng_socket, const char *, char **);
-
 NNG_DECL int nng_socket_set(nng_socket, const char *, const void *, size_t);
 NNG_DECL int nng_socket_set_bool(nng_socket, const char *, bool);
 NNG_DECL int nng_socket_set_int(nng_socket, const char *, int);
@@ -331,35 +303,6 @@ NNG_DECL int nng_dialer_id(nng_dialer);
 // invalid.
 NNG_DECL int nng_listener_id(nng_listener);
 
-// nng_dialer_setopt sets an option for a specific dialer.  Note
-// dialer options may not be altered on a running dialer.
-NNG_DECL int nng_dialer_setopt(nng_dialer, const char *, const void *, size_t);
-NNG_DECL int nng_dialer_setopt_bool(nng_dialer, const char *, bool);
-NNG_DECL int nng_dialer_setopt_int(nng_dialer, const char *, int);
-NNG_DECL int nng_dialer_setopt_ms(nng_dialer, const char *, nng_duration);
-NNG_DECL int nng_dialer_setopt_size(nng_dialer, const char *, size_t);
-NNG_DECL int nng_dialer_setopt_uint64(nng_dialer, const char *, uint64_t);
-NNG_DECL int nng_dialer_setopt_ptr(nng_dialer, const char *, void *);
-NNG_DECL int nng_dialer_setopt_string(nng_dialer, const char *, const char *);
-
-// nng_dialer_getopt obtains the option for a dialer. This will
-// fail for options that a particular dialer is not interested in,
-// even if they were set on the socket.
-NNG_DECL int nng_dialer_getopt(nng_dialer, const char *, void *, size_t *);
-NNG_DECL int nng_dialer_getopt_bool(nng_dialer, const char *, bool *);
-NNG_DECL int nng_dialer_getopt_int(nng_dialer, const char *, int *);
-NNG_DECL int nng_dialer_getopt_ms(nng_dialer, const char *, nng_duration *);
-NNG_DECL int nng_dialer_getopt_size(nng_dialer, const char *, size_t *);
-NNG_DECL int nng_dialer_getopt_sockaddr(
-    nng_dialer, const char *, nng_sockaddr *);
-NNG_DECL int nng_dialer_getopt_uint64(nng_dialer, const char *, uint64_t *);
-NNG_DECL int nng_dialer_getopt_ptr(nng_dialer, const char *, void **);
-
-// nng_dialer_getopt_string is special -- it allocates a string to hold the
-// resulting string, which should be freed with nng_strfree when it is
-// no logner needed.
-NNG_DECL int nng_dialer_getopt_string(nng_dialer, const char *, char **);
-
 NNG_DECL int nng_dialer_set(nng_dialer, const char *, const void *, size_t);
 NNG_DECL int nng_dialer_set_bool(nng_dialer, const char *, bool);
 NNG_DECL int nng_dialer_set_int(nng_dialer, const char *, int);
@@ -381,41 +324,6 @@ NNG_DECL int nng_dialer_get_ptr(nng_dialer, const char *, void **);
 NNG_DECL int nng_dialer_get_ms(nng_dialer, const char *, nng_duration *);
 NNG_DECL int nng_dialer_get_addr(nng_dialer, const char *, nng_sockaddr *);
 
-// nng_listener_setopt sets an option for a dialer.  This value is
-// not stored in the socket.  Subsequent setopts on the socket may
-// override these value however.  Note listener options may not be altered
-// on a running listener.
-NNG_DECL int nng_listener_setopt(
-    nng_listener, const char *, const void *, size_t);
-NNG_DECL int nng_listener_setopt_bool(nng_listener, const char *, bool);
-NNG_DECL int nng_listener_setopt_int(nng_listener, const char *, int);
-NNG_DECL int nng_listener_setopt_ms(nng_listener, const char *, nng_duration);
-NNG_DECL int nng_listener_setopt_size(nng_listener, const char *, size_t);
-NNG_DECL int nng_listener_setopt_uint64(nng_listener, const char *, uint64_t);
-NNG_DECL int nng_listener_setopt_ptr(nng_listener, const char *, void *);
-NNG_DECL int nng_listener_setopt_string(
-    nng_listener, const char *, const char *);
-
-// nng_listener_getopt obtains the option for a listener.  This will
-// fail for options that a particular listener is not interested in,
-// even if they were set on the socket.
-NNG_DECL int nng_listener_getopt(nng_listener, const char *, void *, size_t *);
-NNG_DECL int nng_listener_getopt_bool(nng_listener, const char *, bool *);
-NNG_DECL int nng_listener_getopt_int(nng_listener, const char *, int *);
-NNG_DECL int nng_listener_getopt_ms(
-    nng_listener, const char *, nng_duration *);
-NNG_DECL int nng_listener_getopt_size(nng_listener, const char *, size_t *);
-NNG_DECL int nng_listener_getopt_sockaddr(
-    nng_listener, const char *, nng_sockaddr *);
-NNG_DECL int nng_listener_getopt_uint64(
-    nng_listener, const char *, uint64_t *);
-NNG_DECL int nng_listener_getopt_ptr(nng_listener, const char *, void **);
-
-// nng_listener_getopt_string is special -- it allocates a string to hold the
-// resulting string, which should be freed with nng_strfree when it is
-// no logner needed.
-NNG_DECL int nng_listener_getopt_string(nng_listener, const char *, char **);
-
 NNG_DECL int nng_listener_set(
     nng_listener, const char *, const void *, size_t);
 NNG_DECL int nng_listener_set_bool(nng_listener, const char *, bool);
@@ -517,26 +425,6 @@ NNG_DECL void nng_ctx_recv(nng_ctx, nng_aio *);
 // uses a local context instead of the socket global context.
 NNG_DECL void nng_ctx_send(nng_ctx, nng_aio *);
 
-// nng_ctx_getopt is used to retrieve a context-specific option.  This
-// can only be used for those options that relate to specific context
-// tunables (which does include NNG_OPT_SENDTIMEO and NNG_OPT_RECVTIMEO);
-// see the protocol documentation for more details.
-NNG_DECL int nng_ctx_getopt(nng_ctx, const char *, void *, size_t *);
-NNG_DECL int nng_ctx_getopt_bool(nng_ctx, const char *, bool *);
-NNG_DECL int nng_ctx_getopt_int(nng_ctx, const char *, int *);
-NNG_DECL int nng_ctx_getopt_ms(nng_ctx, const char *, nng_duration *);
-NNG_DECL int nng_ctx_getopt_size(nng_ctx, const char *, size_t *);
-
-// nng_ctx_setopt is used to set a context-specific option.  This
-// can only be used for those options that relate to specific context
-// tunables (which does include NNG_OPT_SENDTIMEO and NNG_OPT_RECVTIMEO);
-// see the protocol documentation for more details.
-NNG_DECL int nng_ctx_setopt(nng_ctx, const char *, const void *, size_t);
-NNG_DECL int nng_ctx_setopt_bool(nng_ctx, const char *, bool);
-NNG_DECL int nng_ctx_setopt_int(nng_ctx, const char *, int);
-NNG_DECL int nng_ctx_setopt_ms(nng_ctx, const char *, nng_duration);
-NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t);
-
 NNG_DECL int nng_ctx_get(nng_ctx, const char *, void *, size_t *);
 NNG_DECL int nng_ctx_get_bool(nng_ctx, const char *, bool *);
 NNG_DECL int nng_ctx_get_int(nng_ctx, const char *, int *);
@@ -741,24 +629,10 @@ NNG_DECL void     nng_msg_header_clear(nng_msg *);
 NNG_DECL void     nng_msg_set_pipe(nng_msg *, nng_pipe);
 NNG_DECL nng_pipe nng_msg_get_pipe(const nng_msg *);
 
-// nng_msg_getopt is defunct, and should not be used by programs. It
-// always returns NNG_ENOTSUP.
-NNG_DECL int nng_msg_getopt(nng_msg *, int, void *, size_t *);
-
 // Pipe API. Generally pipes are only "observable" to applications, but
 // we do permit an application to close a pipe. This can be useful, for
 // example during a connection notification, to disconnect a pipe that
 // is associated with an invalid or untrusted remote peer.
-NNG_DECL int nng_pipe_getopt(nng_pipe, const char *, void *, size_t *);
-NNG_DECL int nng_pipe_getopt_bool(nng_pipe, const char *, bool *);
-NNG_DECL int nng_pipe_getopt_int(nng_pipe, const char *, int *);
-NNG_DECL int nng_pipe_getopt_ms(nng_pipe, const char *, nng_duration *);
-NNG_DECL int nng_pipe_getopt_size(nng_pipe, const char *, size_t *);
-NNG_DECL int nng_pipe_getopt_sockaddr(nng_pipe, const char *, nng_sockaddr *);
-NNG_DECL int nng_pipe_getopt_uint64(nng_pipe, const char *, uint64_t *);
-NNG_DECL int nng_pipe_getopt_ptr(nng_pipe, const char *, void **);
-NNG_DECL int nng_pipe_getopt_string(nng_pipe, const char *, char **);
-
 NNG_DECL int nng_pipe_get(nng_pipe, const char *, void *, size_t *);
 NNG_DECL int nng_pipe_get_bool(nng_pipe, const char *, bool *);
 NNG_DECL int nng_pipe_get_int(nng_pipe, const char *, int *);
@@ -1296,6 +1170,106 @@ NNG_DECL int nng_stream_listener_set_ptr(
 NNG_DECL int nng_stream_listener_set_addr(
     nng_stream_listener *, const char *, const nng_sockaddr *);
 
+
+#ifndef NNG_ELIDE_DEPRECATED
+// These are legacy APIs that have been deprecated.
+// Their use is strongly discouraged.
+
+// nng_msg_getopt is defunct, and should not be used by programs. It
+// always returns NNG_ENOTSUP.
+NNG_DECL int nng_msg_getopt(nng_msg *, int, void *, size_t *);
+
+// Socket options.  Use nng_socket_get and nng_socket_set isnetadl
+NNG_DECL int nng_getopt(nng_socket, const char *, void *, size_t *);
+NNG_DECL int nng_getopt_bool(nng_socket, const char *, bool *);
+NNG_DECL int nng_getopt_int(nng_socket, const char *, int *);
+NNG_DECL int nng_getopt_ms(nng_socket, const char *, nng_duration *);
+NNG_DECL int nng_getopt_size(nng_socket, const char *, size_t *);
+NNG_DECL int nng_getopt_uint64(nng_socket, const char *, uint64_t *);
+NNG_DECL int nng_getopt_ptr(nng_socket, const char *, void **);
+NNG_DECL int nng_getopt_string(nng_socket, const char *, char **);
+NNG_DECL int nng_setopt(nng_socket, const char *, const void *, size_t);
+NNG_DECL int nng_setopt_bool(nng_socket, const char *, bool);
+NNG_DECL int nng_setopt_int(nng_socket, const char *, int);
+NNG_DECL int nng_setopt_ms(nng_socket, const char *, nng_duration);
+NNG_DECL int nng_setopt_size(nng_socket, const char *, size_t);
+NNG_DECL int nng_setopt_uint64(nng_socket, const char *, uint64_t);
+NNG_DECL int nng_setopt_string(nng_socket, const char *, const char *);
+NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *);
+
+// Context options.  Use nng_ctx_get and nng_ctx_set instead.
+NNG_DECL int nng_ctx_getopt(nng_ctx, const char *, void *, size_t *);
+NNG_DECL int nng_ctx_getopt_bool(nng_ctx, const char *, bool *);
+NNG_DECL int nng_ctx_getopt_int(nng_ctx, const char *, int *);
+NNG_DECL int nng_ctx_getopt_ms(nng_ctx, const char *, nng_duration *);
+NNG_DECL int nng_ctx_getopt_size(nng_ctx, const char *, size_t *);
+NNG_DECL int nng_ctx_setopt(nng_ctx, const char *, const void *, size_t);
+NNG_DECL int nng_ctx_setopt_bool(nng_ctx, const char *, bool);
+NNG_DECL int nng_ctx_setopt_int(nng_ctx, const char *, int);
+NNG_DECL int nng_ctx_setopt_ms(nng_ctx, const char *, nng_duration);
+NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t);
+
+// Dialer options.  Use nng_dialer_get and nng_dialer_set instead.
+NNG_DECL int nng_dialer_getopt(nng_dialer, const char *, void *, size_t *);
+NNG_DECL int nng_dialer_getopt_bool(nng_dialer, const char *, bool *);
+NNG_DECL int nng_dialer_getopt_int(nng_dialer, const char *, int *);
+NNG_DECL int nng_dialer_getopt_ms(nng_dialer, const char *, nng_duration *);
+NNG_DECL int nng_dialer_getopt_size(nng_dialer, const char *, size_t *);
+NNG_DECL int nng_dialer_getopt_sockaddr(
+    nng_dialer, const char *, nng_sockaddr *);
+NNG_DECL int nng_dialer_getopt_uint64(nng_dialer, const char *, uint64_t *);
+NNG_DECL int nng_dialer_getopt_ptr(nng_dialer, const char *, void **);
+NNG_DECL int nng_dialer_getopt_string(nng_dialer, const char *, char **);
+NNG_DECL int nng_dialer_setopt(nng_dialer, const char *, const void *, size_t);
+NNG_DECL int nng_dialer_setopt_bool(nng_dialer, const char *, bool);
+NNG_DECL int nng_dialer_setopt_int(nng_dialer, const char *, int);
+NNG_DECL int nng_dialer_setopt_ms(nng_dialer, const char *, nng_duration);
+NNG_DECL int nng_dialer_setopt_size(nng_dialer, const char *, size_t);
+NNG_DECL int nng_dialer_setopt_uint64(nng_dialer, const char *, uint64_t);
+NNG_DECL int nng_dialer_setopt_ptr(nng_dialer, const char *, void *);
+NNG_DECL int nng_dialer_setopt_string(nng_dialer, const char *, const char *);
+
+// Listener options.  Use nng_listener_get and nng_listener_set instead.
+NNG_DECL int nng_listener_getopt(nng_listener, const char *, void *, size_t *);
+NNG_DECL int nng_listener_getopt_bool(nng_listener, const char *, bool *);
+NNG_DECL int nng_listener_getopt_int(nng_listener, const char *, int *);
+NNG_DECL int nng_listener_getopt_ms(
+    nng_listener, const char *, nng_duration *);
+NNG_DECL int nng_listener_getopt_size(nng_listener, const char *, size_t *);
+NNG_DECL int nng_listener_getopt_sockaddr(
+    nng_listener, const char *, nng_sockaddr *);
+NNG_DECL int nng_listener_getopt_uint64(
+    nng_listener, const char *, uint64_t *);
+NNG_DECL int nng_listener_getopt_ptr(nng_listener, const char *, void **);
+NNG_DECL int nng_listener_getopt_string(nng_listener, const char *, char **);
+NNG_DECL int nng_listener_setopt(
+    nng_listener, const char *, const void *, size_t);
+NNG_DECL int nng_listener_setopt_bool(nng_listener, const char *, bool);
+NNG_DECL int nng_listener_setopt_int(nng_listener, const char *, int);
+NNG_DECL int nng_listener_setopt_ms(nng_listener, const char *, nng_duration);
+NNG_DECL int nng_listener_setopt_size(nng_listener, const char *, size_t);
+NNG_DECL int nng_listener_setopt_uint64(nng_listener, const char *, uint64_t);
+NNG_DECL int nng_listener_setopt_ptr(nng_listener, const char *, void *);
+NNG_DECL int nng_listener_setopt_string(
+    nng_listener, const char *, const char *);
+
+// Pipe options.  Use nng_pipe_get instead.
+NNG_DECL int nng_pipe_getopt(nng_pipe, const char *, void *, size_t *);
+NNG_DECL int nng_pipe_getopt_bool(nng_pipe, const char *, bool *);
+NNG_DECL int nng_pipe_getopt_int(nng_pipe, const char *, int *);
+NNG_DECL int nng_pipe_getopt_ms(nng_pipe, const char *, nng_duration *);
+NNG_DECL int nng_pipe_getopt_size(nng_pipe, const char *, size_t *);
+NNG_DECL int nng_pipe_getopt_sockaddr(nng_pipe, const char *, nng_sockaddr *);
+NNG_DECL int nng_pipe_getopt_uint64(nng_pipe, const char *, uint64_t *);
+NNG_DECL int nng_pipe_getopt_ptr(nng_pipe, const char *, void **);
+NNG_DECL int nng_pipe_getopt_string(nng_pipe, const char *, char **);
+
+// nng_closeall closes all open sockets. Do not call this from
+// a library; it will affect all sockets.
+NNG_DECL void nng_closeall(void);
+
+#endif
+
 #ifdef __cplusplus
 }
 #endif