= nng_stream_set(3str) // // Copyright 2020 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // // 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_set - set option on byte stream == SYNOPSIS [source, c] ---- #include int nng_stream_set(nng_stream *s, const char *name, const void *data, size_t size); int nng_stream_set_bool(nng_stream *s, const char *opt, bool val); int nng_stream_set_int(nng_stream *s, const char *opt, int val); int nng_stream_set_ms(nng_stream *s, const char *opt, nng_duration val); int nng_stream_set_ptr(nng_stream *s, const char *opt, void *val); int nng_stream_set_size(nng_stream *s, const char *opt, size_t val); int nng_stream_set_string(nng_stream *s, const char *opt, const char *val); int nng_stream_set_uint64(nng_stream *s, const char *opt, uint64_t val); int nng_stream_set_addr(nng_stream *s, const char *opt, const nng_sockaddr *val); ---- == DESCRIPTION The `nng_stream_set()` functions are used to configure options for the xref:nng_stream.5.adoc[byte stream] _s_. 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_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_set_bool()`:: This function is for options which take a Boolean (`bool`). `nng_stream_set_int()`:: This function is for options which take an integer (`int`). `nng_stream_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_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_alloc.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_set_size()`:: This function is used to configure a size, typically for buffer sizes, message maximum sizes, and similar options. `nng_stream_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_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_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 connection 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_get.3str.adoc[nng_stream_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.5.adoc[nng_stream(5)]