fixes #143 Protocols and transports should be "configurable"

This makes all the protocols and transports optional.  All
of them except ZeroTier are enabled by default, but you can
now disable them (remove from the build) with cmake options.

The test suite is modified so that tests still run as much
as they can, but skip over things caused by missing functionality
from the library (due to configuration).

Further, the constant definitions and prototypes for functions
that are specific to transports or protocols are moved into
appropriate headers, which should be included directly by
applications wishing to use these.

We have also added and improved documentation -- all of the
transports are documented, and several more man pages for
protocols have been added.  (Req/Rep and Surveyor are still
missing.)

1 files changed, 155 insertions, 0 deletions

diff --git a/docs/nng_pair.adoc b/docs/nng_pair.adoc
new file mode 100644
index 00000000..b55000af
--- /dev/null
+++ b/docs/nng_pair.adoc
@@ -0,0 +1,155 @@
+nng_pair(7)
+===========
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
+            Copyright 2017 Capitar IT Group BV <info@capitar.com> \
+            This software 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_pair - pair protocol
+
+SYNOPSIS
+--------
+
+.Version 0
+[source,c]
+----------
+#include <nng/protocol/pair0/pair.h>
+
+int nng_pair0_open(nng_socket *s);
+----------
+
+.Version 1
+[source,c]
+----------
+#include <nng/protocol/pair1/pair.h>
+
+int nng_pair1_open(nng_socket *s);
+----------
+
+DESCRIPTION
+-----------
+
+The _nng_pair_ protocol implements a peer-to-peer pattern, where
+relationships between peers are one-to-one.
+
+Version 1 of this protocol supports an optional _polyamorous_ mode where a
+peer can maintain multiple partnerships.  Using this mode requires
+some additional sophistication in the application.
+
+Socket Operations
+~~~~~~~~~~~~~~~~~
+
+The `nng_pair_open()` call creates a _pair_ socket.  Normally, this
+pattern will block when attempting to send a message, if no peer is
+able to receive the message.
+
+NOTE: Even though this mode may appear to be "reliable", because back-pressure
+prevents discarding messages most of the time, there are topologies involving
+_devices_ (see <<nng_device.adoc#,nng_device(3)>>) or raw mode sockets where
+messages may be discarded.  Applications that require reliable delivery
+semantics should consider using <<nng_req.adoc#,nng_req(7)>> sockets, or
+implement their own acknowledgement layer on top of pair sockets.
+
+In order to avoid head-of-line blocking conditions, _polyamorous_ mode pair
+sockets (version 1 only) discard messages if they are unable to deliver them
+to a peer.
+
+Protocol Versions
+~~~~~~~~~~~~~~~~~
+
+Version 0 is the legacy version of this protocol.  It lacks any header
+information, and is suitable when building simple one-to-one topologies.
+
+TIP: Use version 0 if you need to communicate with other implementations,
+including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or
+https://github.com/go-mangos/mangos[mangos].
+
+Version 1 of the protocol offers improved protection against loops when
+used with <<nng_device.adoc#,nng_device(3)>>.   It also offers _polyamorous_
+mode for forming multiple partnerships on a single socket.
+
+NOTE: Version 1 of this protocol is considered experimental at this time.
+
+Polyamorous Mode
+~~~~~~~~~~~~~~~~
+
+Normally pair sockets are for one-to-one communication, and a given peer
+will reject new connections if it already has an active connection to another
+peer.
+
+In _polyamorous_ mode, which is only available with version 1, a socket can
+support many one-to-one connections.  In this mode, the application must
+choose the remote peer to receive an ougoing message by setting the value
+of the pipe ID on the outgoing message using
+the <<nng_msg_set_pipe.adoc#,nng_msg_set_pipe(3)>> function.
+
+Most often the value of the outgoing pipe ID will be obtained from an incoming
+message using the <<nng_msg_get_pipe.adoc#,nng_msg_get_pipe(3)>> function,
+such as when replying to an incoming message.
+
+In order to prevent head-of-line blocking, if the peer on the given pipe
+is not able to receive (or the pipe is no longer available, such as if the
+peer has disconnected), then the message will be discarded with no notification
+to the sender.
+
+Protocol Options
+~~~~~~~~~~~~~~~~
+
+The following protocol-specific options are available.
+
+`NNG_OPT_PAIR1_POLY`::
+
+   (Version 1 only).  This option enables the use of _polyamorous_ mode.
+   The value is read-write, and takes an integer boolean value.  The default
+   false value (0) indicates that legacy monogamous mode should be used.
+
+`NNG_OPT_MAXTTL`::
+
+   (Version 1 only).  Maximum time-to-live.  This option is an integer value
+   between 0 and 255,
+   inclusive, and is the maximum number of "hops" that a message may
+   pass through until it is discarded.  The default value is 8.  A value
+   of 0 may be used to disable the loop protection, allowing an infinite
+   number of hops.
++
+TIP: Each node along a forwarding path may have it's own value for the
+maximum time-to-live, and performs its own checks before forwarding a message.
+Therefore it is helpful if all nodes in the topology use the same value for
+this option.
+
+Protocol Headers
+~~~~~~~~~~~~~~~~
+
+Version 0 of the pair protocol has no protocol-specific headers.
+
+Version 1 of the pair protocol uses a single 32-bit unsigned value.  The
+low-order (big-endian) byte of this value contains a "hop" count, and is
+used in conjuction with the `NNG_OPT_MAXTTL` option to guard against
+device forwarding loops.  This value is initialized to 1, and incremented
+each time the message is received by a new node.
+    
+AUTHORS
+-------
+link:mailto:garrett@damore.org[Garrett D'Amore]
+
+SEE ALSO
+--------
+<<nng.adoc#,nng(7)>>
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] +
+Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].