diff options
Diffstat (limited to 'docs/nng_dialer_getopt.adoc')
| -rw-r--r-- | docs/nng_dialer_getopt.adoc | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/docs/nng_dialer_getopt.adoc b/docs/nng_dialer_getopt.adoc new file mode 100644 index 00000000..8275d46b --- /dev/null +++ b/docs/nng_dialer_getopt.adoc @@ -0,0 +1,109 @@ += nng_dialer_getopt(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_dialer_getopt - get dialer option + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); +int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); +int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); +int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); +int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t *zp); +int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); +----------- + +== DESCRIPTION + +The `nng_dialer_getopt()` functions are used to retrieve option values for +the dialer _d_. The actual options that may be retrieved in this way +vary, and are documented in the <<nng_getopt#,nng_getopt(3)>> manual. +Additionally some transport-specific options are documented with the +transports themselves. + +In all of these forms, the option _opt_ is retrieved from the dialer _d_. + +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. + +The first form of this function, `nng_dialer_getopt()`, can be used to +retrieve the value of any option. It is untyped. 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 referened 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 validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + +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. + +Generally, it will be easier to use one of the typed forms instead. Note +however that no validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed +form. + +The second form, `nng_dialer_getopt_int()`, +is for options which take an integer (or boolean). The value will +be stored at _ivalp_. For booleans the value will be eiher 0 (false) or 1 (true). + +The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and +the special value `NNG_DUR_DEFAULT` means a context-specific default.) + +The fourth form, `nng_dialer_getopt_ptr()`, 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. + +The fifth form, `nng_dialer_getopt_size()`, is used to retrieve a size +into the pointer _zp_, typically for buffer sizes, message maximum sizes, and +similar options. + +The sixth form, `nng_diale_getopt_uint64()`, 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 + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +<<nng_listen#,nng_listen(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_dialer_setopt#,nng_dialer_setopt(3)>> +<<nng_getopt#,nng_getopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright}
\ No newline at end of file |