Add nng_msg_get_pipe, nng_msg_set_pipe, and nng_pipe_getopt docs.

4 files changed, 224 insertions, 0 deletions

diff --git a/docs/man/libnng.adoc b/docs/man/libnng.adoc
index fdade0a4..8c18c8ff 100644
--- a/docs/man/libnng.adoc
+++ b/docs/man/libnng.adoc
@@ -67,6 +67,7 @@ Listeners accept incoming connection requets, and dialers make them.
 |<<nng_listener_getopt#,nng_listener_getopt(3)>>|get listener option
 |<<nng_listener_setopt#,nng_listener_setopt(3)>>|set listener option
 |<<nng_listener_start#,nng_listener_start(3)>>|start listener
+|<<nng_pipe_getopt#,nng_pipe_getopt(3)>>|get pipe option
 |===
 
 === Message Handling Functions
@@ -87,9 +88,11 @@ Most applications will only interact with the body.
 |<<nng_msg_clear#,nng_msg_clear(3)>>|clear message body
 |<<nng_msg_dup#,nng_msg_dup(3)>>|duplicate a message
 |<<nng_msg_free#,nng_msg_free(3)>>|free a message
+|<<nng_msg_get_pipe#,nng_msg_get_pipe(3)>>|get pipe for message
 |<<nng_msg_insert#,nng_msg_insert(3)>>|prepend to message body
 |<<nng_msg_len#,nng_msg_len(3)>>|return the message body length
 |<<nng_msg_realloc#,nng_msg_realloc(3)>>|reallocate a message
+|<<nng_msg_set_pipe#,nng_msg_set_pipe(3)>>|set pipe for message
 |<<nng_msg_trim#,nng_msg_trim(3)>>|remove data from start of message body
 |<<nng_recvmsg#,nng_recvmsg(3)>>|receive a message
 |<<nng_sendmsg#,nng_sendmsg(3)>>|send a message
diff --git a/docs/man/nng_msg_get_pipe.adoc b/docs/man/nng_msg_get_pipe.adoc
new file mode 100644
index 00000000..403b22a3
--- /dev/null
+++ b/docs/man/nng_msg_get_pipe.adoc
@@ -0,0 +1,56 @@
+= nng_msg_get_pipe(3)
+//
+// Copyright 2018 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
+// 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_msg_get_pipe - get pipe for message
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+nng_pipe nng_msg_get_pipe(nng_msg *msg);
+-----------
+
+== DESCRIPTION
+
+The `nng_msg_get_pipe()` returns the pipe associated with message _msg_.
+On receive, this is the pipe from which a message was received.
+On transmit, this would be the pipe that the message should be delivered
+to, if a specific peer is required.
+
+NOTE: Not all protocols support overriding the destination pipe.
+
+The most usual use case for this is to obtain information about the peer
+from which the message was received.  This can be used to provide different
+behaviors for different peers, such as a higher level of authentication
+for peers located on an untrusted network.
+The <<nng_pipe_getopt#,nng_pipe_getopt(3)>> function is useful in this situation.
+
+
+== RETURN VALUES
+
+This function returns the pipe associated with this message, which will
+be a positive value.  If the pipe is non-positive, then that indicates that
+no specific pipe is associated with the messsage.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_msg_alloc#,nng_msg_alloc(3)>>,
+<<nng_msg_set_pipe#,nng_msg_set_pipe(3)>>,
+<<nng_pipe_getopt#,nng_pipe_getopt(3)>>,
+<<nng#,nng(7)>>
diff --git a/docs/man/nng_msg_set_pipe.adoc b/docs/man/nng_msg_set_pipe.adoc
new file mode 100644
index 00000000..845ca5a2
--- /dev/null
+++ b/docs/man/nng_msg_set_pipe.adoc
@@ -0,0 +1,48 @@
+= nng_msg_get_pipe(3)
+//
+// Copyright 2018 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
+// 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_msg_set_pipe - set pipe for message
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_msg_set_pipe(nng_msg *msg, nng_pipe p);
+-----------
+
+== DESCRIPTION
+
+The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_.
+This is most often useful when used with protocols that support directing
+a message to a specific peer.  For example the <<nng_pair#,nng_pair(7)>> version
+1 protocol can do this when `NNG_OPT__POLYAMOROUS` mode is set.
+
+NOTE: Not all protocols support overriding the destination pipe.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_msg_alloc#,nng_msg_alloc(3)>>,
+<<nng_msg_get_pipe#,nng_msg_get_pipe(3)>>,
+<<nng_pipe_getopt#,nng_pipe_getopt(3)>>,
+<<nng#,nng(7)>>
+<<nng_getopt#,nng_getopt(3)>>,
diff --git a/docs/man/nng_pipe_getopt.adoc b/docs/man/nng_pipe_getopt.adoc
new file mode 100644
index 00000000..7642ef02
--- /dev/null
+++ b/docs/man/nng_pipe_getopt.adoc
@@ -0,0 +1,117 @@
+= nng_pipe_getopt(3)
+//
+// Copyright 2018 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
+// 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_pipe_getopt - get pipe option
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp);
+int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp);
+int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp);
+int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp);
+int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p);
+-----------
+
+== DESCRIPTION
+
+The `nng_pipe_getopt()` functions are used to retrieve option values for
+the pipe _p_. The actual options that may be retrieved in this way
+vary, and are documented in the <<nng_getopt#,nng_getopt(3)>> manual.
+Additionally some transport-specific options are documented with the
+transports themselves, and some protocol-specific options are documented
+with the protocol.
+
+NOTE: All "options" on a pipe are read-only values, and intended to
+facilitate understanding the identity of an associated peer; modification
+of options must be done on the listener or dialer using either
+<<nng_listener_setopt#,nng_listener_setopt(3)>> or
+<<nng_dialer_getopt#,nng_dialer_getopt(3)>>
+
+Any option that is set on an endpoint will be retrievable from pipes
+created by that endpoint.
+
+In all of these forms, the option _opt_ is retrieved from the pipe _p_.
+
+The details of the type, size, and semantics of the option will depend
+on the actual option, and will be documented with the option itself.
+
+The first form of this function, `nng_pipe_getopt()`, can be used to
+retrieve the value of any option.  It is untyped.  The caller must store
+a pointer to a buffer to receive the value in _val_, and the size of the
+buffer shall be stored at the location referenced by _valszp_.
+
+When the function returns, the actual size of the data copied (or that
+would have been copied if sufficient space were present) is stored at
+the location referened by _valszp_.  If the caller's buffer is not large
+enough to hold the entire object, then the copy is truncated.  Therefore
+the caller should validate that the returned size in _valszp_ does not
+exceed the original buffer size to check for truncation.
+
+It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero.
+This can be used to determine the size of the buffer needed to receive
+the object.
+
+Generally, it will be easier to use one of the typed forms instead.  Note
+however that no validation that the option is actually of the associated
+type is performed, so the caller must take care to use the *correct* typed
+form.
+
+The second form, `nng_pipe_getopt_int()`,
+is for options which take an integer (or boolean).  The value will
+be stored at _ivalp_.  For booleans the value will be eiher 0 (false) or 1 (true).
+
+The third form, `nng_pipe_getopt_ms()`, is used to retrieve time durations
+(such as timeouts), stored in _durp_ as a number of milliseconds.
+(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and
+the special value `NNG_DUR_DEFAULT` means a context-specific default.)
+
+The fourth form, `nng_pipe_getopt_size()`, is used to retrieve a size
+into the pointer _zp_, typically for buffer sizes, message maximum sizes, and
+similar options.
+
+The fifth form, `nng_pipe_getopt_uint64()`, is used to retrieve a
+64-bit unsigned value into the value referenced by _u64p_.
+This is typically used for options
+related to identifiers, network numbers, and similar.
+
+// XXX: nng_pipe_getopt_ptr is not support, and would carry some risks,
+// as the pipe may not survive, and the endpoint options may not survive,
+// leading to questions about pointer validity.
+// The last form, `nng_pipe_getopt_ptr()`, is used to retrieve a
+// pointer _ptr_ to structured data.  The data referenced by _ptr_ is
+// generally managed using other functions.
+// Note that this form is somewhat special in that the object is generally
+// not copied, but instead the *pointer* to the object is copied.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe.
+`NNG_ENOTSUP`:: The option _opt_ is not supported.
+`NNG_EWRITEONLY`:: The option _opt_ is write-only.
+
+== SEE ALSO
+
+<<nng_dialer_setopt#,nng_dialer_setopt(3)>>
+<<nng_getopt#,nng_getopt(3)>>,
+<<nng_listener_setopt#,nng_listener_setopt(3)>>
+<<nng_msg_get_pipe#,nng_msg_get_pipe(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>