fixes #375 integer types are error prone

This change converts the various integer types like nng_socket
in the public API to opaque structures that are passed by value.
Basically we just wrap the integer ID.  This "hack" give us strong
type checks by the compiler (yay!), at the expense of not being able
to directly use these as numbers (so comparisions for example don't
work, and neither does initialization to zero using the normal
method.

Comparison of disassembly output shows that at least with the optimizer
enabled there is no difference in the compiler output between using
a structure or an integral value.

5 files changed, 35 insertions, 14 deletions

diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
index 4fcac571..98402738 100644
--- a/docs/man/nng_ctx.5.adoc
+++ b/docs/man/nng_ctx.5.adoc
@@ -19,7 +19,7 @@ nng_ctx - protocol context
 ----
 #include <nng/nng.h>
 
-typedef uint32_t nng_ctx
+typedef struct nng_ctx_s nng_ctx
 ----
 
 == DESCRIPTION
@@ -38,6 +38,11 @@ of any sent request, a timer to retry the request on failure, and so forth.
 A separate context on the same socket can have similar data, but corresponding
 to a completely different request.
 
+IMPORTANT: The `nng_ctx` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
+
 All contexts share the same socket, and so some options, as well as the
 underlying transport details, will be common to all contexts on that socket.
 
diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc
index daadbd0b..45c60bc9 100644
--- a/docs/man/nng_dialer.5.adoc
+++ b/docs/man/nng_dialer.5.adoc
@@ -16,11 +16,11 @@ nng_dialer - dialer
 == SYNOPSIS
 
 [source, c]
------------
+----
 #include <nng/nng.h>
 
-typedef uint32_t nng_dialer;
------------
+typedef struct nng_dialer_s nng_dialer;
+----
 
 == DESCRIPTION
 
@@ -38,6 +38,11 @@ Dialer objects are created by the
 or <<nng_dial.3#,`nng_dial()`>> functions, and are always "`owned`"
 by a single <<nng_socket.5#,`nng_socket`>>.
 
+IMPORTANT: The `nng_dialer` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
+
 TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple dialer
 objects, multiple <<nng_listener.5#,listener>> objects, or even some
 of both.
diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc
index 6c5d0bd0..558eb920 100644
--- a/docs/man/nng_listener.5.adoc
+++ b/docs/man/nng_listener.5.adoc
@@ -16,11 +16,11 @@ nng_listener - listener
 == SYNOPSIS
 
 [source, c]
------------
+----
 #include <nng/nng.h>
 
-typedef uint32_t nng_listener;
------------
+typedef struct nng_listener_s nng_listener;
+----
 
 == DESCRIPTION
 
@@ -35,6 +35,11 @@ Listener objects are created by the
 or <<nng_listen.3#,`nng_listen()`>> functions, and are always "`owned`"
 by a single <<nng_socket.5#,`nng_socket`>>.
 
+IMPORTANT: The `nng_listener` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
+
 TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple listener
 objects, multiple <<nng_dialer.5#,dialer>> objects, or even some
 of both.
diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc
index 4befd3e8..39247fbd 100644
--- a/docs/man/nng_pipe.5.adoc
+++ b/docs/man/nng_pipe.5.adoc
@@ -16,11 +16,11 @@ nng_pipe - communications pipe
 == SYNOPSIS
 
 [source, c]
------------
+----
 #include <nng/nng.h>
 
-typedef uint32_t nng_pipe;
------------
+typedef struct nng_pipe_s nng_pipe;
+----
 
 == DESCRIPTION
 
@@ -32,6 +32,11 @@ single TCP or IPC connection.)
 Pipes are associated with either the listener or dialer that created them,
 and therefore are also automatically associated with a single socket.
 
+IMPORTANT: The `nng_pipe` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
+
 TIP: Most applications should never concern themselves with individual pipes. 
 However it is possible to access a pipe when more information about the
 source of a message is needed, or when more control is required over
diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc
index 0dcdfa99..4711495f 100644
--- a/docs/man/nng_socket.5.adoc
+++ b/docs/man/nng_socket.5.adoc
@@ -19,7 +19,7 @@ nng_socket - socket handle
 ----
 #include <nng/nng.h>
 
-typedef uint32_t nng_socket;
+typedef struct nng_socket_s nng_socket;
 ----
 
 == DESCRIPTION
@@ -34,9 +34,10 @@ may be connected to multiple transports at the same time.
 However, a given socket will have exactly one "`protocol`" associated with it,
 and is responsible for any state machines or other protocol-specific logic.
 
-NOTE: Although `nng_socket` is an integer data type, these objects are not
-ordinary file descriptors, and can only be used with the functions that
-explicitly indicate that it safe and appropropate to do so.
+IMPORTANT: The `nng_socket` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
 
 Each `nng_socket` is created by a protocol-specific constructor, such as
 <<nng_rep_open.3#,`nng_rep_open()`>>.