diff options
| author | Garrett D'Amore <garrett@damore.org> | 2024-04-08 20:18:34 -0700 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2024-04-08 20:18:34 -0700 |
| commit | 1a66ecd1098d4d8e10806e32741acc35a6d08f8d (patch) | |
| tree | 9b651cfd0d9d1fa2b316a3236eba7f2d264e3566 /docs | |
| parent | c7f7bcb6e2cfbf66c7fab158b0ac02890243b5bb (diff) | |
| download | nng-doc-reorg.tar.gz nng-doc-reorg.tar.bz2 nng-doc-reorg.zip | |
nng_stream_* converteddoc-reorg
Diffstat (limited to 'docs')
41 files changed, 1016 insertions, 1684 deletions
diff --git a/docs/man/nng_stream_close.3str.adoc b/docs/man/nng_stream_close.3str.adoc deleted file mode 100644 index 9e7b8d6a..00000000 --- a/docs/man/nng_stream_close.3str.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= 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/man/nng_stream_dialer.5.adoc b/docs/man/nng_stream_dialer.5.adoc deleted file mode 100644 index eef23a3d..00000000 --- a/docs/man/nng_stream_dialer.5.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= 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/man/nng_stream_dialer_alloc.3str.adoc b/docs/man/nng_stream_dialer_alloc.3str.adoc deleted file mode 100644 index 0c2db67c..00000000 --- a/docs/man/nng_stream_dialer_alloc.3str.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= 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/man/nng_stream_dialer_close.3str.adoc b/docs/man/nng_stream_dialer_close.3str.adoc deleted file mode 100644 index 59d9dec0..00000000 --- a/docs/man/nng_stream_dialer_close.3str.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= 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/man/nng_stream_dialer_dial.3str.adoc b/docs/man/nng_stream_dialer_dial.3str.adoc deleted file mode 100644 index 8dcd4ec2..00000000 --- a/docs/man/nng_stream_dialer_dial.3str.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= 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/man/nng_stream_dialer_free.3str.adoc b/docs/man/nng_stream_dialer_free.3str.adoc deleted file mode 100644 index 6669ca1e..00000000 --- a/docs/man/nng_stream_dialer_free.3str.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= 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/man/nng_stream_dialer_set.3str.adoc b/docs/man/nng_stream_dialer_set.3str.adoc deleted file mode 100644 index bd4ac478..00000000 --- a/docs/man/nng_stream_dialer_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= 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/man/nng_stream_free.3str.adoc b/docs/man/nng_stream_free.3str.adoc deleted file mode 100644 index 30679458..00000000 --- a/docs/man/nng_stream_free.3str.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= 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/man/nng_stream_get.3str.adoc b/docs/man/nng_stream_get.3str.adoc deleted file mode 100644 index 606fcc09..00000000 --- a/docs/man/nng_stream_get.3str.adoc +++ /dev/null @@ -1,146 +0,0 @@ -= 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/man/nng_stream_listener.5.adoc b/docs/man/nng_stream_listener.5.adoc deleted file mode 100644 index b774a1b9..00000000 --- a/docs/man/nng_stream_listener.5.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= 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/man/nng_stream_listener_accept.3str.adoc b/docs/man/nng_stream_listener_accept.3str.adoc deleted file mode 100644 index f5ffbca5..00000000 --- a/docs/man/nng_stream_listener_accept.3str.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= 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/man/nng_stream_listener_alloc.3str.adoc b/docs/man/nng_stream_listener_alloc.3str.adoc deleted file mode 100644 index 966866ba..00000000 --- a/docs/man/nng_stream_listener_alloc.3str.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= 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/man/nng_stream_listener_close.3str.adoc b/docs/man/nng_stream_listener_close.3str.adoc deleted file mode 100644 index a810509e..00000000 --- a/docs/man/nng_stream_listener_close.3str.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= 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/man/nng_stream_listener_free.3str.adoc b/docs/man/nng_stream_listener_free.3str.adoc deleted file mode 100644 index aecd8895..00000000 --- a/docs/man/nng_stream_listener_free.3str.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= 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/man/nng_stream_listener_get.3str.adoc b/docs/man/nng_stream_listener_get.3str.adoc deleted file mode 100644 index 927e36a8..00000000 --- a/docs/man/nng_stream_listener_get.3str.adoc +++ /dev/null @@ -1,144 +0,0 @@ -= 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/man/nng_stream_listener_listen.3str.adoc b/docs/man/nng_stream_listener_listen.3str.adoc deleted file mode 100644 index e8473b52..00000000 --- a/docs/man/nng_stream_listener_listen.3str.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= 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/man/nng_stream_listener_set.3str.adoc b/docs/man/nng_stream_listener_set.3str.adoc deleted file mode 100644 index ccabe5ca..00000000 --- a/docs/man/nng_stream_listener_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= 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/man/nng_stream_recv.3str.adoc b/docs/man/nng_stream_recv.3str.adoc deleted file mode 100644 index 148be978..00000000 --- a/docs/man/nng_stream_recv.3str.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= 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/man/nng_stream_send.3str.adoc b/docs/man/nng_stream_send.3str.adoc deleted file mode 100644 index 5a53e63c..00000000 --- a/docs/man/nng_stream_send.3str.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= 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/man/nng_stream_set.3str.adoc b/docs/man/nng_stream_set.3str.adoc deleted file mode 100644 index e4a82a1a..00000000 --- a/docs/man/nng_stream_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= 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 diff --git a/docs/ref/str/nng_stream_close.adoc b/docs/ref/str/nng_stream_close.adoc new file mode 100644 index 00000000..c4afe8a7 --- /dev/null +++ b/docs/ref/str/nng_stream_close.adoc @@ -0,0 +1,29 @@ +## nng_stream_close + +Close byte stream. + +### Synopsis + +```c +#include <nng/nng.h> + +void nng_stream_close(nng_stream *s); +``` + +### Description + +The `nng_stream_close` function closes the byte stream _s_. + +Any pending operations, as well as any further new operations, will fail with an `NNG_ECLOSED` error. + +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.adoc[`nng_stream_free`]. + +### See Also + +xref:nng_stream_free.adoc[nng_stream_free], +xref:nng_stream_recv.adoc[nng_stream_recv], +xref:nng_stream_send.adoc[nng_stream_send] diff --git a/docs/ref/str/nng_stream_dialer.5.adoc.adoc b/docs/ref/str/nng_stream_dialer.5.adoc.adoc new file mode 100644 index 00000000..6e3b2083 --- /dev/null +++ b/docs/ref/str/nng_stream_dialer.5.adoc.adoc @@ -0,0 +1,25 @@ +## nng_stream_dialer + +Byte stream dialer. + +### Synopsis + +```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 `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:../dialer/index.adoc[`nng_dialer`] object. + +### See Also + +xref:nng_stream_dialer_alloc.adoc[nng_stream_dialer_alloc], +xref:nng_stream_dialer_close.adoc[nng_stream_dialer_close], +xref:nng_stream_dialer_dial.adoc[nng_stream_dialer_dial], +xref:nng_stream_dialer_free.adoc[nng_stream_dialer_free] diff --git a/docs/ref/str/nng_stream_dialer_alloc.adoc b/docs/ref/str/nng_stream_dialer_alloc.adoc new file mode 100644 index 00000000..d18d6733 --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_alloc.adoc @@ -0,0 +1,46 @@ +## nng_stream_dialer_alloc + +Allocate byte stream dialer. + +### Synopsis + +```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 byte stream objects by initiating outgoing connections, via the xref:nng_stream_dialer_dial.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:../util/nng_url.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 + +xref:nng_stream_dialer_close.adoc[nng_stream_dialer_close], +xref:nng_stream_dialer_dial.adoc[nng_stream_dialer_dial], +xref:nng_stream_dialer_free.adoc[nng_stream_dialer_free], +xref:nng_stream_dialer_get.adoc[nng_stream_dialer_get], +xref:nng_stream_dialer_set.adoc[nng_stream_dialer_set] diff --git a/docs/ref/str/nng_stream_dialer_close.adoc b/docs/ref/str/nng_stream_dialer_close.adoc new file mode 100644 index 00000000..637f20e1 --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_close.adoc @@ -0,0 +1,26 @@ +## nng_stream_dialer_close + +Close byte stream dialer. + +### Synopsis + +```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. + +Any pending or new operations using _d_ will fail with an `NNG_ECLOSED` error condition. + +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.adoc[`nng_stream_dialer_free`] once it is certain that nothing else is using it. + +### See Also + +xref:nng_stream_dialer_alloc.adoc[nng_stream_dialer_alloc], +xref:nng_stream_dialer_dial.adoc[nng_stream_dialer_dial], +xref:nng_stream_dialer_free.adoc[nng_stream_dialer_free] diff --git a/docs/ref/str/nng_stream_dialer_dial.adoc b/docs/ref/str/nng_stream_dialer_dial.adoc new file mode 100644 index 00000000..ee7eb99b --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_dial.adoc @@ -0,0 +1,37 @@ +## nng_stream_dialer_dial + +Initiate outgoing byte stream connection. + +### Synopsis + +```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.adoc[`nng_stream_dialer_alloc`] or xref:nng_stream_dialer_alloc.adoc[`nng_stream_dialer_alloc_url`]. + +If a connection is successfully established, the _aio_ will have the resulting `nng_stream` object stored as its first output. +(See xref:../aio/nng_aio_get_output.adoc[`nng_aio_get_output`].) + +### 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 + +xref:../aio/index.adoc[Asynchronous I/O], +xref:nng_stream_dialer_alloc.adoc[nng_stream_dialer_alloc], +xref:nng_stream_dialer_close.adoc[nng_stream_dialer_close] diff --git a/docs/ref/str/nng_stream_dialer_free.adoc b/docs/ref/str/nng_stream_dialer_free.adoc new file mode 100644 index 00000000..ecebb3d7 --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_free.adoc @@ -0,0 +1,24 @@ +## nng_stream_dialer_free + +Free byte stream dialer. + +### Synopsis + +```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.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. + +### See Also + +xref:nng_stream_dialer_alloc.adoc[nng_stream_dialer_alloc], +xref:nng_stream_dialer_close.adoc[nng_stream_dialer_close] diff --git a/docs/man/nng_stream_dialer_get.3str.adoc b/docs/ref/str/nng_stream_dialer_get.adoc index 4023e56f..5bc98540 100644 --- a/docs/man/nng_stream_dialer_get.3str.adoc +++ b/docs/ref/str/nng_stream_dialer_get.adoc @@ -1,64 +1,44 @@ -= 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] ----- +## nng_stream_dialer_get + +Get option from byte stream dialer. + +### Synopsis + +```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 +### 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 `nng_stream_dialer_get` functions are used to retrieve option values for the +xref:nng_stream_dialer.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. +A number of them are documented in xref:../options/index.adoc[Options] and additional linked documents. -=== Forms +#### Forms -In all of these forms, the option _opt_ is retrieved from the connected -byte stream dialer _d_. +In all of these forms, the option _opt_ is retrieved from the 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()`:: +TIP: It may be easier to use one of the typed forms of this function. + +`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 @@ -75,23 +55,19 @@ 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()`:: +`nng_stream_dialer_get_bool`:: This function is for options which take a Boolean (`bool`). -`nng_stream_dialer_get_int()`:: +`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. +`nng_stream_dialer_get_ms`:: +This function is used to retrieve time durations, 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()`:: +`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 @@ -101,31 +77,28 @@ 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()`:: +`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()`:: +`nng_stream_dialer_get_addr`:: This function is used to retrieve a -xref:nng_sockaddr.5.adoc[socket address]. +xref:../opts/nng_sockaddr.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_string`:: +This function is used to retrieve a `NUL`-terminated string. +This string is created from the source using xref:../util/nng_strdup.adoc[`nng_strdup`]. +Consequently, it must be freed by the caller using xref:../util/nng_strfree.adoc[`nng_strfree`] when it is no longer needed. -`nng_stream_dialer_get_uint64()`:: +`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. +This is typically used for identifiers, network numbers, and similar options. -== RETURN VALUES +### Return Values These functions return 0 on success, and non-zero otherwise. -== ERRORS +### Errors [horizontal] `NNG_ECLOSED`:: The dialer is closed. @@ -134,10 +107,7 @@ These functions return 0 on success, and non-zero otherwise. `NNG_ENOTSUP`:: The option is not supported. `NNG_EWRITEONLY`:: The option may not read. -== SEE ALSO +### 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)] +xref:../opts/index.adoc[Options], +xref:nng_stream_dialer_set.adoc[nng_stream_dialer_set] diff --git a/docs/ref/str/nng_stream_dialer_set.adoc b/docs/ref/str/nng_stream_dialer_set.adoc new file mode 100644 index 00000000..16505d7b --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_set.adoc @@ -0,0 +1,89 @@ +## nng_stream_dialer_set + +Set option on byte stream dialer. + +### Synopsis + +```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 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:../opts/index.adoc[Options]. + +Additionally some transport-specific options are documented with the transports. + +TIP: It may be easier to use one of the typed forms of this function. + +#### 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_. + +`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.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. ++ +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 set a size option. + +`nng_stream_dialer_set_string`:: +This function is used to set a string option. +Strings passed this way must be legal UTF-8 strings, terminated with a `NUL` (`\0`) byte. + +`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:../opts/nng_sockaddr.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 + +xref:../opts/index.adoc[Options], +xref:nng_stream_dialer_get.adoc[nng_stream_dialer_get] diff --git a/docs/ref/str/nng_stream_free.adoc b/docs/ref/str/nng_stream_free.adoc new file mode 100644 index 00000000..0494926d --- /dev/null +++ b/docs/ref/str/nng_stream_free.adoc @@ -0,0 +1,28 @@ +## nng_stream_free + +Free byte stream. + +### Synopsis + +```c +#include <nng/nng.h> + +void nng_stream_free(nng_stream *s); +``` + +### Description + +The `nng_stream_free` function closes the byte stream _s_, and frees the underlying resources associated with it. + +Any pending operations using _s_ will fail with an `NNG_ECLOSED` error. + +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. + +### See Also + +xref:nng_stream_close.adoc[nng_stream_close], +xref:nng_stream_recv.adoc[nng_stream_recv], +xref:nng_stream_send.adoc[nng_stream_send] diff --git a/docs/ref/str/nng_stream_get.adoc b/docs/ref/str/nng_stream_get.adoc new file mode 100644 index 00000000..f527dc8a --- /dev/null +++ b/docs/ref/str/nng_stream_get.adoc @@ -0,0 +1,98 @@ +## nng_stream_get + +Get option from byte stream. + +### Synopsis + +```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 byte stream _s_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:../opts/index.adoc[Options]. + +#### 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. + +TIP: It may be easier to use one of the typed forms of this function. + +`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. + +`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 durations (`nng_duration`), 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. ++ +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 option. + +`nng_stream_get_addr`:: +This function is used to retrieve a xref:../opts/nng_sockaddr.adoc[socket address]. + +`nng_stream_get_string`:: +This function is used to retrieve a `NUL`-terminated string. +This string is created from the source using xref:nng_strdup.adoc[`nng_strdup`]. +Consequently, it must be freed by the caller using xref:nng_strfree.adoc[`nng_strfree`] when it is no longer needed. + +`nng_stream_get_uint64`:: +This function is used to retrieve a 64-bit unsigned value. + +### 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 + +xref:../opts/index.adoc[Options], +xref:nng_stream_set.adoc[nng_stream_set] diff --git a/docs/ref/str/nng_stream_listener.5.adoc.adoc b/docs/ref/str/nng_stream_listener.5.adoc.adoc new file mode 100644 index 00000000..d2a469e1 --- /dev/null +++ b/docs/ref/str/nng_stream_listener.5.adoc.adoc @@ -0,0 +1,27 @@ +## nng_stream_listener + +Byte stream listener. + +### Synopsis + +```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 `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:../listener/nng_listener.adoc[`nng_listener`] object. + +### See Also + +xref:nng_stream_listener_accept.adoc[nng_stream_listener_accept], +xref:nng_stream_listener_alloc.adoc[nng_stream_listener_alloc], +xref:nng_stream_listener_close.adoc[nng_stream_listener_close], +xref:nng_stream_listener_free.adoc[nng_stream_listener_free], +xref:nng_stream_listener_listen.adoc[nng_stream_listener_listen], +xref:nng_stream_dialer.adoc[nng_stream_dialer] diff --git a/docs/ref/str/nng_stream_listener_accept.adoc b/docs/ref/str/nng_stream_listener_accept.adoc new file mode 100644 index 00000000..6d04f8b7 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_accept.adoc @@ -0,0 +1,37 @@ +## nng_stream_listener_accept + +Accept incoming byte stream connection. + +### Synopsis + +```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.adoc[listening]. + +If a connection is successfully established, the _aio_ will have the resulting `nng_stream` object stored as its first output, which can be retrieved with xref:../aio/nng_aio_get_output.adoc[`nng_aio_get_output`]. + +### 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 + +xref:../aio/index.adoc[Asynchronous I/O], +xref:nng_stream_listener_alloc.adoc[nng_stream_listener_alloc], +xref:nng_stream_listener_close.adoc[nng_stream_listener_close], +xref:nng_stream_listener_free.adoc[nng_stream_listener_free], +xref:nng_stream_listener_listen.adoc[nng_stream_listener_listen], diff --git a/docs/ref/str/nng_stream_listener_alloc.adoc b/docs/ref/str/nng_stream_listener_alloc.adoc new file mode 100644 index 00000000..10cbbf44 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_alloc.adoc @@ -0,0 +1,46 @@ +## nng_stream_listener_alloc + +Allocate byte stream listener. + +### Synopsis + +```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 `nng_stream` objects by accepting incoming connections, via the xref:nng_stream_listener_accept.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:../opts/nng_url.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 + +xref:nng_stream_listener_accept.adoc[nng_stream_listener_accept], +xref:nng_stream_listener_close.adoc[nng_stream_listener_close], +xref:nng_stream_listener_free.adoc[nng_stream_listener_free], +xref:nng_stream_listener_get.adoc[nng_stream_listener_get], +xref:nng_stream_listener_listen.adoc[nng_stream_listener_listen], +xref:nng_stream_listener_set.adoc[nng_stream_listener_set] diff --git a/docs/ref/str/nng_stream_listener_close.adoc b/docs/ref/str/nng_stream_listener_close.adoc new file mode 100644 index 00000000..5ec8d7fc --- /dev/null +++ b/docs/ref/str/nng_stream_listener_close.adoc @@ -0,0 +1,43 @@ +## nng_stream_listener_close + +Close byte stream listener. + +### Synopsis + +```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.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.adoc[`nng_stream_listener_free`] +once it is certain that nothing else is using it. + +### Return Values + +None. + +### Errors + +None. + +### See Also + +xref:nng_strerror.adoc[nng_strerror], +xref:nng_stream_listener_accept.adoc[nng_stream_listener_accept], +xref:nng_stream_listener_alloc.adoc[nng_stream_listener_alloc], +xref:nng_stream_listener_free.adoc[nng_stream_listener_free], +xref:nng_stream_listener.adoc[nng_stream_listener] diff --git a/docs/ref/str/nng_stream_listener_free.adoc b/docs/ref/str/nng_stream_listener_free.adoc new file mode 100644 index 00000000..ebf84bb7 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_free.adoc @@ -0,0 +1,25 @@ +## nng_stream_listener_free + +Free byte stream listener. + +### Synopsis + +```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.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. + +### See Also + +xref:nng_stream_listener_accept.adoc[nng_stream_listener_accept], +xref:nng_stream_listener_alloc.adoc[nng_stream_listener_alloc], +xref:nng_stream_listener_close.adoc[nng_stream_listener_close] diff --git a/docs/ref/str/nng_stream_listener_get.adoc b/docs/ref/str/nng_stream_listener_get.adoc new file mode 100644 index 00000000..5ac62cb8 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_get.adoc @@ -0,0 +1,99 @@ +## nng_stream_listener_get + +Get option from byte stream listener. + +### Synopsis + +```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 byte stream listener _l_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:../opts/index.adoc[Options]. + +#### Forms + +In all of these forms, the option _opt_ is retrieved from the 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. + +TIP: It may be easier to use one of the typed forms of this function. + +`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. + +`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 durations (`nng_duration`) 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. ++ +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:../opts/nng_sockaddr.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:../util/nng_strdup.adoc[`nng_strdup`]. +Consequently, it must be freed by the caller using xref:../util/nng_strfree.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. + +### 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 + +xref:../opts/index.adoc[Options], +xref:nng_stream_listener_set.adoc[nng_stream_listener_set] diff --git a/docs/ref/str/nng_stream_listener_listen.adoc b/docs/ref/str/nng_stream_listener_listen.adoc new file mode 100644 index 00000000..6568ad41 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_listen.adoc @@ -0,0 +1,40 @@ +## nng_stream_listener_listen + +Bind listener to configured address. + +### Synopsis + +```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.adoc[`nng_stream_listener_accept`]. + +For some transports this will also perform other actions. +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.adoc[`nng_stream_listener_get`], typically with the `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 + +xref:nng_stream_listener_accept.adoc[nng_stream_listener_accept] diff --git a/docs/ref/str/nng_stream_listener_set.adoc b/docs/ref/str/nng_stream_listener_set.adoc new file mode 100644 index 00000000..58bd7448 --- /dev/null +++ b/docs/ref/str/nng_stream_listener_set.adoc @@ -0,0 +1,92 @@ +## nng_stream_listener_set + +Set option on byte stream listener. + +### Synopsis + +```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 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 ../opts/index.adoc[Options]. + +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. + +TIP: It may be easier to use one of the typed forms of this function. + +`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_. + +`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 (`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. ++ +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 set size options. + +`nng_stream_listener_set_string`:: +This function is used to set string options. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated with a `NUL` (`\0`) byte. + +`nng_stream_listener_set_uint64`:: +This function is used to configure a 64-bit unsigned value. + +`nng_stream_listener_set_addr`:: +This function is used to configure a xref:../opts/nng_sockaddr.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 + +xref:nng_strerror.adoc[nng_strerror], +xref:nng_stream_listener_get.adoc[nng_stream_listener_get], +xref:nng_options.adoc[nng_options], +xref:nng_ipc_options.adoc[nng_ipc_options], +xref:nng_tcp_options.adoc[nng_tcp_options], +xref:nng_tls_options.adoc[nng_tls_options], +xref:nng_stream_listener.adoc[nng_stream_listener] diff --git a/docs/ref/str/nng_stream_recv.adoc b/docs/ref/str/nng_stream_recv.adoc new file mode 100644 index 00000000..c91132ab --- /dev/null +++ b/docs/ref/str/nng_stream_recv.adoc @@ -0,0 +1,43 @@ +## nng_stream_recv + +Receive from byte stream. + +### Synopsis + +```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 byte stream _s_ into the scatter/gather vector located in the asynchronous I/O structure _aio_. + +NOTE: The xref:../aio/nng_aio_set_iov.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.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:../aio/nng_aio_count.adoc[`nng_aio_count`]. + +### 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 + +xref:../aio/index.adoc[Asynchronous I/O], +xref:nng_aio_count.adoc[nng_aio_count], +xref:nng_aio_result.adoc[nng_aio_result], +xref:nng_aio_set_iov.adoc[nng_aio_set_iov] diff --git a/docs/ref/str/nng_stream_send.adoc b/docs/ref/str/nng_stream_send.adoc new file mode 100644 index 00000000..48352c34 --- /dev/null +++ b/docs/ref/str/nng_stream_send.adoc @@ -0,0 +1,41 @@ +## nng_stream_send + +Send to byte stream. + +### Synopsis + +```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 byte stream _s_ from the scatter/gather vector located in the asynchronous I/O structure _aio_. + +NOTE: The xref:../aio/nng_aio_set_iov.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:../aio/nng_aio_result.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:../aio/nng_aio_count.adoc[`nng_aio_count`]. + +### 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 + +xref:../aio/index.adoc[Asynchronous I/O], +xref:nng_aio_count.adoc[nng_aio_count], +xref:nng_aio_result.adoc[nng_aio_result], +xref:nng_aio_set_iov.adoc[nng_aio_set_iov] diff --git a/docs/ref/str/nng_stream_set.adoc b/docs/ref/str/nng_stream_set.adoc new file mode 100644 index 00000000..d6aea2c6 --- /dev/null +++ b/docs/ref/str/nng_stream_set.adoc @@ -0,0 +1,85 @@ +## nng_stream_set + +Set option on byte stream. + +### Synopsis + +```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 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:../opts/index.adoc[Options]. + +#### 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. + +TIP: It may be easier to use one of the typed forms of this function. + +`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_. + +`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 (`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. ++ +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. + +`nng_stream_set_uint64`:: +This function is used to configure a 64-bit unsigned value. + +`nng_stream_set_addr`:: +This function is used to configure a xref:../opts/nng_sockaddr.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 + +xref:../opts/index.adoc[Options], +xref:nng_stream_get.adoc[nng_stream_get] |