Functions
NATS_EXTERN natsStatus	natsOptions_Create (natsOptions **newOpts)
	Creates a natsOptions object.

NATS_EXTERN natsStatus	natsOptions_SetURL (natsOptions opts, const char url)
	Sets the URL to connect to.

NATS_EXTERN natsStatus	natsOptions_SetServers (natsOptions opts, const char *servers, int serversCount)
	Set the list of servers to try to (re)connect to.

NATS_EXTERN natsStatus	natsOptions_SetUserInfo (natsOptions opts, const char user, const char *password)
	Sets the user name/password to use when not specified in the URL.

NATS_EXTERN natsStatus	natsOptions_SetToken (natsOptions opts, const char token)
	Sets the token to use when not specified in the URL.

NATS_EXTERN natsStatus	natsOptions_SetTokenHandler (natsOptions opts, natsTokenHandler tokenCb, void closure)
	Sets the tokenCb to use whenever a token is needed.

NATS_EXTERN natsStatus	natsOptions_SetNoRandomize (natsOptions *opts, bool noRandomize)
	Indicate if the servers list should be randomized.

NATS_EXTERN natsStatus	natsOptions_SetTimeout (natsOptions *opts, int64_t timeout)
	Sets the (re)connect process timeout.

NATS_EXTERN natsStatus	natsOptions_SetName (natsOptions opts, const char name)
	Sets the name.

NATS_EXTERN natsStatus	natsOptions_SetSecure (natsOptions *opts, bool secure)
	Sets the secure mode.

NATS_EXTERN natsStatus	natsOptions_LoadCATrustedCertificates (natsOptions opts, const char fileName)
	Loads the trusted CA certificates from a file.

NATS_EXTERN natsStatus	natsOptions_SetCATrustedCertificates (natsOptions opts, const char certificates)
	Sets the trusted CA certificates from memory.

NATS_EXTERN natsStatus	natsOptions_LoadCertificatesChain (natsOptions opts, const char certsFileName, const char *keyFileName)
	Loads the certificate chain from a file, using the given key.

NATS_EXTERN natsStatus	natsOptions_SetCertificatesChain (natsOptions opts, const char cert, const char *key)
	Sets the client certificate and key.

NATS_EXTERN natsStatus	natsOptions_SetCiphers (natsOptions opts, const char ciphers)
	Sets the list of available ciphers.

NATS_EXTERN natsStatus	natsOptions_SetCipherSuites (natsOptions opts, const char ciphers)
	Sets the list of available ciphers for TLSv1.3.

NATS_EXTERN natsStatus	natsOptions_SetExpectedHostname (natsOptions opts, const char hostname)
	Sets the server certificate's expected hostname.

NATS_EXTERN natsStatus	natsOptions_SkipServerVerification (natsOptions *opts, bool skip)
	Switch server certificate verification.

NATS_EXTERN natsStatus	natsOptions_SetVerbose (natsOptions *opts, bool verbose)
	Sets the verbose mode.

NATS_EXTERN natsStatus	natsOptions_SetPedantic (natsOptions *opts, bool pedantic)
	Sets the pedantic mode.

NATS_EXTERN natsStatus	natsOptions_SetPingInterval (natsOptions *opts, int64_t interval)
	Sets the ping interval.

NATS_EXTERN natsStatus	natsOptions_SetMaxPingsOut (natsOptions *opts, int maxPingsOut)
	Sets the limit of outstanding `PING`s without corresponding `PONG`s.

NATS_EXTERN natsStatus	natsOptions_SetIOBufSize (natsOptions *opts, int ioBufSize)
	Sets the size of the internal read/write buffers.

NATS_EXTERN natsStatus	natsOptions_SetAllowReconnect (natsOptions *opts, bool allow)
	Indicates if the connection will be allowed to reconnect.

NATS_EXTERN natsStatus	natsOptions_SetMaxReconnect (natsOptions *opts, int maxReconnect)
	Sets the maximum number of reconnect attempts.

NATS_EXTERN natsStatus	natsOptions_SetReconnectWait (natsOptions *opts, int64_t reconnectWait)
	Sets the time between reconnect attempts.

NATS_EXTERN natsStatus	natsOptions_SetReconnectJitter (natsOptions *opts, int64_t jitter, int64_t jitterTLS)
	Set the upper bound of a random delay added to reconnect wait.

NATS_EXTERN natsStatus	natsOptions_SetCustomReconnectDelay (natsOptions opts, natsCustomReconnectDelayHandler cb, void closure)
	Sets the handler to invoke when the library needs to wait before the next reconnect attempts.

NATS_EXTERN natsStatus	natsOptions_SetReconnectBufSize (natsOptions *opts, int reconnectBufSize)
	Sets the size of the backing buffer used during reconnect.

NATS_EXTERN natsStatus	natsOptions_SetMaxPendingMsgs (natsOptions *opts, int maxPending)
	Sets the maximum number of pending messages per subscription.

NATS_EXTERN natsStatus	natsOptions_SetErrorHandler (natsOptions opts, natsErrHandler errHandler, void closure)
	Sets the error handler for asynchronous events.

NATS_EXTERN natsStatus	natsOptions_SetClosedCB (natsOptions opts, natsConnectionHandler closedCb, void closure)
	Sets the callback to be invoked when a connection to a server is permanently lost.

NATS_EXTERN natsStatus	natsOptions_SetDisconnectedCB (natsOptions opts, natsConnectionHandler disconnectedCb, void closure)
	Sets the callback to be invoked when the connection to a server is lost.

NATS_EXTERN natsStatus	natsOptions_SetReconnectedCB (natsOptions opts, natsConnectionHandler reconnectedCb, void closure)
	Sets the callback to be invoked when the connection has reconnected.

NATS_EXTERN natsStatus	natsOptions_SetDiscoveredServersCB (natsOptions opts, natsConnectionHandler discoveredServersCb, void closure)
	Sets the callback to be invoked when new servers are discovered.

NATS_EXTERN natsStatus	natsOptions_SetIgnoreDiscoveredServers (natsOptions *opts, bool ignore)
	Sets if the library should ignore or not discovered servers.

NATS_EXTERN natsStatus	natsOptions_SetLameDuckModeCB (natsOptions opts, natsConnectionHandler lameDuckCb, void closure)
	Sets the callback to be invoked when server enters lame duck mode.

NATS_EXTERN natsStatus	natsOptions_SetEventLoop (natsOptions opts, void loop, natsEvLoop_Attach attachCb, natsEvLoop_ReadAddRemove readCb, natsEvLoop_WriteAddRemove writeCb, natsEvLoop_Detach detachCb)
	Sets the external event loop and associated callbacks.

NATS_EXTERN natsStatus	natsOptions_UseGlobalMessageDelivery (natsOptions *opts, bool global)
	Switch on/off the use of a central message delivery thread pool.

NATS_EXTERN natsStatus	natsOptions_IPResolutionOrder (natsOptions *opts, int order)
	Dictates the order in which host name are resolved during connect.

NATS_EXTERN natsStatus	natsOptions_SetSendAsap (natsOptions *opts, bool sendAsap)
	Sets if Publish calls should send data right away.

NATS_EXTERN natsStatus	natsOptions_UseOldRequestStyle (natsOptions *opts, bool useOldStyle)
	Switches the use of old style requests.

NATS_EXTERN natsStatus	natsOptions_SetFailRequestsOnDisconnect (natsOptions *opts, bool failRequests)
	Fails pending requests on disconnect event.

NATS_EXTERN natsStatus	natsOptions_SetNoEcho (natsOptions *opts, bool noEcho)
	Sets if connection receives its own messages.

NATS_EXTERN natsStatus	natsOptions_SetRetryOnFailedConnect (natsOptions opts, bool retry, natsConnectionHandler connectedCb, void closure)
	Indicates if initial connect failure should be retried or not.

NATS_EXTERN natsStatus	natsOptions_SetUserCredentialsCallbacks (natsOptions opts, natsUserJWTHandler ujwtCB, void ujwtClosure, natsSignatureHandler sigCB, void *sigClosure)
	Sets the callbacks to fetch user JWT and sign server's nonce.

NATS_EXTERN natsStatus	natsOptions_SetUserCredentialsFromFiles (natsOptions opts, const char userOrChainedFile, const char *seedFile)
	Sets the file(s) to use to fetch user JWT and seed required to sign nonce.

NATS_EXTERN natsStatus	natsOptions_SetUserCredentialsFromMemory (natsOptions opts, const char jwtAndSeedContent)
	Sets JWT handler and handler to sign nonce that uses seed.

NATS_EXTERN natsStatus	natsOptions_SetNKey (natsOptions opts, const char pubKey, natsSignatureHandler sigCB, void *sigClosure)
	Sets the NKey public key and signature callback.

NATS_EXTERN natsStatus	natsOptions_SetNKeyFromSeed (natsOptions opts, const char pubKey, const char *seedFile)
	Sets the NKey public key and its seed file.

NATS_EXTERN natsStatus	natsOptions_SetWriteDeadline (natsOptions *opts, int64_t deadline)
	Sets the write deadline.

NATS_EXTERN natsStatus	natsOptions_DisableNoResponders (natsOptions *opts, bool disabled)
	Enable/Disable the "no responders" feature.

NATS_EXTERN natsStatus	natsOptions_SetCustomInboxPrefix (natsOptions opts, const char inboxPrefix)
	Sets a custom inbox prefix.

NATS_EXTERN natsStatus	natsOptions_SetMessageBufferPadding (natsOptions *opts, int paddingSize)
	Sets a custom padding when allocating buffer for incoming messages.

NATS_EXTERN void	natsOptions_Destroy (natsOptions *opts)
	Destroys a natsOptions object.

Detailed Description

NATS Options.

Function Documentation

◆ natsOptions_Create()

NATS_EXTERN natsStatus natsOptions_Create ( natsOptions ** newOpts )

Creates a natsOptions object. This object is used when one wants to set specific options prior to connecting to the NATS Server.

After making the appropriate natsOptions_Set calls, this object is passed to the natsConnection_Connect() call, which will clone this object. After natsConnection_Connect() returns, modifications to the options object will not affect the connection.

Note: The object needs to be destroyed when no longer needed.*

See also: natsConnection_Connect(); natsOptions_Destroy()

Parameters

newOpts the location where store the pointer to the newly created natsOptions object.

◆ natsOptions_SetURL()

NATS_EXTERN natsStatus natsOptions_SetURL	(	natsOptions *	opts,
		const char *	url )

Sets the URL of the NATS Server the client should try to connect to. The URL can contain optional user name and password.

Some valid URLS:

nats://localhost:4222
nats://user@localhost:4222
nats://user:password@localhost:4222

See also: natsOptions_SetServers; natsOptions_SetUserInfo; natsOptions_SetToken

Parameters

opts	the pointer to the natsOptions object.
url	the string representing the URL the connection should use to connect to the server.

◆ natsOptions_SetServers()

NATS_EXTERN natsStatus natsOptions_SetServers	(	natsOptions *	opts,
		const char **	servers,
		int	serversCount )

This specifies a list of servers to try to connect (or reconnect) to. Note that if you call natsOptions_SetURL() too, the actual list will contain the one from natsOptions_SetURL() and the ones specified in this call.

See also: natsOptions_SetURL; natsOptions_SetUserInfo; natsOptions_SetToken

Parameters

opts	the pointer to the natsOptions object.
servers	the array of strings representing the server URLs.
serversCount	the size of the array.

◆ natsOptions_SetUserInfo()

NATS_EXTERN natsStatus natsOptions_SetUserInfo	(	natsOptions *	opts,
		const char *	user,
		const char *	password )

Credentials are usually provided through the URL in the form: nats://foo:bar@localhost:4222.
Until now, you could specify URLs in two ways, with natsOptions_SetServers or natsConnection_ConnectTo. The client library would connect (or reconnect) only to this given list of URLs, so if any of the server in the list required authentication, you were responsible for providing the appropriate credentials in the URLs.

However, with cluster auto-discovery, the client library asynchronously receives URLs of servers in the cluster. These URLs do not contain any embedded credentials.
You need to use this function (or natsOptions_SetToken) to instruct the client library to use those credentials when connecting to a server that requires authentication and for which there is no embedded credentials in the URL.

See also: natsOptions_SetToken; natsOptions_SetURL; natsOptions_SetServers

Parameters

opts	the pointer to the natsOptions object.
user	the user name to send to the server during connect.
password	the password to send to the server during connect.

◆ natsOptions_SetToken()

NATS_EXTERN natsStatus natsOptions_SetToken	(	natsOptions *	opts,
		const char *	token )

Tokens are usually provided through the URL in the form: nats://mytoken@localhost:4222.
Until now, you could specify URLs in two ways, with natsOptions_SetServers or natsConnection_ConnectTo. The client library would connect (or reconnect) only to this given list of URLs, so if any of the server in the list required authentication, you were responsible for providing the appropriate token in the URLs.

However, with cluster auto-discovery, the client library asynchronously receives URLs of servers in the cluster. These URLs do not contain any embedded tokens.
You need to use this function (or natsOptions_SetUserInfo) to instruct the client library to use this token when connecting to a server that requires authentication and for which there is no embedded token in the URL.

See also: natsOptions_SetUserInfo; natsOptions_SetURL; natsOptions_SetServers

Parameters

opts	the pointer to the natsOptions object.
token	the token to send to the server during connect.

◆ natsOptions_SetTokenHandler()

NATS_EXTERN natsStatus natsOptions_SetTokenHandler	(	natsOptions *	opts,
		natsTokenHandler	tokenCb,
		void *	closure )

For use cases where setting a static token through the URL
or through natsOptions_SetToken is not desirable.

This function can be used to generate a token whenever the client needs one.
Some example of use cases: expiring token, credential rotation, ...

See also: natsOptions_SetToken

Parameters

opts	the pointer to the natsOptions object.
tokenCb	the tokenCb to use to generate a token to the server during connect.
closure	a pointer to an user defined object (can be `NULL`). See the natsMsgHandler prototype.

◆ natsOptions_SetNoRandomize()

NATS_EXTERN natsStatus natsOptions_SetNoRandomize	(	natsOptions *	opts,
		bool	noRandomize )

If 'noRandomize' is true, then the list of server URLs is used in the order provided by natsOptions_SetURL() + natsOptions_SetServers(). Otherwise, the list is formed in a random order.

Parameters

opts	the pointer to the natsOptions object.
noRandomize	if `true`, the list will be used as-is.

◆ natsOptions_SetTimeout()

NATS_EXTERN natsStatus natsOptions_SetTimeout	(	natsOptions *	opts,
		int64_t	timeout )

This timeout, expressed in milliseconds, is used to interrupt a (re)connect attempt to a NATS Server. This timeout is used both for the low level TCP connect call, and for timing out the response from the server to the client's initial PING protocol.

Parameters

opts	the pointer to the natsOptions object.
timeout	the time, in milliseconds, allowed for an individual connect (or reconnect) to complete.

◆ natsOptions_SetName()

NATS_EXTERN natsStatus natsOptions_SetName	(	natsOptions *	opts,
		const char *	name )

This name is sent as part of the CONNECT protocol. There is no default name.

Parameters

opts	the pointer to the natsOptions object.
name	the name to set.

◆ natsOptions_SetSecure()

NATS_EXTERN natsStatus natsOptions_SetSecure	(	natsOptions *	opts,
		bool	secure )

Indicates to the server if the client wants a secure (SSL/TLS) connection.

The default is false.

Parameters

opts	the pointer to the natsOptions object.
secure	`true` for a secure connection, `false` otherwise.

◆ natsOptions_LoadCATrustedCertificates()

NATS_EXTERN natsStatus natsOptions_LoadCATrustedCertificates	(	natsOptions *	opts,
		const char *	fileName )

Loads the trusted CA certificates from a file.

Note that the certificates are added to a SSL context for this natsOptions object at the time of this call, so possible errors while loading the certificates will be reported now instead of when a connection is created. You can get extra information by calling nats_GetLastError.

Parameters

opts	the pointer to the natsOptions object.
fileName	the file containing the CA certificates.

◆ natsOptions_SetCATrustedCertificates()

NATS_EXTERN natsStatus natsOptions_SetCATrustedCertificates	(	natsOptions *	opts,
		const char *	certificates )

Similar to natsOptions_LoadCATrustedCertificates expect that instead of loading from file, this loads from the given memory location.

If more than one certificate need to be provided, they need to be concatenated. For instance:

const char *certs =
   "-----BEGIN CERTIFICATE-----\n"
   "MIIGjzCCBHegAwIBAgIJAKT2W9SKY7o4MA0GCSqGSIb3DQEBCwUAMIGLMQswCQYD\n"
   (...)
   "-----END CERTIFICATE-----\n"
   "-----BEGIN CERTIFICATE-----\n"
   "MIIXyz...\n"
   (...)
   "-----END CERTIFICATE-----\n"

See also: natsOptions_LoadCATrustedCertificates

Parameters

opts	the pointer to the natsOptions object.
certificates	the string containing the concatenated CA certificates.

◆ natsOptions_LoadCertificatesChain()

NATS_EXTERN natsStatus natsOptions_LoadCertificatesChain	(	natsOptions *	opts,
		const char *	certsFileName,
		const char *	keyFileName )

The certificates must be in PEM format and must be sorted starting with the subject's certificate, followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

The private key file format supported is also PEM.

See natsOptions_LoadCATrustedCertificates regarding error reports.

Parameters

opts	the pointer to the natsOptions object.
certsFileName	the file containing the client certificates.
keyFileName	the file containing the client private key.

◆ natsOptions_SetCertificatesChain()

NATS_EXTERN natsStatus natsOptions_SetCertificatesChain	(	natsOptions *	opts,
		const char *	cert,
		const char *	key )

Similar to natsOptions_LoadCertificatesChain expect that instead of loading from file, this loads from the given memory locations.

See also: natsOptions_LoadCertificatesChain()

Parameters

opts	the pointer to the natsOptions object.
cert	the memory location containing the client certificates.
key	the memory location containing the client private key.

◆ natsOptions_SetCiphers()

NATS_EXTERN natsStatus natsOptions_SetCiphers	(	natsOptions *	opts,
		const char *	ciphers )

Note: This function does not impact TLSv1.3 ciphersuites.

Sets the list of available ciphers. Check https://www.openssl.org/docs/man1.1.1/man1/ciphers.html for the proper syntax. Here is an example:

‍"-ALL:HIGH"

See natsOptions_LoadCATrustedCertificates regarding error reports.

Parameters

opts	the pointer to the natsOptions object.
ciphers	the ciphers suite.

◆ natsOptions_SetCipherSuites()

NATS_EXTERN natsStatus natsOptions_SetCipherSuites	(	natsOptions *	opts,
		const char *	ciphers )

Sets the list of available ciphers. Check https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_ciphersuites.html for the proper syntax. Here is an example:

‍"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

See natsOptions_LoadCATrustedCertificates regarding error reports.

Parameters

opts	the pointer to the natsOptions object.
ciphers	the ciphers suite.

◆ natsOptions_SetExpectedHostname()

NATS_EXTERN natsStatus natsOptions_SetExpectedHostname	(	natsOptions *	opts,
		const char *	hostname )

If set, the library will check that the hostname in the server certificate matches the given hostname. This will occur when a connection is created, not at the time of this call.

Parameters

opts	the pointer to the natsOptions object.
hostname	the expected server certificate hostname.

◆ natsOptions_SkipServerVerification()

NATS_EXTERN natsStatus natsOptions_SkipServerVerification	(	natsOptions *	opts,
		bool	skip )

By default, the server certificate is verified. You can disable the verification by passing true to this function.

Warning: This is fine for tests but use with caution since this is not secure.

Parameters

opts	the pointer to the natsOptions object.
skip	set it to `true` to disable - or skip - server certificate verification.

◆ natsOptions_SetVerbose()

NATS_EXTERN natsStatus natsOptions_SetVerbose	(	natsOptions *	opts,
		bool	verbose )

Sets the verbose mode. If true, sends are echoed by the server with an OK protocol message.

The default is false.

Parameters

opts	the pointer to the natsOptions object.
verbose	`true` for a verbose protocol, `false` otherwise.

◆ natsOptions_SetPedantic()

NATS_EXTERN natsStatus natsOptions_SetPedantic	(	natsOptions *	opts,
		bool	pedantic )

Sets the pedantic mode. If true some extra checks will be performed by the server.

The default is false

Parameters

opts	the pointer to the natsOptions object.
pedantic	`true` for a pedantic protocol, `false` otherwise.

◆ natsOptions_SetPingInterval()

NATS_EXTERN natsStatus natsOptions_SetPingInterval	(	natsOptions *	opts,
		int64_t	interval )

Interval, expressed in milliseconds, in which the client sends PING protocols to the NATS Server.

Parameters

opts	the pointer to the natsOptions object.
interval	the interval, in milliseconds, at which the connection will send `PING` protocols to the server.

◆ natsOptions_SetMaxPingsOut()

NATS_EXTERN natsStatus natsOptions_SetMaxPingsOut	(	natsOptions *	opts,
		int	maxPingsOut )

Specifies the maximum number of PINGs without corresponding PONGs (which should be received from the server) before closing the connection with the NATS_STALE_CONNECTION status. If reconnection is allowed, the client library will try to reconnect.

Parameters

opts	the pointer to the natsOptions object.
maxPingsOut	the maximum number of `PING`s without `PONG`s (positive number).

◆ natsOptions_SetIOBufSize()

NATS_EXTERN natsStatus natsOptions_SetIOBufSize	(	natsOptions *	opts,
		int	ioBufSize )

Sets the size, in bytes, of the internal read/write buffers used for reading/writing data from a socket. If not specified, or the value is 0, the library will use a default value, currently set to 32KB.

Parameters

opts	the pointer to the natsOptions object.
ioBufSize	the size, in bytes, of the internal buffer for read/write operations.

◆ natsOptions_SetAllowReconnect()

NATS_EXTERN natsStatus natsOptions_SetAllowReconnect	(	natsOptions *	opts,
		bool	allow )

Specifies whether or not the client library should try to reconnect when losing the connection to the NATS Server.

The default is true.

Parameters

opts	the pointer to the natsOptions object.
allow	`true` if the connection is allowed to reconnect, `false` otherwise.

◆ natsOptions_SetMaxReconnect()

NATS_EXTERN natsStatus natsOptions_SetMaxReconnect	(	natsOptions *	opts,
		int	maxReconnect )

Specifies the maximum number of reconnect attempts.

Parameters

opts	the pointer to the natsOptions object.
maxReconnect	the maximum number of reconnects (positive number).

◆ natsOptions_SetReconnectWait()

NATS_EXTERN natsStatus natsOptions_SetReconnectWait	(	natsOptions *	opts,
		int64_t	reconnectWait )

Specifies how long to wait between two reconnect attempts from the same server. This means that if you have a list with S1,S2 and are currently connected to S1, and get disconnected, the library will immediately attempt to connect to S2. If this fails, it will go back to S1, and this time will wait for reconnectWait milliseconds since the last attempt to connect to S1.

Parameters

opts	the pointer to the natsOptions object.
reconnectWait	the time, in milliseconds, to wait between attempts to reconnect to the same server.

◆ natsOptions_SetReconnectJitter()

NATS_EXTERN natsStatus natsOptions_SetReconnectJitter	(	natsOptions *	opts,
		int64_t	jitter,
		int64_t	jitterTLS )

After a disconnect, the library will try to reconnect to any server URLs in its list (the URLs are either provided by the user or discovered through gossip protocol).

After the library failed to reconnect to every server in the list, it will wait for reconnectWait as specified with natsOptions_SetReconnectWait(). This option adds some random jitter to the reconnect wait delay.

This will help minimize the thundering herd phenomenon. For instance, suppose a server has 1000 connections, all were created at different times, but have the same reconnect wait option. If this server suddenly stops, then all connections will detect the failure and initiate a reconnect at the same time. The issue is even greater when those connections are TLS because of the added cost of the TLS handshake.

See also: natsOptions_SetReconnectWait()

Parameters

opts	the pointer to the natsOptions object.
jitter	the jitter in milliseconds for non TLS connections.
jitterTLS	the jitter in milliseconds for TLS connections.

◆ natsOptions_SetCustomReconnectDelay()

NATS_EXTERN natsStatus natsOptions_SetCustomReconnectDelay	(	natsOptions *	opts,
		natsCustomReconnectDelayHandler	cb,
		void *	closure )

This callback is invoked after the library tried every URL in the server list and failed to reconnect. It passes to the user the current number of attempts. This function shall return the amount of time the library will sleep before attempting to reconnect again.

It is strongly recommended that this value contains some jitter to prevent all connections to attempt reconnecting at the same time.

Note: When using this approach, the reconnect wait as specified by natsOptions_SetReconnectWait() is ignored.

Parameters

opts	the pointer to the natsOptions object.
cb	the custom reconnect delay handler to invoke.
closure	a pointer to an user defined object (can be `NULL`). See the natsCustomReconnectDelayHandler prototype.

◆ natsOptions_SetReconnectBufSize()

NATS_EXTERN natsStatus natsOptions_SetReconnectBufSize	(	natsOptions *	opts,
		int	reconnectBufSize )

Sets the size, in bytes, of the backing buffer holding published data while the library is reconnecting. Once this buffer has been exhausted, publish operations will return the NATS_INSUFFICIENT_BUFFER error. If not specified, or the value is 0, the library will use a default value, currently set to 8MB.

Parameters

opts	the pointer to the natsOptions object.
reconnectBufSize	the size, in bytes, of the backing buffer for write operations during a reconnect.

◆ natsOptions_SetMaxPendingMsgs()

NATS_EXTERN natsStatus natsOptions_SetMaxPendingMsgs	(	natsOptions *	opts,
		int	maxPending )

Specifies the maximum number of inbound messages that can be buffered in the library, for each subscription, before inbound messages are dropped and NATS_SLOW_CONSUMER status is reported to the natsErrHandler callback (if one has been set).

See also: natsOptions_SetErrorHandler()

Parameters

opts	the pointer to the natsOptions object.
maxPending	the number of messages allowed to be buffered by the library before triggering a slow consumer scenario.

◆ natsOptions_SetErrorHandler()

NATS_EXTERN natsStatus natsOptions_SetErrorHandler	(	natsOptions *	opts,
		natsErrHandler	errHandler,
		void *	closure )

Specifies the callback to invoke when an asynchronous error occurs. This is used by applications having only asynchronous subscriptions that would not know otherwise that a problem with the connection occurred.

See also: natsErrHandler

Parameters

opts	the pointer to the natsOptions object.
errHandler	the error handler callback.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetClosedCB()

NATS_EXTERN natsStatus natsOptions_SetClosedCB	(	natsOptions *	opts,
		natsConnectionHandler	closedCb,
		void *	closure )

Specifies the callback to invoke when a connection is terminally closed, that is, after all reconnect attempts have failed (when reconnection is allowed).

Parameters

opts	the pointer to the natsOptions object.
closedCb	the callback to be invoked when the connection is closed.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetDisconnectedCB()

NATS_EXTERN natsStatus natsOptions_SetDisconnectedCB	(	natsOptions *	opts,
		natsConnectionHandler	disconnectedCb,
		void *	closure )

Specifies the callback to invoke when a connection to the NATS Server is lost.

Warning: Invocation of this callback is asynchronous, which means that the state of the connection may have changed when this callback is invoked.

Parameters

opts	the pointer to the natsOptions object.
disconnectedCb	the callback to be invoked when a connection to a server is lost
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetReconnectedCB()

NATS_EXTERN natsStatus natsOptions_SetReconnectedCB	(	natsOptions *	opts,
		natsConnectionHandler	reconnectedCb,
		void *	closure )

Specifies the callback to invoke when the client library has successfully reconnected to a NATS Server.

Warning: Invocation of this callback is asynchronous, which means that the state of the connection may have changed when this callback is invoked.

Parameters

opts	the pointer to the natsOptions object.
reconnectedCb	the callback to be invoked when the connection to a server has been re-established.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetDiscoveredServersCB()

NATS_EXTERN natsStatus natsOptions_SetDiscoveredServersCB	(	natsOptions *	opts,
		natsConnectionHandler	discoveredServersCb,
		void *	closure )

Specifies the callback to invoke when the client library has been notified of one or more new NATS Servers.

Warning: Invocation of this callback is asynchronous, which means that the state may have changed when this callback is invoked.

Parameters

opts	the pointer to the natsOptions object.
discoveredServersCb	the callback to be invoked when new servers have been discovered.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetIgnoreDiscoveredServers()

NATS_EXTERN natsStatus natsOptions_SetIgnoreDiscoveredServers	(	natsOptions *	opts,
		bool	ignore )

By default, when a server joins a cluster, a client is notified of the new URL and added to the list so it can be used in case of a reconnect.

The servers can be configured to disable this gossip, however, if not done at the servers level, this option allows the discovered servers to be ignored.

Parameters

opts	the pointer to the natsOptions object.
ignore	if discovered server should be ignored or not.

◆ natsOptions_SetLameDuckModeCB()

NATS_EXTERN natsStatus natsOptions_SetLameDuckModeCB	(	natsOptions *	opts,
		natsConnectionHandler	lameDuckCb,
		void *	closure )

Specifies the callback to invoke when the server notifies the connection that it entered lame duck mode, that is, going to gradually disconnect all its connections before shuting down. This is often used in deployments when upgrading NATS Servers.

Warning: Invocation of this callback is asynchronous, which means that the state may have changed when this callback is invoked.

Parameters

opts	the pointer to the natsOptions object.
lameDuckCb	the callback to be invoked when server enters lame duck mode.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetEventLoop()

NATS_EXTERN natsStatus natsOptions_SetEventLoop	(	natsOptions *	opts,
		void *	loop,
		natsEvLoop_Attach	attachCb,
		natsEvLoop_ReadAddRemove	readCb,
		natsEvLoop_WriteAddRemove	writeCb,
		natsEvLoop_Detach	detachCb )

If you want to use an external event loop, the NATS library will not create a thread to read data from the socket, and will not directly write data to the socket. Instead, the library will invoke those callbacks for various events.

Parameters

opts	the pointer to the natsOptions object.
loop	the `void*` pointer to the external event loop.
attachCb	the callback invoked after the connection is connected, or reconnected.
readCb	the callback invoked when the event library should start or stop polling for read events.
writeCb	the callback invoked when the event library should start or stop polling for write events.
detachCb	the callback invoked when a connection is closed.

◆ natsOptions_UseGlobalMessageDelivery()

NATS_EXTERN natsStatus natsOptions_UseGlobalMessageDelivery	(	natsOptions *	opts,
		bool	global )

Normally, each asynchronous subscriber that is created has its own message delivery thread. The advantage is that it reduces lock contentions, therefore improving performance.
However, if an application creates many subscribers, this is not scaling well since the process would use too many threads.

When a connection is created from a nats_Options that has enabled global message delivery, asynchronous subscribers from this connection will use a shared thread pool responsible for message delivery.

Note: The message order per subscription is still guaranteed.

See also: nats_SetMessageDeliveryPoolSize(); Environment Variables

Parameters

opts	the pointer to the natsOptions object.
global	if `true`, uses the global message delivery thread pool, otherwise, each asynchronous subscriber will create their own message delivery thread.

◆ natsOptions_IPResolutionOrder()

NATS_EXTERN natsStatus natsOptions_IPResolutionOrder	(	natsOptions *	opts,
		int	order )

The library would previously favor IPv6 addresses during the connect process.
You can now change the order, or even exclude a family of addresses, using this option. Here is the list of possible values:

Value	Meaning
46	try IPv4 first, if it fails try IPv6
64	try IPv6 first, if it fails try IPv4
4	use only IPv4
6	use only IPv6
0	any family, no specific order

Note: If this option is not set, or you specify 0 for the order, the library will use the first IP (based on the DNS configuration) for which a successful connection can be made.

Parameters

opts	the pointer to the natsOptions object.
order	a string representing the order for the IP resolution.

◆ natsOptions_SetSendAsap()

NATS_EXTERN natsStatus natsOptions_SetSendAsap	(	natsOptions *	opts,
		bool	sendAsap )

For throughput performance, the client library tries by default to buffer as much data as possible before sending it over TCP.

Setting this option to true will make Publish calls send the data right away, reducing latency, but also throughput.

A good use-case would be a connection used to solely send replies. Imagine, a requestor sending a request, waiting for the reply before sending the next request.
The replier application will send only one reply at a time (since it will not receive the next request until the requestor receives the reply).
In such case, it makes sense for the reply to be sent right away.

The alternative would be to call natsConnection_Flush(), but this call requires a round-trip with the server, which is less efficient than using this option.

Note that the Request() call already automatically sends the request as fast as possible, there is no need to set an option for that.

Parameters

opts	the pointer to the natsOptions object.
sendAsap	a boolean indicating if published data should be sent right away or be buffered.

◆ natsOptions_UseOldRequestStyle()

NATS_EXTERN natsStatus natsOptions_UseOldRequestStyle	(	natsOptions *	opts,
		bool	useOldStyle )

Setting useOldStyle to true forces the request calls to use the original behavior, which is to create a new inbox, a new subscription on that inbox and set auto-unsubscribe to 1.

Parameters

opts	the pointer to the natsOptions object.
useOldStyle	a boolean indicating if old request style should be used.

◆ natsOptions_SetFailRequestsOnDisconnect()

NATS_EXTERN natsStatus natsOptions_SetFailRequestsOnDisconnect	(	natsOptions *	opts,
		bool	failRequests )

If this option is enabled, all pending natsConnection_Request() family calls will fail with the NATS_CONNECTION_DISCONNECTED status.

Note: This does not apply to requests from connections that use the old style requests.

See also: natsOptions_UseOldRequestStyle

Parameters

opts	the pointer to the natsOptions object.
failRequests	a boolean indicating if pending requests should fail when a disconnect event occurs.

◆ natsOptions_SetNoEcho()

NATS_EXTERN natsStatus natsOptions_SetNoEcho	(	natsOptions *	opts,
		bool	noEcho )

This configures whether the server will echo back messages that are sent on this connection if there is also matching subscriptions.

Set this to true to prevent the server from sending back messages produced by this connection. The default is false, that is, messages originating from this connection will be sent by the server if the connection has matching subscriptions.

Note: This is supported on servers >= version 1.2.0. Calling natsConnection_Connect() with the option set to true to server below this version will return the NATS_NO_SERVER_SUPPORT error.

Parameters

opts	the pointer to the natsOptions object.
noEcho	a boolean indicating if sent messages can be delivered back to this connection or not.

◆ natsOptions_SetRetryOnFailedConnect()

NATS_EXTERN natsStatus natsOptions_SetRetryOnFailedConnect	(	natsOptions *	opts,
		bool	retry,
		natsConnectionHandler	connectedCb,
		void *	closure )

By default, natsConnection_Connect() attempts to connect to a server specified in provided list of servers. If it cannot connect and the list has been fully tried, the function returns an error.

This option is used to changed this default behavior.

If retry is set to true and connection cannot be established right away, the library will attempt to connect based on the reconnect attempts and delay settings.

Note: The connect retry logic uses reconnect settings even if natsOptions_SetAllowReconnect() has been set to false. In other words, a failed connect may be retried even though a reconnect will not be allowed should the connection to the server be lost after initial connect.

The behavior will then depend on the value of the connectedCb parameter:

If NULL, then the call blocks until it can connect or exhausts the reconnect attempts.
If not NULL, and no connection can be immediately established, the natsConnection_Connect() calls returns NATS_NOT_YET_CONNECTED to indicate that no connection is currently established, but will try asynchronously to connect using the reconnect attempts/delay settings. If the connection is later established, the specified callback will be invoked. If no connection can be made and the retry attempts are exhausted, the callback registered with natsOptions_SetClosedCB(), if any, will be invoked.

Note: If natsConnection_Connect() returns NATS_OK (that is, a connection to a NATS Server was established in that call), then the connectedCb callback will not be invoked.

If retry is set to false, natsConnection_Connect() behaves as originally designed, that is, returns an error and no connection object if failing to connect to any server in the list.

Note: The connectedCb parameter is ignored and set to NULL in the options object when retry is set to false.

See also: natsOptions_SetMaxReconnect(); natsOptions_SetReconnectWait(); natsOptions_SetClosedCB()

Parameters

opts	the pointer to the natsOptions object.
retry	a boolean indicating if a failed connect should be retried.
connectedCb	if `retry` is true and this is not `NULL`, then the connect may be asynchronous and this callback will be invoked if the connect succeeds.
closure	a pointer to an user object that will be passed to the callback. `closure` can be `NULL`.

◆ natsOptions_SetUserCredentialsCallbacks()

NATS_EXTERN natsStatus natsOptions_SetUserCredentialsCallbacks	(	natsOptions *	opts,
		natsUserJWTHandler	ujwtCB,
		void *	ujwtClosure,
		natsSignatureHandler	sigCB,
		void *	sigClosure )

Any time the library creates a TCP connection to the server, the server in response sends an INFO protocol. That INFO protocol, for NATS Server at v2.0.0+, may include a nonce for the client to sign.

If this option is set, the library will invoke the two handlers to fetch the user JWT and sign the server's nonce.

This is an option that will be used only by users that are able to sign using Ed25519 (public-key signature system). Most users will probably prefer the user of natsOptions_SetUserCredentialsFromFiles().

Note: natsOptions_SetUserCredentialsCallbacks() and natsOptions_SetNKey() are mutually exclusive. Calling this function will remove the NKey and replace the signature handler, that was set with natsOptions_SetNKey(), with this one.

See also: natsUserJWTHandler; natsSignatureHandler; natsOptions_SetUserCredentialsFromFiles()

Parameters

opts	the pointer to the natsOptions object.
ujwtCB	the callback to invoke to fetch the user JWT.
ujwtClosure	the closure that will be passed to the `ujwtCB` callback.
sigCB	the callback to invoke to sign the server nonce.
sigClosure	the closure that will be passed to the `sigCB` callback.

◆ natsOptions_SetUserCredentialsFromFiles()

NATS_EXTERN natsStatus natsOptions_SetUserCredentialsFromFiles	(	natsOptions *	opts,
		const char *	userOrChainedFile,
		const char *	seedFile )

This is a convenient option that specifies the files(s) to use to fetch the user JWT and the user seed to be used to sign the server's nonce.

The userOrChainedFile contains the user JWT token and possibly the user NKey seed. Note the format of this file:

-----BEGIN NATS USER JWT-----
...an user JWT token...
------END NATS USER JWT------
 
************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.
 
-----BEGIN USER NKEY SEED-----
SU...
------END USER NKEY SEED------

The ---BEGIN NATS USER JWT--- header is used to detect where the user JWT is in this file.

If the file does not contain the user NKey seed, then the seedFile file name must be specified and must contain the user NKey seed.

Note: natsOptions_SetUserCredentialsFromFiles() and natsOptions_SetNKey() are mutually exclusive. Calling this function will remove the NKey and replace the signature handler, that was set with natsOptions_SetNKey(), with an internal one that will handle the signature.

Parameters

opts	the pointer to the natsOptions object.
userOrChainedFile	the name of the file containing the user JWT and possibly the user NKey seed.
seedFile	the name of the file containing the user NKey seed.

◆ natsOptions_SetUserCredentialsFromMemory()

NATS_EXTERN natsStatus natsOptions_SetUserCredentialsFromMemory	(	natsOptions *	opts,
		const char *	jwtAndSeedContent )

This function acts similarly to natsOptions_SetUserCredentialsFromFiles() but reads from memory instead from a file. Also it assumes that jwtAndSeedContent contains both the JWT and NKey seed.

As for the format, see natsOptions_SetUserCredentialsFromFiles() documentation.

See also: natsOptions_SetUserCredentialsFromFiles()

Parameters

opts	the pointer to the natsOptions object.
jwtAndSeedContent	string containing user JWT and user NKey seed.

◆ natsOptions_SetNKey()

NATS_EXTERN natsStatus natsOptions_SetNKey	(	natsOptions *	opts,
		const char *	pubKey,
		natsSignatureHandler	sigCB,
		void *	sigClosure )

Any time the library creates a TCP connection to the server, the server in response sends an INFO protocol. That INFO protocol, for NATS Server at v2.0.0+, may include a nonce for the client to sign.

If this option is set, the library will add the NKey public key pubKey to the CONNECT protocol along with the server's nonce signature resulting from the invocation of the signature handler sigCB.

Note: natsOptions_SetNKey() and natsOptions_SetUserCredentialsCallbacks() or natsOptions_SetUserCredentialsFromFiles() are mutually exclusive. Calling this function will remove the user JWT callback and replace the signature handler, that was set with one of the user credentials options, with this one.

See also: natsSignatureHandler

Parameters

opts	the pointer to the natsOptions object.
pubKey	the user NKey public key.
sigCB	the callback to invoke to sign the server nonce.
sigClosure	the closure that will be passed to the `sigCB` callback.

◆ natsOptions_SetNKeyFromSeed()

NATS_EXTERN natsStatus natsOptions_SetNKeyFromSeed	(	natsOptions *	opts,
		const char *	pubKey,
		const char *	seedFile )

Any time the library creates a TCP connection to the server, the server in response sends an INFO protocol. That INFO protocol, for NATS Server at v2.0.0+, may include a nonce for the client to sign.

If this option is set, the library will add the NKey public key pubKey to the CONNECT protocol along with the server's nonce signature signed using the private key from the provided seed file. The library takes care of clearing the memory holding the private key read from the file as soon as it is no longer needed.

Note: natsOptions_SetNKeyFromSeed() and natsOptions_SetUserCredentialsCallbacks() or natsOptions_SetUserCredentialsFromFiles() are mutually exclusive. Calling this function will remove the user JWT callback and replace the signature handler, that was set with one of the user credentials options, with this one.

See also: natsSignatureHandler

Parameters

opts	the pointer to the natsOptions object.
pubKey	the user NKey public key.
seedFile	the name of the file containing the user NKey seed.

◆ natsOptions_SetWriteDeadline()

NATS_EXTERN natsStatus natsOptions_SetWriteDeadline	(	natsOptions *	opts,
		int64_t	deadline )

If this is set, the socket is set to non-blocking mode and write will have a deadline set. If the deadline is reached, the write call will return an error which will translate to publish calls, or any library call trying to send data to the server, to possibly fail.

Parameters

opts	the pointer to the natsOptions object.
deadline	the write deadline expressed in milliseconds. If set to 0, it means that there is no deadline and socket is in blocking mode.

◆ natsOptions_DisableNoResponders()

NATS_EXTERN natsStatus natsOptions_DisableNoResponders	(	natsOptions *	opts,
		bool	disabled )

By default, when a connection to a NATS Server v2.2.0+ is made, the library signals to the server that it supports the "no responders" feature, which means that if a request is made, and there are no subscriptions on the request subject (no responders), then the server sends back an empty message with the header "Status" and value "503". The request APIs capture this message and instead return a NATS_NO_RESPONDERS status, instead of waiting for the timeout to occur and return NATS_TIMEOUT.

In case where users set up their own asynchronous subscription on the reply subject and publish the request with natsConnection_PublishRequest and the like, then the message callback may be invoked with this "no responders" message, which can be checked with natsMsg_IsNoResponders.

However, if users don't want to have to deal with that, it is possible to instruct the server to disable this feature for a given connection. If that is the case, requests will behave as with pre-v2.2.0 servers, in that the request will timeout when there are no responders.

Note: This function is to disable the feature that is normally enabled by default. Passing false means that it would enable it again if you had previously disable the option. However, the feature may still be disabled when connecting to a server that does not support it.

See also: natsMsg_IsNoResponders()

Parameters

opts	the pointer to the natsOptions object.
disabled	the boolean to indicate if the feature should be disabled or not.

◆ natsOptions_SetCustomInboxPrefix()

NATS_EXTERN natsStatus natsOptions_SetCustomInboxPrefix	(	natsOptions *	opts,
		const char *	inboxPrefix )

The default inbox prefix is "_INBOX", but you can change it using this option. This can be useful when setting permissions and/or with import/exports across different accounts.

The prefix must be a valid subject and not contain any of the wildcards tokens * nor >.

To clear the custom inbox prefix, call this function with NULL or the empty string.

Parameters

opts	the pointer to the natsOptions object.
inboxPrefix	the desired inbox prefix.

◆ natsOptions_SetMessageBufferPadding()

NATS_EXTERN natsStatus natsOptions_SetMessageBufferPadding	(	natsOptions *	opts,
		int	paddingSize )

By default library allocates natsMsg with payload buffer size equal to payload size. Sometimes it can be useful to add some padding to the end of the buffer which can be tweaked using this option.

To clear the custom message buffer padding, call this function with 0. Changing this option has no effect on existing NATS connections.

Parameters

opts	the pointer to the natsOptions object.
paddingSize	the desired inbox prefix.

◆ natsOptions_Destroy()

NATS_EXTERN void natsOptions_Destroy ( natsOptions * opts )

Destroys the natsOptions object, freeing used memory. See the note in the natsOptions_Create() call.

Parameters

opts	the pointer to the natsOptions object to destroy.

Functions

Detailed Description

Function Documentation

◆ natsOptions_Create()

◆ natsOptions_SetURL()

◆ natsOptions_SetServers()

◆ natsOptions_SetUserInfo()

◆ natsOptions_SetToken()

◆ natsOptions_SetTokenHandler()

◆ natsOptions_SetNoRandomize()

◆ natsOptions_SetTimeout()

◆ natsOptions_SetName()

◆ natsOptions_SetSecure()

◆ natsOptions_LoadCATrustedCertificates()

◆ natsOptions_SetCATrustedCertificates()

◆ natsOptions_LoadCertificatesChain()

◆ natsOptions_SetCertificatesChain()

◆ natsOptions_SetCiphers()

◆ natsOptions_SetCipherSuites()

◆ natsOptions_SetExpectedHostname()

◆ natsOptions_SkipServerVerification()

◆ natsOptions_SetVerbose()

◆ natsOptions_SetPedantic()

◆ natsOptions_SetPingInterval()

◆ natsOptions_SetMaxPingsOut()

◆ natsOptions_SetIOBufSize()

◆ natsOptions_SetAllowReconnect()

◆ natsOptions_SetMaxReconnect()

◆ natsOptions_SetReconnectWait()

◆ natsOptions_SetReconnectJitter()

◆ natsOptions_SetCustomReconnectDelay()

◆ natsOptions_SetReconnectBufSize()

◆ natsOptions_SetMaxPendingMsgs()

◆ natsOptions_SetErrorHandler()

◆ natsOptions_SetClosedCB()

◆ natsOptions_SetDisconnectedCB()

◆ natsOptions_SetReconnectedCB()

◆ natsOptions_SetDiscoveredServersCB()

◆ natsOptions_SetIgnoreDiscoveredServers()

◆ natsOptions_SetLameDuckModeCB()

◆ natsOptions_SetEventLoop()

◆ natsOptions_UseGlobalMessageDelivery()

◆ natsOptions_IPResolutionOrder()

◆ natsOptions_SetSendAsap()

◆ natsOptions_UseOldRequestStyle()

◆ natsOptions_SetFailRequestsOnDisconnect()

◆ natsOptions_SetNoEcho()

◆ natsOptions_SetRetryOnFailedConnect()

◆ natsOptions_SetUserCredentialsCallbacks()

◆ natsOptions_SetUserCredentialsFromFiles()

◆ natsOptions_SetUserCredentialsFromMemory()

◆ natsOptions_SetNKey()

◆ natsOptions_SetNKeyFromSeed()

◆ natsOptions_SetWriteDeadline()

◆ natsOptions_DisableNoResponders()

◆ natsOptions_SetCustomInboxPrefix()

◆ natsOptions_SetMessageBufferPadding()

◆ natsOptions_Destroy()