diff options
Diffstat (limited to 'docs/man/nng_stream_dialer_set.3str.adoc')
| -rw-r--r-- | docs/man/nng_stream_dialer_set.3str.adoc | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/docs/man/nng_stream_dialer_set.3str.adoc b/docs/man/nng_stream_dialer_set.3str.adoc new file mode 100644 index 00000000..1a1b6862 --- /dev/null +++ b/docs/man/nng_stream_dialer_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_dialer_set(3str) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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_stream_dialer_set - set option on byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_dialer_set(nng_stream_dialer *d, const char *name, const void *data, size_t size); + +int nng_stream_dialer_set_bool(nng_stream_dialer *d, const char *opt, int val); + +int nng_stream_dialer_set_int(nng_stream_dialer *d, const char *opt, int val); + +int nng_stream_dialer_set_ms(nng_stream_dialer *d, const char *opt, nng_duration val); + +int nng_stream_dialer_set_ptr(nng_stream_dialer *d, const char *opt, void *val); + +int nng_stream_dialer_set_size(nng_stream_dialer *d, const char *opt, size_t val); + +int nng_stream_dialer_set_string(nng_stream_dialer *d, const char *opt, const char *val); + +int nng_stream_dialer_set_uint64(nng_stream_dialer *d, const char *opt, uint64_t val); + +int nng_stream_dialer_set_addr(nng_stream_dialer *d, const char *opt, const nng_sockaddr *val); + +---- + +== DESCRIPTION + +The `nng_stream_dialer_set()` functions are used to configure options for the +xref:nng_stream.5.adoc[byte stream dialer] _d_. +The actual options that may be configured in this way vary, and are +specified by _opt_. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +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. + +`nng_stream_dialer_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _size_ is the +size of the objected located at _val_. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_dialer_set_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_set_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +the type +xref:nng_duration.5.adoc[`nng_duration`]. +The duration is an integer number of milliseconds. + +`nng_stream_dialer_set_ptr()`:: +This function is used to pass a pointer to structured data. +The data referenced by is generally managed by other functions. +For example, TLS configuration objects created with +xref:nng_tls_config.3tls.adoc[`nng_tls_config_alloc()`] +can be passed this way. ++ +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. +Please see the documentation for the specific option for further details. + +`nng_stream_dialer_set_size()`:: +This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_stream_dialer_set_string()`:: +This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_stream_dialer_set_uint64()`:: +This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options. + +`nng_stream_dialer_set_addr()`:: +This function is used to configure a +xref:nng_sockaddr.5.adoc[socket address]. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The dialer is closed. +`NNG_EINVAL`:: Either _data_ or _size_ are invalid. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EREADONLY`:: The option may not be modified. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
\ No newline at end of file |