SYNOPSIS
#include <nng/nng.h>
#define NNG_OPT_SOCKNAME "socket-name"
#define NNG_OPT_RAW "raw"
#define NNG_OPT_PROTO "protocol"
#define NNG_OPT_PROTONAME "protocol-name"
#define NNG_OPT_PEER "peer"
#define NNG_OPT_PEERNAME "peer-name"
#define NNG_OPT_RECVBUF "recv-buffer"
#define NNG_OPT_SENDBUF "send-buffer"
#define NNG_OPT_RECVFD "recv-fd"
#define NNG_OPT_SENDFD "send-fd"
#define NNG_OPT_RECVTIMEO "recv-timeout"
#define NNG_OPT_SENDTIMEO "send-timeout"
#define NNG_OPT_LOCADDR "local-address"
#define NNG_OPT_REMADDR "remote-address"
#define NNG_OPT_URL "url"
#define NNG_OPT_MAXTTL "ttl-max"
#define NNG_OPT_RECVMAXSZ "recv-size-max"
#define NNG_OPT_RECONNMINT "reconnect-time-min"
#define NNG_OPT_RECONNMAXT "reconnect-time-max"
#define NNG_OPT_TCP_NODELAY "tcp-nodelay"
#define NNG_OPT_TCP_KEEPALIVE "tcp-keepalive"DESCRIPTION
This page documents the various standard options that can be set or retrieved on objects in the nng library.
Sockets (nng_socket objects) use the functions
nng_getopt()
and nng_setopt() to set and retrieve option values.
Dialers (nng_dialer objects) use the functions
nng_dialer_getopt() and
nng_dialer_setopt() to set and retrieve option
values.
Listeners (nng_listener objects) use the functions
nng_listener_getopt()
and nng_listener_setopt() to set and
retrieve option values.
Pipes (nng_pipe objects) can only retrieve option values using
the nng_pipe_getopt() function.
In addition to the options listed here, transports and protocols will generally have some of their own options, which will be documented with the transport or protocol.
Options
In the following list of options, the name of the option is supplied, along with the data type of the underlying value. Some options are only meaningful or supported in certain contexts; for example there is no single meaningful address for a socket, since sockets can have multiple dialers and endpoints associated with them. An attempt has been made to include details about such restrictions in the description of the option.
NNG_OPT_LOCADDR-
(
nng_sockaddr) This read-only option may be used on listeners, dialers and connected pipes, and represents the local address used for communication. Not all transports support this option, and some transports may support it listeners but not dialers.
NNG_OPT_RAW-
(
bool) This read-only option indicates whether the socket is in “raw” mode. Iftrue, the socket is in “raw” mode, and iffalsethe socket is in “cooked” mode. Raw mode sockets generally do not have any protocol-specific semantics applied to them; instead the application is expected to perform such semantics itself. (For example, in “cooked” mode a rep socket would automatically copy message headers from a received message to the corresponding reply, whereas in “raw” mode this is not done.) See Raw Mode for more details.
NNG_OPT_RECONNMINT-
(
nng_duration) This is the minimum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners.
NNG_OPT_RECONNMAXT-
(
nng_duration) This is the maximum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. If this is non-zero, then the time between successive connection attempts will start at the value ofNNG_OPT_RECONNMINT, and grow exponentially, until it reaches this value. If this value is zero, then no exponential back-off between connection attempts is done, and each attempt will wait the time specified byNNG_OPT_RECONNMINT. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners.
NNG_OPT_RECVBUF-
(
int) This is the depth of the socket’s receive buffer as a number of messages. Messages received by a transport may be buffered until the application has accepted them for delivery.
NNG_OPT_RECVFD-
(
int) This read-only option is used to obtain an integer file descriptor suitable for use withpoll(),select(), (or on Windows systemsWSAPoll()) and similar functions. This descriptor will be readable when a message is available for receiving on the socket. When no message is ready for receiving, then this file descriptor will not be readable.
| Applications should never attempt to read or write to the returned file descriptor. |
While this option may help applications integrate into existing polling
loops, it is more efficient, and often easier, to use the asynchronous I/O
objects instead.
See nng_aio_alloc().
|
NNG_OPT_RECVMAXSZ-
(
size_t) This is the maximum message size that the will be accepted from a remote peer. If a peer attempts to send a message larger than this, then the message will be discarded. If the value of this is zero, then no limit on message sizes is enforced. This option exists to prevent certain kinds of denial-of-service attacks, where a malicious agent can claim to want to send an extraordinarily large message, without sending any data. This option can be set for the socket, but may be overridden for on a per-dialer or per-listener basis.
| Some transports may have further message size restrictions! |
NNG_OPT_RECVTIMEO-
(
nng_duration) This is the socket receive timeout in milliseconds. When no message is available for receiving at the socket for this period of time, receive operations will fail with a return value ofNNG_ETIMEDOUT.
NNG_OPT_REMADDR-
(
nng_sockaddr) This read-only option may be used on dialers and connected pipes, and represents the address of a remote peer. Not all transports support this option.
NNG_OPT_SENDBUF-
(
int) This is the depth of the socket send buffer as a number of messages. Messages sent by an application may be buffered by the socket until a transport is ready to accept them for delivery. This value must be an integer between 0 and 8192, inclusive.
| Not all protocols support buffering sent messages; generally multicast protocols like pub will simply discard messages when they cannot be delivered immediately. |
NNG_OPT_SENDFD-
(
int) This read-only option is used to obtain an integer file descriptor suitable for use withpoll(),select(), (or on Windows systemsWSAPoll()) and similar functions. This descriptor will be readable when the socket is able to accept a message for sending without blocking. When the socket is no longer able to accept such messages without blocking, the descriptor will not be readable.
| Applications should never attempt to read or write to the returned file descriptor. |
While this option may help applications integrate into existing polling
loops, it is more efficient, and often easier, to use the asynchronous I/O
objects instead.
See nng_aio_alloc().
|
NNG_OPT_SENDTIMEO-
(
nng_duration) This is the socket send timeout in milliseconds. When a message cannot be queued for delivery by the socket for this period of time (such as if send buffers are full), the operation will fail with a return value ofNNG_ETIMEDOUT.
NNG_OPT_SOCKNAME-
(string) This the socket name. By default this is a string corresponding to the value of the socket. The string must fit within 64-bytes, including the terminating
NULbyte, but it can be changed for other application uses.
NNG_OPT_MAXTTL-
(
int) This is the maximum number of “hops” a message may traverse (seenng_device()). The intention here is to prevent forwarding loops in device chains. When this is supported, it can have a value between 1 and 255, inclusive.
| Not all protocols support this option. Those that do generally have a default value of 8. |
| Each node along a forwarding path may have it’s own value for the maximum time-to-live, and performs its own checks before forwarding a message. Therefore it is helpful if all nodes in the topology use the same value for this option. |
NNG_OPT_URL-
(string) This read-only option is used to obtain the URL with which a listener or dialer was configured. Accordingly it can only be used with dialers, listeners, and pipes.
| Some transports will canonify URLs before returning them to the application. |
NNG_OPT_PROTO-
(
int) This read-only option is used to obtain the 16-bit number for the socket’s protocol.
NNG_OPT_PEER-
(
int) This read-only option is used to obtain the 16-bit number of the peer protocol for the socket.
NNG_OPT_PROTONAME-
(string) This read-only option is used to obtain the name of the socket’s protocol.
NNG_OPT_PEERNAME-
(string) This read-only option is used to obtain the name of the peer protocol for the socket.
NNG_OPT_TCP_NODELAY-
(
bool) This option is used to disable (or enable) the use of Nagle’s algorithm for TCP connections. Whentrue(the default), messages are sent immediately by the underlying TCP stream without waiting to gather more data. Whenfalse, Nagle’s algorithm is enabled, and the TCP stream may wait briefly in attempt to coalesce messages. Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, but it comes at a cost to latency.
| This setting may apply to transports that are built on top of TCP. See the transport documentation for each transport for details. |
NNG_OPT_TCP_KEEPALIVE-
(
bool) This option is used to enable the sending of keep-alive messages on the underlying TCP stream. This option isfalseby default. When enabled, if no messages are seen for a period of time, then a zero length TCP message is sent with the ACK flag set in an attempt to tickle some traffic from the peer. If none is still seen (after some platform-specific number of retries and timeouts), then the remote peer is presumed dead, and the connection is closed.
| This setting may apply to transports that are built on top of TCP. See the transport documentation for each transport for details. |
| This option has two purposes. First, it can be used to detect dead peers on an otherwise quiescent network. Second, it can be used to keep connection table entries in NAT and other middleware from being expiring due to lack of activity. |