diff options
| -rw-r--r-- | docs/man/CMakeLists.txt | 3 | ||||
| -rw-r--r-- | docs/man/libnng.3.adoc | 3 | ||||
| -rw-r--r-- | docs/man/nng_getopt.3.adoc | 142 | ||||
| -rw-r--r-- | docs/man/nng_pipe_notify.3.adoc | 2 | ||||
| -rw-r--r-- | docs/man/nng_setopt.3.adoc | 125 | ||||
| -rw-r--r-- | docs/man/nng_socket.5.adoc | 4 | ||||
| -rw-r--r-- | docs/man/nng_sub.7.adoc | 4 | ||||
| -rw-r--r-- | docs/man/nng_tcp_options.5.adoc | 6 | ||||
| -rw-r--r-- | include/nng/nng.h | 33 | ||||
| -rw-r--r-- | src/nng_legacy.c | 100 |
10 files changed, 7 insertions, 415 deletions
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index bdb16b27..e25ab977 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -99,7 +99,6 @@ if (NNG_ENABLE_DOC) nng_dialer_set nng_dialer_start nng_free - nng_getopt nng_listen nng_listener_close nng_listener_create @@ -152,7 +151,7 @@ if (NNG_ENABLE_DOC) nng_send nng_send_aio nng_sendmsg - nng_setopt + nng_set nng_sleep_aio nng_socket_id nng_socket_get diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index cc86cde6..8b893cae 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -46,11 +46,10 @@ The following functions operate on sockets. |=== |xref:nng_close.3.adoc[nng_close()]|close socket |xref:nng_dial.3.adoc[nng_dial()]|create and start dialer -|xref:nng_getopt.3.adoc[nng_getopt()]|get socket option +|xref:nng_get.3.adoc[nng_get()]|get socket option |xref:nng_listen.3.adoc[nng_listen()]|create and start listener |xref:nng_recv.3.adoc[nng_recv()]|receive data |xref:nng_send.3.adoc[nng_send()]|send data -|xref:nng_setopt.3.adoc[nng_setopt()]|set socket option |xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option |xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier |xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc deleted file mode 100644 index 9b61fc5f..00000000 --- a/docs/man/nng_getopt.3.adoc +++ /dev/null @@ -1,142 +0,0 @@ -= nng_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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_getopt - get socket option - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); - -int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp); - -int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); - -int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); - -int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); - -int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); - -int nng_getopt_string(nng_socket s, const char *opt, char **strp); - -int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_get.3.adoc[nng_socket_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_getopt()` functions are used to retrieve option values for -the xref:nng_socket.5.adoc[socket] _s_. -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)]. - -Additionally transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the socket _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_getopt()`:: -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 -_valszp_. -+ -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 _valszp_. -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 _valszp_ does not exceed the original buffer size. -+ -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. - -`nng_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ 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_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_getopt_string()`:: -This function is used to retrieve a string into _strp_. -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_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc index e351129e..cd7250f7 100644 --- a/docs/man/nng_pipe_notify.3.adoc +++ b/docs/man/nng_pipe_notify.3.adoc @@ -87,7 +87,7 @@ This function returns 0 on success, and non-zero otherwise. [.text-left] xref:nng_pipe_close.3.adoc[nng_pipe_close(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], xref:nng_pipe.5.adoc[nng_pipe(5)], xref:nng_socket.5.adoc[nng_socket(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc deleted file mode 100644 index aa65a638..00000000 --- a/docs/man/nng_setopt.3.adoc +++ /dev/null @@ -1,125 +0,0 @@ -= nng_setopt(3) - -// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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_setopt - set socket option - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -int nng_setopt(nng_socket s, const char *opt, const void *val, size_t valsz); - -int nng_setopt_bool(nng_socket s, const char *opt, bool bval); - -int nng_setopt_int(nng_socket s, const char *opt, int ival); - -int nng_setopt_ms(nng_socket s, const char *opt, nng_duration dur); - -int nng_setopt_ptr(nng_socket s, const char *opt, void *ptr); - -int nng_setopt_size(nng_socket s, const char *opt, size_t z); - -int nng_setopt_string(nng_socket s, const char *opt, const char *str); - -int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_set.3.adoc[nng_socket_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_setopt()` functions are used to configure options for -the socket _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_setopt()`:: -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. - -`nng_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_setopt_string()`:: -This function is used to pass configure a string, _str_. -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_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 5c565720..c80a4dcd 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -62,9 +62,9 @@ nng_socket s = NNG_SOCKET_INITIALIZER; [.text-left] xref:libnng.3.adoc[libnng(3)], xref:nng_close.3.adoc[nng_close(3)], -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_socket_get.3.adoc[nng_socket_get(3)], xref:nng_socket_id.3.adoc[nng_socket_id(3)], +xref:nng_socket_set.3.adoc[nng_socket_set(3)], xref:nng_dialer.5.adoc[nng_dialer(5)], xref:nng_listener.5.adoc[nng_listener(5)], xref:nng_options.5.adoc[nng_options(5)], diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc index a96c1217..b362c656 100644 --- a/docs/man/nng_sub.7.adoc +++ b/docs/man/nng_sub.7.adoc @@ -66,10 +66,10 @@ The following protocol-specific options are available. discarded. + NOTE: This option is a byte array. Thus if you use -xref:nng_setopt.3.adoc[`nng_setopt_string()`] the `NUL` terminator byte will +xref:nng_socket_set.3.adoc[`nng_socket_set_string()`] the `NUL` terminator byte will be included in the topic. If that isn't desired, consider using -xref:nng_setopt.3.adoc[`nng_setopt()`] and using `strlen()` of the topic +xref:nng_socket_set.3.adoc[`nng_socket_set()`] and using `strlen()` of the topic as the topic size. + TIP: To receive all messages, an empty topic (zero length) can be used. diff --git a/docs/man/nng_tcp_options.5.adoc b/docs/man/nng_tcp_options.5.adoc index b8629fe5..ad5fabfd 100644 --- a/docs/man/nng_tcp_options.5.adoc +++ b/docs/man/nng_tcp_options.5.adoc @@ -112,11 +112,5 @@ when appropriate for the context: == SEE ALSO [.text-left] -xref:nng_tcp_dialer_getopt.3tcp.adoc[nng_tcp_dialer_getopt(3tcp)], -xref:nng_tcp_dialer_setopt.3tcp.adoc[nng_tcp_dialer_setopt(3tcp)], -xref:nng_tcp_getopt.3tcp.adoc[nng_tcp_getopt(3tcp)], -xref:nng_tcp_listener_getopt.3tcp.adoc[nng_tcp_listener_getopt(3tcp)], -xref:nng_tcp_listener_setopt.3tcp.adoc[nng_tcp_listener_setopt(3tcp)], -xref:nng_tcp_setopt.3tcp.adoc[nng_tcp_setopt(3tcp)], xref:nng_options.5.adoc[nng_options(5)] xref:nng.7.adoc[nng(7)] diff --git a/include/nng/nng.h b/include/nng/nng.h index b1f31ca3..17965010 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1296,39 +1296,6 @@ NNG_DECL void nng_udp_recv(nng_udp *udp, nng_aio *aio); NNG_DECL int nng_udp_multicast_membership( nng_udp *udp, nng_sockaddr *sa, bool join); -#ifndef NNG_ELIDE_DEPRECATED -// These are legacy APIs that have been deprecated. -// Their use is strongly discouraged. - -// Socket options. Use nng_socket_get and nng_socket_set instead. -NNG_DECL int nng_getopt( - nng_socket, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_bool(nng_socket, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_int(nng_socket, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_ms( - nng_socket, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_size( - nng_socket, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_uint64( - nng_socket, const char *, uint64_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_ptr(nng_socket, const char *, void **) NNG_DEPRECATED; -NNG_DECL int nng_getopt_string( - nng_socket, const char *, char **) NNG_DEPRECATED; -NNG_DECL int nng_setopt( - nng_socket, const char *, const void *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_bool(nng_socket, const char *, bool) NNG_DEPRECATED; -NNG_DECL int nng_setopt_int(nng_socket, const char *, int) NNG_DEPRECATED; -NNG_DECL int nng_setopt_ms( - nng_socket, const char *, nng_duration) NNG_DEPRECATED; -NNG_DECL int nng_setopt_size(nng_socket, const char *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_uint64( - nng_socket, const char *, uint64_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_string( - nng_socket, const char *, const char *) NNG_DEPRECATED; -NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *) NNG_DEPRECATED; - -#endif // NNG_ELIDE_DEPRECATED - // nng_init_parameter is used by applications to change a tunable setting. // This function must be called before any other NNG function for the setting // to have any effect. This function is also not thread-safe! diff --git a/src/nng_legacy.c b/src/nng_legacy.c index 833c35d5..83a5f668 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -10,104 +10,4 @@ #ifndef NNG_ELIDE_DEPRECATED #include "core/nng_impl.h" -// These are legacy APIs that we would prefer nobody used. -// Eventually they will likely be removed. For now we have -// to continue to provide them for compatibility. - -int -nng_getopt(nng_socket id, const char *n, void *v, size_t *sz) -{ - return (nng_socket_get(id, n, v, sz)); -} - -int -nng_getopt_int(nng_socket id, const char *n, int *v) -{ - return (nng_socket_get_int(id, n, v)); -} - -int -nng_getopt_uint64(nng_socket id, const char *n, uint64_t *v) -{ - return (nng_socket_get_uint64(id, n, v)); -} - -int -nng_getopt_bool(nng_socket id, const char *n, bool *v) -{ - return (nng_socket_get_bool(id, n, v)); -} - -int -nng_getopt_size(nng_socket id, const char *n, size_t *v) -{ - return (nng_socket_get_size(id, n, v)); -} - -int -nng_getopt_ms(nng_socket id, const char *n, nng_duration *v) -{ - return (nng_socket_get_ms(id, n, v)); -} - -int -nng_getopt_ptr(nng_socket id, const char *n, void **v) -{ - return (nng_socket_get_ptr(id, n, v)); -} - -int -nng_getopt_string(nng_socket id, const char *n, char **v) -{ - return (nng_socket_get_string(id, n, v)); -} - -int -nng_setopt(nng_socket id, const char *name, const void *v, size_t sz) -{ - return (nng_socket_set(id, name, v, sz)); -} - -int -nng_setopt_bool(nng_socket id, const char *n, bool v) -{ - return (nng_socket_set_bool(id, n, v)); -} - -int -nng_setopt_int(nng_socket id, const char *n, int v) -{ - return (nng_socket_set_int(id, n, v)); -} - -int -nng_setopt_ms(nng_socket id, const char *n, nng_duration v) -{ - return (nng_socket_set_ms(id, n, v)); -} - -int -nng_setopt_size(nng_socket id, const char *n, size_t v) -{ - return (nng_socket_set_size(id, n, v)); -} - -int -nng_setopt_uint64(nng_socket id, const char *n, uint64_t v) -{ - return (nng_socket_set_uint64(id, n, v)); -} - -int -nng_setopt_string(nng_socket id, const char *n, const char *v) -{ - return (nng_socket_set_string(id, n, v)); -} - -int -nng_setopt_ptr(nng_socket id, const char *n, void *v) -{ - return (nng_socket_set_ptr(id, n, v)); -} - #endif // NNG_ELIDE_DEPRECATED |