From 2c9d65e0b170f474d241a20a68579f6d31dc8408 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 9 Mar 2018 18:42:28 -0800 Subject: Add nng_msg_get_pipe, nng_msg_set_pipe, and nng_pipe_getopt docs. --- docs/man/libnng.adoc | 3 ++ docs/man/nng_msg_get_pipe.adoc | 56 ++++++++++++++++++++ docs/man/nng_msg_set_pipe.adoc | 48 +++++++++++++++++ docs/man/nng_pipe_getopt.adoc | 117 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 224 insertions(+) create mode 100644 docs/man/nng_msg_get_pipe.adoc create mode 100644 docs/man/nng_msg_set_pipe.adoc create mode 100644 docs/man/nng_pipe_getopt.adoc (limited to 'docs/man') 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. |<>|get listener option |<>|set listener option |<>|start listener +|<>|get pipe option |=== === Message Handling Functions @@ -87,9 +88,11 @@ Most applications will only interact with the body. |<>|clear message body |<>|duplicate a message |<>|free a message +|<>|get pipe for message |<>|prepend to message body |<>|return the message body length |<>|reallocate a message +|<>|set pipe for message |<>|remove data from start of message body |<>|receive a message |<>|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. +// Copyright 2018 Capitar IT Group BV +// +// 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_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 <> 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 + +<>, +<>, +<>, +<> 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. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +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 <> 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 + +<>, +<>, +<>, +<> +<>, 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. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +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 <> 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 +<> or +<> + +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 + +<> +<>, +<> +<> +<>, +<> -- cgit v1.2.3-70-g09d2