From 1a66ecd1098d4d8e10806e32741acc35a6d08f8d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 8 Apr 2024 20:18:34 -0700 Subject: nng_stream_* converted --- docs/man/nng_stream_close.3str.adoc | 65 ------------ docs/man/nng_stream_dialer.5.adoc | 46 -------- docs/man/nng_stream_dialer_alloc.3str.adoc | 68 ------------ docs/man/nng_stream_dialer_close.3str.adoc | 60 ----------- docs/man/nng_stream_dialer_dial.3str.adoc | 65 ------------ docs/man/nng_stream_dialer_free.3str.adoc | 54 ---------- docs/man/nng_stream_dialer_get.3str.adoc | 143 ------------------------- docs/man/nng_stream_dialer_set.3str.adoc | 133 ----------------------- docs/man/nng_stream_free.3str.adoc | 61 ----------- docs/man/nng_stream_get.3str.adoc | 146 -------------------------- docs/man/nng_stream_listener.5.adoc | 48 --------- docs/man/nng_stream_listener_accept.3str.adoc | 64 ----------- docs/man/nng_stream_listener_alloc.3str.adoc | 70 ------------ docs/man/nng_stream_listener_close.3str.adoc | 60 ----------- docs/man/nng_stream_listener_free.3str.adoc | 54 ---------- docs/man/nng_stream_listener_get.3str.adoc | 144 ------------------------- docs/man/nng_stream_listener_listen.3str.adoc | 66 ------------ docs/man/nng_stream_listener_set.3str.adoc | 133 ----------------------- docs/man/nng_stream_recv.3str.adoc | 74 ------------- docs/man/nng_stream_send.3str.adoc | 74 ------------- docs/man/nng_stream_set.3str.adoc | 133 ----------------------- docs/ref/str/nng_stream_close.adoc | 29 +++++ docs/ref/str/nng_stream_dialer.5.adoc.adoc | 25 +++++ docs/ref/str/nng_stream_dialer_alloc.adoc | 46 ++++++++ docs/ref/str/nng_stream_dialer_close.adoc | 26 +++++ docs/ref/str/nng_stream_dialer_dial.adoc | 37 +++++++ docs/ref/str/nng_stream_dialer_free.adoc | 24 +++++ docs/ref/str/nng_stream_dialer_get.adoc | 113 ++++++++++++++++++++ docs/ref/str/nng_stream_dialer_set.adoc | 89 ++++++++++++++++ docs/ref/str/nng_stream_free.adoc | 28 +++++ docs/ref/str/nng_stream_get.adoc | 98 +++++++++++++++++ docs/ref/str/nng_stream_listener.5.adoc.adoc | 27 +++++ docs/ref/str/nng_stream_listener_accept.adoc | 37 +++++++ docs/ref/str/nng_stream_listener_alloc.adoc | 46 ++++++++ docs/ref/str/nng_stream_listener_close.adoc | 43 ++++++++ docs/ref/str/nng_stream_listener_free.adoc | 25 +++++ docs/ref/str/nng_stream_listener_get.adoc | 99 +++++++++++++++++ docs/ref/str/nng_stream_listener_listen.adoc | 40 +++++++ docs/ref/str/nng_stream_listener_set.adoc | 92 ++++++++++++++++ docs/ref/str/nng_stream_recv.adoc | 43 ++++++++ docs/ref/str/nng_stream_send.adoc | 41 ++++++++ docs/ref/str/nng_stream_set.adoc | 85 +++++++++++++++ 42 files changed, 1093 insertions(+), 1761 deletions(-) delete mode 100644 docs/man/nng_stream_close.3str.adoc delete mode 100644 docs/man/nng_stream_dialer.5.adoc delete mode 100644 docs/man/nng_stream_dialer_alloc.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_close.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_dial.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_free.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_get.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_set.3str.adoc delete mode 100644 docs/man/nng_stream_free.3str.adoc delete mode 100644 docs/man/nng_stream_get.3str.adoc delete mode 100644 docs/man/nng_stream_listener.5.adoc delete mode 100644 docs/man/nng_stream_listener_accept.3str.adoc delete mode 100644 docs/man/nng_stream_listener_alloc.3str.adoc delete mode 100644 docs/man/nng_stream_listener_close.3str.adoc delete mode 100644 docs/man/nng_stream_listener_free.3str.adoc delete mode 100644 docs/man/nng_stream_listener_get.3str.adoc delete mode 100644 docs/man/nng_stream_listener_listen.3str.adoc delete mode 100644 docs/man/nng_stream_listener_set.3str.adoc delete mode 100644 docs/man/nng_stream_recv.3str.adoc delete mode 100644 docs/man/nng_stream_send.3str.adoc delete mode 100644 docs/man/nng_stream_set.3str.adoc create mode 100644 docs/ref/str/nng_stream_close.adoc create mode 100644 docs/ref/str/nng_stream_dialer.5.adoc.adoc create mode 100644 docs/ref/str/nng_stream_dialer_alloc.adoc create mode 100644 docs/ref/str/nng_stream_dialer_close.adoc create mode 100644 docs/ref/str/nng_stream_dialer_dial.adoc create mode 100644 docs/ref/str/nng_stream_dialer_free.adoc create mode 100644 docs/ref/str/nng_stream_dialer_get.adoc create mode 100644 docs/ref/str/nng_stream_dialer_set.adoc create mode 100644 docs/ref/str/nng_stream_free.adoc create mode 100644 docs/ref/str/nng_stream_get.adoc create mode 100644 docs/ref/str/nng_stream_listener.5.adoc.adoc create mode 100644 docs/ref/str/nng_stream_listener_accept.adoc create mode 100644 docs/ref/str/nng_stream_listener_alloc.adoc create mode 100644 docs/ref/str/nng_stream_listener_close.adoc create mode 100644 docs/ref/str/nng_stream_listener_free.adoc create mode 100644 docs/ref/str/nng_stream_listener_get.adoc create mode 100644 docs/ref/str/nng_stream_listener_listen.adoc create mode 100644 docs/ref/str/nng_stream_listener_set.adoc create mode 100644 docs/ref/str/nng_stream_recv.adoc create mode 100644 docs/ref/str/nng_stream_send.adoc create mode 100644 docs/ref/str/nng_stream_set.adoc (limited to 'docs') 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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_close - close byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer - byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_alloc - allocate byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_close - close byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_dial - initiate outgoing byte stream connection - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions - -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_free - free byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -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_get.3str.adoc b/docs/man/nng_stream_dialer_get.3str.adoc deleted file mode 100644 index 4023e56f..00000000 --- a/docs/man/nng_stream_dialer_get.3str.adoc +++ /dev/null @@ -1,143 +0,0 @@ -= nng_stream_dialer_get(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_get - get option from byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); - -int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); - -int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); - -int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); - -int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); - -int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); - -int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); - -int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); - -int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); ----- - -== DESCRIPTION - - -The `nng_stream_dialer_get()` functions are used to retrieve option values for the -xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_. - -The actual options that may be retrieved in this way vary. -A number of them are documented in -xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the connected -byte stream dialer _d_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_stream_dialer_get()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_sizep_. -+ -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _sizep_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _sizep_ does not exceed the original buffer size. -+ -It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_stream_dialer_get_bool()`:: -This function is for options which take a Boolean (`bool`). - -`nng_stream_dialer_get_int()`:: -This function is for options which take an integer (`int`). - -`nng_stream_dialer_get_ms()`:: -This function is used to retrieve time -xref:nng_duration.5.adoc[durations] -(such as timeouts), stored as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_stream_dialer_get_ptr()`:: -This function is used to retrieve a pointer to structured data. -The data referenced is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. -+ -NOTE: Care must be taken to ensure that the application respects any -considerations about the lifetime of the underlying object. -See the documentation for the option for more specific guidance. - -`nng_stream_dialer_get_size()`:: -This function is used to retrieve a size, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_stream_dialer_get_addr()`:: -This function is used to retrieve a -xref:nng_sockaddr.5.adoc[socket address]. - -`nng_stream_dialer_get_string()`:: -This function is used to retrieve a `NULL`-terminated string. -This string is created from the source using -xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_stream_dialer_get_uint64()`:: -This function is used to retrieve a 64-bit unsigned value. -This is typically used for identifiers, network -numbers, and similar options. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option is not supported. -`NNG_EWRITEONLY`:: The option may not read. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_set - set option on byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_free - free byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_get - get option from byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener - byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_accept - accept incoming byte stream connection - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_alloc - allocate byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_close - close byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions - -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_free - free byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_get - get option from byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_listen - bind listener to configured address - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_set - set option on byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_recv - receive from byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_send - send to byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_set - set option on byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_set(nng_stream *s, const char *name, const void *data, size_t size); - -int nng_stream_set_bool(nng_stream *s, const char *opt, bool val); - -int nng_stream_set_int(nng_stream *s, const char *opt, int val); - -int nng_stream_set_ms(nng_stream *s, const char *opt, nng_duration val); - -int nng_stream_set_ptr(nng_stream *s, const char *opt, void *val); - -int nng_stream_set_size(nng_stream *s, const char *opt, size_t val); - -int nng_stream_set_string(nng_stream *s, const char *opt, const char *val); - -int nng_stream_set_uint64(nng_stream *s, const char *opt, uint64_t val); - -int nng_stream_set_addr(nng_stream *s, const char *opt, const nng_sockaddr *val); - ----- - -== DESCRIPTION - -The `nng_stream_set()` functions are used to configure options for the -xref:nng_stream.5.adoc[byte stream] _s_. -The actual options that may be configured in this way vary, and are -specified by _opt_. -A number of them are documented in -xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific and protocol-specific options are -documented with the transports and protocols themselves. - -=== Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_stream_set()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _size_ is the -size of the objected located at _val_. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_stream_set_bool()`:: -This function is for options which take a Boolean (`bool`). - -`nng_stream_set_int()`:: -This function is for options which take an integer (`int`). - -`nng_stream_set_ms()`:: -This function is used to configure time durations (such as timeouts) using -the type -xref:nng_duration.5.adoc[`nng_duration`]. -The duration is an integer number of milliseconds. - -`nng_stream_set_ptr()`:: -This function is used to pass a pointer to structured data. -The data referenced by is generally managed by other functions. -For example, TLS configuration objects created with -xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`] -can be passed this way. -+ -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. -Please see the documentation for the specific option for further details. - -`nng_stream_set_size()`:: -This function is used to configure a size, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_stream_set_string()`:: -This function is used to pass configure a string. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_stream_set_uint64()`:: -This function is used to configure a 64-bit unsigned value/ -This is typically used for identifiers, network numbers, -and similar options. - -`nng_stream_set_addr()`:: -This function is used to configure a -xref:nng_sockaddr.5.adoc[socket address]. -The value is copied, and thus the caller may discard the supplied -value immediately after this function returns. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option is not supported. -`NNG_EREADONLY`:: The option may not be modified. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_get.3str.adoc[nng_stream_get(3str)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], -xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], -xref:nng_tls_options.5.adoc[nng_tls_options(5)], -xref:nng_stream.5.adoc[nng_stream(5)] \ 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 + +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 + +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 + +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 + +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 + +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 + +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/ref/str/nng_stream_dialer_get.adoc b/docs/ref/str/nng_stream_dialer_get.adoc new file mode 100644 index 00000000..5bc98540 --- /dev/null +++ b/docs/ref/str/nng_stream_dialer_get.adoc @@ -0,0 +1,113 @@ +## nng_stream_dialer_get + +Get option from byte stream dialer. + +### Synopsis + +```c +#include + +int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); + +int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); +int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); +int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); +int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); +int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); +int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); +int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); +int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); +``` + +### Description + + +The `nng_stream_dialer_get` functions are used to retrieve option values for the +xref:nng_stream_dialer.adoc[byte stream dialer] _d_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in xref:../options/index.adoc[Options] and additional linked documents. + +#### Forms + +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. + +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 +_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_dialer_get_bool`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_get_int`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_get_ms`:: +This function is used to retrieve time 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`:: +This function is used to retrieve a pointer to structured data. +The data referenced is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. ++ +NOTE: Care must be taken to ensure that the application respects any +considerations about the lifetime of the underlying object. +See the documentation for the option for more specific guidance. + +`nng_stream_dialer_get_size`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_dialer_get_addr`:: +This function is used to retrieve a +xref:../opts/nng_sockaddr.adoc[socket address]. + +`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`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network numbers, and similar options. + +### Return Values + +These functions return 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ECLOSED`:: The dialer is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +### See Also + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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] -- cgit v1.2.3-70-g09d2