From 89eb7d5c612bf80e223367e88f20d55d7fbea252 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 7 Nov 2024 23:19:23 -0800 Subject: Document a number of things as deprecated. This does not fully mark them in the headers, to avoid complicating test suites and such, for now. --- docs/man/nng_dialer_get.3.adoc | 2 +- docs/man/nng_dialer_set.3.adoc | 4 ++-- docs/man/nng_listener_set.3.adoc | 6 +++--- docs/man/nng_socket_get.3.adoc | 2 -- docs/man/nng_stream_dialer_get.3str.adoc | 6 +++--- docs/man/nng_stream_dialer_set.3str.adoc | 5 +++-- docs/man/nng_stream_listener_get.3str.adoc | 6 +++--- docs/man/nng_stream_listener_set.3str.adoc | 6 +++--- docs/man/nng_stream_set.3str.adoc | 12 +++++------- docs/man/nng_tls_options.5.adoc | 11 ++++++++--- 10 files changed, 31 insertions(+), 29 deletions(-) diff --git a/docs/man/nng_dialer_get.3.adoc b/docs/man/nng_dialer_get.3.adoc index e23ecd2c..5084c1b3 100644 --- a/docs/man/nng_dialer_get.3.adoc +++ b/docs/man/nng_dialer_get.3.adoc @@ -75,7 +75,7 @@ It is acceptable to pass `NULL` for _val_ if the value in _valszp_ 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. +NOTE: This function is deprecated. Use one of the typed functions listed below instead. `nng_dialer_get_bool()`:: This function is for options which take a Boolean (`bool`). diff --git a/docs/man/nng_dialer_set.3.adoc b/docs/man/nng_dialer_set.3.adoc index 3363eae9..1792db7c 100644 --- a/docs/man/nng_dialer_set.3.adoc +++ b/docs/man/nng_dialer_set.3.adoc @@ -19,7 +19,7 @@ nng_dialer_set - set dialer option ---- #include -int nng_dialer_set(nng_dialer d, const char *opt, const void *val, +int nng_dialer_set(nng_dialer d, const char *opt, const void *val, size_t valsz); int nng_dialer_set_bool(nng_dialer d, const char *opt, bool bval); @@ -63,7 +63,7 @@ This function is untyped, and can be used to configure any arbitrary data. The _val_ pointer addresses the data to copy, and _valsz_ is the size of the objected located at _val_. -TIP: It may be easier to use one of the typed forms of this function. +NOTE: This function is deprecated. Use of the typed functions below instead. `nng_dialer_set_bool()`:: This function is for options which take a Boolean (`bool`). diff --git a/docs/man/nng_listener_set.3.adoc b/docs/man/nng_listener_set.3.adoc index 0cfd2112..9e95b199 100644 --- a/docs/man/nng_listener_set.3.adoc +++ b/docs/man/nng_listener_set.3.adoc @@ -19,7 +19,7 @@ nng_listener_set - set listener option ---- #include -int nng_listener_set(nng_listener l, const char *opt, const void *val, +int nng_listener_set(nng_listener l, const char *opt, const void *val, size_t valsz); int nng_listener_set_bool(nng_listener l, const char *opt, bool bval); @@ -58,13 +58,13 @@ In all of these forms, the option _opt_ is configured on the listener _l_. 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_listener_set()`:: This function is untyped, and can be used to configure any arbitrary data. The _val_ pointer addresses the data to copy, and _valsz_ is the size of the objected located at _val_. +NOTE: This function is deprecated. Use one of the typed functions beelow instead. + `nng_listener_set_bool()`:: This function is for options which take a Boolean (`bool`). The _bval_ is passed to the option. diff --git a/docs/man/nng_socket_get.3.adoc b/docs/man/nng_socket_get.3.adoc index e304964a..b59956d1 100644 --- a/docs/man/nng_socket_get.3.adoc +++ b/docs/man/nng_socket_get.3.adoc @@ -35,8 +35,6 @@ int nng_socket_get_ptr(nng_socket s, const char *opt, void **ptr); int nng_socket_get_ms(nng_socket s, const char *opt, nng_duration *durp); -int nng_socket_get_addr(nng_socket s, const char *opt, nng_sockaddr *addrp); - ---- == DESCRIPTION diff --git a/docs/man/nng_stream_dialer_get.3str.adoc b/docs/man/nng_stream_dialer_get.3str.adoc index 4023e56f..03dbd534 100644 --- a/docs/man/nng_stream_dialer_get.3str.adoc +++ b/docs/man/nng_stream_dialer_get.3str.adoc @@ -1,6 +1,6 @@ = nng_stream_dialer_get(3str) // -// Copyright 2020 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -42,7 +42,7 @@ int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t == DESCRIPTION -The `nng_stream_dialer_get()` functions are used to retrieve option values for the +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. @@ -76,7 +76,7 @@ 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. +NOTE: This function is deprecated. Use one of the typed functions instead. `nng_stream_dialer_get_bool()`:: This function is for options which take a Boolean (`bool`). diff --git a/docs/man/nng_stream_dialer_set.3str.adoc b/docs/man/nng_stream_dialer_set.3str.adoc index bd4ac478..c72606d4 100644 --- a/docs/man/nng_stream_dialer_set.3str.adoc +++ b/docs/man/nng_stream_dialer_set.3str.adoc @@ -62,7 +62,8 @@ 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. +NOTE: This function is deprecated and will be removed in a future release. +Use one of the typed functions below instead. `nng_stream_dialer_set_bool()`:: This function is for options which take a Boolean (`bool`). @@ -130,4 +131,4 @@ 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 +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_listener_get.3str.adoc b/docs/man/nng_stream_listener_get.3str.adoc index 927e36a8..891e9f8c 100644 --- a/docs/man/nng_stream_listener_get.3str.adoc +++ b/docs/man/nng_stream_listener_get.3str.adoc @@ -1,6 +1,6 @@ = nng_stream_listener_get(3str) // -// Copyright 2019 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -43,7 +43,7 @@ int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint The `nng_stream_listener_get()` functions are used to retrieve option values -for the +for the xref:nng_stream_listener.5.adoc[byte stream listener] _l_. The actual options that may be retrieved in this way vary. @@ -77,7 +77,7 @@ 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. +NOTE: This function is deprecated. Use one of the typed functions below instead. `nng_stream_listener_get_bool()`:: This function is for options which take a Boolean (`bool`). diff --git a/docs/man/nng_stream_listener_set.3str.adoc b/docs/man/nng_stream_listener_set.3str.adoc index ccabe5ca..fb8708cd 100644 --- a/docs/man/nng_stream_listener_set.3str.adoc +++ b/docs/man/nng_stream_listener_set.3str.adoc @@ -1,6 +1,6 @@ = nng_stream_listener_set(3str) // -// Copyright 2020 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -62,7 +62,7 @@ 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. +NOTE: This function is deprecated. Use one of the typed forms instead. `nng_stream_listener_set_bool()`:: This function is for options which take a Boolean (`bool`). @@ -130,4 +130,4 @@ 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 +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_set.3str.adoc b/docs/man/nng_stream_set.3str.adoc index e4a82a1a..64673956 100644 --- a/docs/man/nng_stream_set.3str.adoc +++ b/docs/man/nng_stream_set.3str.adoc @@ -1,6 +1,6 @@ = nng_stream_set(3str) // -// Copyright 2020 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -62,7 +62,7 @@ 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. +NOTE: This function is deprecated. Callers should use one of the typed functions instead. `nng_stream_set_bool()`:: This function is for options which take a Boolean (`bool`). @@ -104,10 +104,8 @@ 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. +This function performs no useful function, and will be removed in +in a future release. == RETURN VALUES @@ -130,4 +128,4 @@ 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 +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_tls_options.5.adoc b/docs/man/nng_tls_options.5.adoc index a06a600f..0b346340 100644 --- a/docs/man/nng_tls_options.5.adoc +++ b/docs/man/nng_tls_options.5.adoc @@ -1,6 +1,6 @@ = nng_tls_options(5) // -// Copyright 2020 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -47,6 +47,13 @@ description of the option. === TLS Options +NOTE: Options for configuring TLS are deprecated and may +not be present in a future release. These options are +`NNG_OPT_TLS_AUTH_MODE`, `NNG_OPT_TLS_CA_FILE`, `NNG_OPT_TLS_CERT_KEY_FILE`, +and `NNG_OPT_TLS_SERVER_NAME`. Applications should switch to using the +`NNG_OPT_TLS_CONFIG` option and working with `nng_tls_config` objects. + + [[NNG_OPT_TLS_AUTH_MODE]]((`NNG_OPT_TLS_AUTH_MODE`)):: (`int`) Write-only option used to configure the authentication mode used. @@ -76,8 +83,6 @@ configuration object before returning it. NOTE: The caller should release the hold with xref:nng_tls_config_free.3tls.adoc[`nng_tls_config_free()`] when it no longer needs the TLS configuration object. -+ -TIP: Use this option when more advanced TLS configuration is required. [[NNG_OPT_TLS_SERVER_NAME]]((`NNG_OPT_TLS_SERVER_NAME`)):: (string) -- cgit v1.2.3-70-g09d2