diff options
Diffstat (limited to 'docs/reference/src/stream')
21 files changed, 1761 insertions, 0 deletions
diff --git a/docs/reference/src/stream/nng_stream_close.3str.adoc b/docs/reference/src/stream/nng_stream_close.3str.adoc new file mode 100644 index 00000000..9e7b8d6a --- /dev/null +++ b/docs/reference/src/stream/nng_stream_close.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_close(3str) +// +// Copyright 2019 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_close - close byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_close(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_close()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with +an `NNG_ECLOSED` error condition. +Also, any new operations will fail with `NNG_ECLOSED` after the connection +is closed. + +NOTE: Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. + +NOTE: Closing the connection does not free the resources associated with it. +Once it is certain that no more operations are pending on the connection, +it should be freed with +xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_free.3str.adoc[nng_stream_free(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer.5.adoc b/docs/reference/src/stream/nng_stream_dialer.5.adoc new file mode 100644 index 00000000..eef23a3d --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer.5.adoc @@ -0,0 +1,46 @@ += nng_stream_dialer(5) +// +// Copyright 2019 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 - byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +typedef struct nng_stream_dialer nng_stream_dialer; +---- + +== DESCRIPTION + +(((byte stream, dialer))) +An `nng_stream_dialer` is a handle to a dialer for byte streams, +and is responsible for creating +xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte +streams) by connecting to remote peers. + +NOTE: The `nng_stream_dialer` object is used for low-level byte stream +connections, and should not be confused with a high-level +xref:nng_dialer.5.adoc[`nng_dialer`] object. + +== SEE ALSO + +[.text-left] +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc new file mode 100644 index 00000000..0c2db67c --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc @@ -0,0 +1,68 @@ += nng_stream_dialer_alloc(3str) +// +// Copyright 2019 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_alloc - allocate byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_dialer_alloc(nng_stream_dialer **dp, const char *addr); + +int nng_stream_dialer_alloc_url(nng_stream_dialer **dp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a dialer for byte streams. +Dialers create +xref:nng_stream.5.adoc[`nng_stream`] objects by initiating outgoing +connections, via the +xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] function. + +The first form, `nng_stream_dialer_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_dialer_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the dialer in the location referenced by _dp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)] +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)] +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)] +xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)] +xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)] +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc new file mode 100644 index 00000000..59d9dec0 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_dialer_close(3str) +// +// Copyright 2019 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_close - close byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_dialer_close(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_close()` function closes the supplied byte stream +dialer _d_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the dialer _d_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the dialer, so the +application should still free the memory using +xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc new file mode 100644 index 00000000..8dcd4ec2 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_dialer_dial(3str) +// +// Copyright 2020 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_dial - initiate outgoing byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_dialer_dial(nng_stream_dialer *d, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_dialer_dial()` attempts to establish a connection to the +remote peer for the dialer _d_. +The operation is completed asynchronously, using _aio_. + +TIP: The peer address is determined by the address specified using +xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc()`] or +xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc_url()`]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output. +(See +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].) + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: The address specified is invalid. +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The dialer is closed. +`NNG_ECONNREFUSED`:: The connection was refused by the server. +`NNG_ECONNRESET`:: The connection was reset by the server. +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc new file mode 100644 index 00000000..6669ca1e --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_dialer_free(3str) +// +// Copyright 2019 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_free - free byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_dialer_free(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_free()` function closes the supplied +byte stream dialer _d_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _d_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc new file mode 100644 index 00000000..4023e56f --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc @@ -0,0 +1,143 @@ += nng_stream_dialer_get(3str) +// +// Copyright 2020 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_get - get option from byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); + +int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); + +int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); + +int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); + +int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); + +int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); + +int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); + +int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); + +int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_dialer_get()` functions are used to retrieve option values for the +xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream dialer _d_. +The forms vary based on the type of the option they take. + +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_get()`:: +This function is untyped and can be used to retrieve the value of any option. +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 +_sizep_. ++ +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 referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_dialer_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_stream_dialer_get_ptr()`:: +This function is used to retrieve a pointer to structured data. +The data referenced 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. ++ +NOTE: Care must be taken to ensure that the application respects any +considerations about the lifetime of the underlying object. +See the documentation for the option for more specific guidance. + +`nng_stream_dialer_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_dialer_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_dialer_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_dialer_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The dialer is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_set.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_set.3str.adoc new file mode 100644 index 00000000..bd4ac478 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_dialer_set(3str) +// +// Copyright 2020 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, bool 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_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_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 diff --git a/docs/reference/src/stream/nng_stream_free.3str.adoc b/docs/reference/src/stream/nng_stream_free.3str.adoc new file mode 100644 index 00000000..30679458 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_free.3str.adoc @@ -0,0 +1,61 @@ += nng_stream_free(3str) +// +// Copyright 2019 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_free - free byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_free(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_free()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_, +and frees the underlying resources associated with it. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _s_, as the memory backing it will be reclaimed for other uses. + +NOTE: Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_get.3str.adoc b/docs/reference/src/stream/nng_stream_get.3str.adoc new file mode 100644 index 00000000..606fcc09 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_get.3str.adoc @@ -0,0 +1,146 @@ += nng_stream_get(3str) +// +// Copyright 2019 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_get - get option from byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_get(nng_stream *s, const char *opt, void *val, size_t *sizep); + +int nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp); + +int nng_stream_get_int(nng_stream *s, const char *opt, int *valp); + +int nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp); + +int nng_stream_get_ptr(nng_stream *s, const char *opt, void **valp); + +int nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp); + +int nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp); + +int nng_stream_get_string(nng_stream *s, const char *opt, char **valp); + +int nng_stream_get_uint64(nng_stream *s, const char *opt, uint64_t *valp); + +---- + +== DESCRIPTION + +The `nng_stream_get()` functions are used to retrieve option values for the +xref:nng_stream.5.adoc[byte stream] _conn_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream _s_. +The forms vary based on the type of the option they take. + +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_get()`:: +This function is untyped and can be used to retrieve the value of any option. +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 +_sizep_. ++ +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 referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_stream_get_ptr()`:: +This function is used to retrieve a pointer to structured data. +The data referenced 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. ++ +NOTE: Care must be taken to ensure that the application respects any +considerations about the lifetime of the underyling object. +See the documentation for the option for more specific guidance. + +`nng_stream_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The connection is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_set.3str.adoc[nng_stream_set(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)] diff --git a/docs/reference/src/stream/nng_stream_listener.5.adoc b/docs/reference/src/stream/nng_stream_listener.5.adoc new file mode 100644 index 00000000..b774a1b9 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener.5.adoc @@ -0,0 +1,48 @@ += nng_stream_listener(5) +// +// Copyright 2019 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_listener - byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +typedef struct nng_stream_listener nng_stream_listener; +---- + +== DESCRIPTION + +(((IPC, listener))) +An `nng_stream_listener` is a handle to a byte stream listener, +which is responsible for accepting incoming connections and creating +corresponding +xref:nng_stream.5.adoc[`nng_stream`] from them. + +NOTE: The `nng_stream_listener` object is a low-level object for +raw byte stream connections, +and should not be confused with a high-level +xref:nng_listener.5.adoc[`nng_listener`] object. + +== SEE ALSO + +[.text-left] +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_accept.3str.adoc b/docs/reference/src/stream/nng_stream_listener_accept.3str.adoc new file mode 100644 index 00000000..f5ffbca5 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_accept.3str.adoc @@ -0,0 +1,64 @@ += nng_stream_listener_accept(3str) +// +// Copyright 2019 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_listener_accept - accept incoming byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_listener_accept(nng_stream_listener *l, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_listener_accept()` attempts to accept an incoming byte stream +connection from a remote peer, using the listener _l_. +The operation is completed asynchronously, using _aio_. + +This operation can only be done after the listener is already +xref:nng_stream_listener_listen.3str.adoc[listening]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output, +which can be retrieved with +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The listener is closed. +`NNG_ECONNRESET`:: The connection was reset by the peer. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ESTATE`:: The listener is not not listening. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc b/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc new file mode 100644 index 00000000..966866ba --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc @@ -0,0 +1,70 @@ += nng_stream_listener_alloc(3str) +// +// Copyright 2019 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_listener_alloc - allocate byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_listener_alloc(nng_stream_listener **lp, const char *addr); + +int nng_stream_listener_alloc_url(nng_stream_listener **lp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a listener for byte streams. +Listeners create +xref:nng_stream.5.adoc[`nng_stream`] objects by accepting incoming +connections, via the +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`] +function. + +The first form, `nng_stream_listener_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_listener_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the listener in the location referenced by _lp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)] +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)] +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)] +xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)] +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)] +xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)] +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_close.3str.adoc b/docs/reference/src/stream/nng_stream_listener_close.3str.adoc new file mode 100644 index 00000000..a810509e --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_listener_close(3str) +// +// Copyright 2019 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_listener_close - close byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_listener_close(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_close()` function closes the supplied connected byte +stream listener _l_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the listener _l_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the listener, so the +application should still free the memory using +xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_free.3str.adoc b/docs/reference/src/stream/nng_stream_listener_free.3str.adoc new file mode 100644 index 00000000..aecd8895 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_listener_free(3str) +// +// Copyright 2019 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_listener_free - free byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_listener_free(nng_stream_listener *)l; +---- + +== DESCRIPTION + +The `nng_stream_listener_free()` function closes the supplied +byte stream listener _l_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] operations using __l are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _l_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_get.3str.adoc b/docs/reference/src/stream/nng_stream_listener_get.3str.adoc new file mode 100644 index 00000000..927e36a8 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_get.3str.adoc @@ -0,0 +1,144 @@ += nng_stream_listener_get(3str) +// +// Copyright 2019 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_listener_get - get option from byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_listener_get(nng_stream_listener *l, const char *opt, void *val, size_t *sizep); + +int nng_stream_listener_get_bool(nng_stream_listener *l, const char *opt, bool *valp); + +int nng_stream_listener_get_int(nng_stream_listener *l, const char *opt, int *valp); + +int nng_stream_listener_get_ms(nng_stream_listener *l, const char *opt, nng_duration *valp); + +int nng_stream_listener_get_ptr(nng_stream_listener *l, const char *opt, void **valp); + +int nng_stream_listener_get_size(nng_stream_listener *l, const char *opt, size_t *valp); + +int nng_stream_listener_get_addr(nng_stream_listener *l, const char *opt, nng_sockaddr *valp); + +int nng_stream_listener_get_string(nng_stream_listener *l, const char *opt, char **valp); + +int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_listener_get()` functions are used to retrieve option values +for the +xref:nng_stream_listener.5.adoc[byte stream listener] _l_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream listener _l_. +The forms vary based on the type of the option they take. + +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_listener_get()`:: +This function is untyped and can be used to retrieve the value of any option. +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 +_sizep_. ++ +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 referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_listener_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_listener_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_listener_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_stream_listener_get_ptr()`:: +This function is used to retrieve a pointer to structured data. +The data referenced 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. ++ +NOTE: Care must be taken to ensure that the application respects any +considerations about the lifetime of the underyling object. +See the documentation for the option for more specific guidance. + +`nng_stream_listener_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_listener_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_listener_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_listener_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The listener is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_listen.3str.adoc b/docs/reference/src/stream/nng_stream_listener_listen.3str.adoc new file mode 100644 index 00000000..e8473b52 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_listen.3str.adoc @@ -0,0 +1,66 @@ += nng_stream_listener_listen(3str) +// +// Copyright 2019 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_listener_listen - bind listener to configured address + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_listener_listen(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_listen()` attempts to bind the listener _l_ +to the local address specified when the listener was created. + +This must generally be done before accepting incoming connections using +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. + +For some transports this will also perform other actiosn. For example, +with TCP listeners it will configure the +underlying port into passive mode, ready to +accept an incoming connection, and established a listen queue +for receiving incoming connections. + +If binding the listener requires allocation of an address (for example +when a TCP port number of zero is specified, indicating that an +ephemeral port should be used), this operation will allocate that +resource. +This can permit retrieval of the selected address using +xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`], +typically with the +xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: The address is already in use. +`NNG_EADDRINVAL`:: The address is invalid or unavailable. +`NNG_ECLOSED`:: The listener has been closed. +`NNG_ESTATE`:: The listener is already bound. + +== SEE ALSO + +[.text-left] +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_set.3str.adoc b/docs/reference/src/stream/nng_stream_listener_set.3str.adoc new file mode 100644 index 00000000..ccabe5ca --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_listener_set(3str) +// +// Copyright 2020 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_listener_set - set option on byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_stream_listener_set(nng_stream_listener *l, const char *name, const void *data, size_t size); + +int nng_stream_listener_set_bool(nng_stream_listener *l, const char *opt, bool val); + +int nng_stream_listener_set_int(nng_stream_listener *l, const char *opt, int val); + +int nng_stream_listener_set_ms(nng_stream_listener *l, const char *opt, nng_duration val); + +int nng_stream_listener_set_ptr(nng_stream_listener *l, const char *opt, void *val); + +int nng_stream_listener_set_size(nng_stream_listener *l, const char *opt, size_t val); + +int nng_stream_listener_set_string(nng_stream_listener *l, const char *opt, const char *val); + +int nng_stream_listener_set_uint64(nng_stream_listener *l, const char *opt, uint64_t val); + +int nng_stream_listener_set_addr(nng_stream_listener *l, const char *opt, const nng_sockaddr *val); + +---- + +== DESCRIPTION + +The `nng_stream_listener_set()` functions are used to configure options for the +xref:nng_stream.5.adoc[byte stream listener] _l_. +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_listener_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_listener_set_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_listener_set_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_listener_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_listener_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_listener_set_size()`:: +This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_stream_listener_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_listener_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_listener_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 listener 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_listener_get.3str.adoc[nng_stream_listener_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_listener.5.adoc[nng_stream_listener(5)]
\ No newline at end of file diff --git a/docs/reference/src/stream/nng_stream_recv.3str.adoc b/docs/reference/src/stream/nng_stream_recv.3str.adoc new file mode 100644 index 00000000..148be978 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_recv.3str.adoc @@ -0,0 +1,74 @@ += nng_stream_recv(3str) +// +// Copyright 2019 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_recv - receive from byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_recv(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_recv()` function starts an asynchronous receive from the +xref:nng_stream.5.adoc[byte stream] _s_ +into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, +and the final result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +received, or an error has occurred. +Therefore, the number of bytes read may be less than requested. +The actual number of bytes read can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ECONNSHUT`:: Remote peer shutdown after sending data. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_send.3str.adoc b/docs/reference/src/stream/nng_stream_send.3str.adoc new file mode 100644 index 00000000..5a53e63c --- /dev/null +++ b/docs/reference/src/stream/nng_stream_send.3str.adoc @@ -0,0 +1,74 @@ += nng_stream_send(3str) +// +// Copyright 2020 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_send - send to byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +void nng_stream_send(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_send()` function starts an asynchronous send over the +xref:nng_stream.5.adoc[byte stream] _s_ +from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] +function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, and the final +result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +sent, or an error has occurred. +Therefore, the number of bytes sent may be less than requested. +The actual number of bytes sent can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_set.3str.adoc b/docs/reference/src/stream/nng_stream_set.3str.adoc new file mode 100644 index 00000000..e4a82a1a --- /dev/null +++ b/docs/reference/src/stream/nng_stream_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_set(3str) +// +// Copyright 2020 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_set - set option on byte stream + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +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)]
\ No newline at end of file |