NATS C Client with JetStream and Streaming support: Options

NATS C Client with JetStream and Streaming support 3.4.1 The nats.io C Client, Supported by Synadia Communications Inc.

Loading...
Searching...
No Matches
Functions
Options
Functions

## Functions
NATS_EXTERN natsStatus | natsOptions_Create (natsOptions **newOpts)
| Creates a natsOptions object. More...
NATS_EXTERN natsStatus | natsOptions_SetURL (natsOptions *opts, const char *url)
| Sets the URL to connect to. More...
NATS_EXTERN natsStatus | natsOptions_SetServers (natsOptions *opts, const char **servers, int serversCount)
| Set the list of servers to try to (re)connect to. More...
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. More...
NATS_EXTERN natsStatus | natsOptions_SetToken (natsOptions *opts, const char *token)
| Sets the token to use when not specified in the URL. More...
NATS_EXTERN natsStatus | natsOptions_SetTokenHandler (natsOptions *opts, natsTokenHandler tokenCb, void *closure)
| Sets the tokenCb to use whenever a token is needed. More...
NATS_EXTERN natsStatus | natsOptions_SetNoRandomize (natsOptions *opts, bool noRandomize)
| Indicate if the servers list should be randomized. More...
NATS_EXTERN natsStatus | natsOptions_SetTimeout (natsOptions *opts, int64_t timeout)
| Sets the (re)connect process timeout. More...
NATS_EXTERN natsStatus | natsOptions_SetName (natsOptions *opts, const char *name)
| Sets the name. More...
NATS_EXTERN natsStatus | natsOptions_SetSecure (natsOptions *opts, bool secure)
| Sets the secure mode. More...
NATS_EXTERN natsStatus | natsOptions_LoadCATrustedCertificates (natsOptions *opts, const char *fileName)
| Loads the trusted CA certificates from a file. More...
NATS_EXTERN natsStatus | natsOptions_SetCATrustedCertificates (natsOptions *opts, const char *certificates)
| Sets the trusted CA certificates from memory. More...
NATS_EXTERN natsStatus | natsOptions_LoadCertificatesChain (natsOptions *opts, const char *certsFileName, const char *keyFileName)
| Loads the certificate chain from a file, using the given key. More...
NATS_EXTERN natsStatus | natsOptions_SetCertificatesChain (natsOptions *opts, const char *cert, const char *key)
| Sets the client certificate and key. More...
NATS_EXTERN natsStatus | natsOptions_SetCiphers (natsOptions *opts, const char *ciphers)
| Sets the list of available ciphers. More...
NATS_EXTERN natsStatus | natsOptions_SetCipherSuites (natsOptions *opts, const char *ciphers)
| Sets the list of available ciphers for TLSv1.3. More...
NATS_EXTERN natsStatus | natsOptions_SetExpectedHostname (natsOptions *opts, const char *hostname)
| Sets the server certificate's expected hostname. More...
NATS_EXTERN natsStatus | natsOptions_SkipServerVerification (natsOptions *opts, bool skip)
| Switch server certificate verification. More...
NATS_EXTERN natsStatus | natsOptions_SetVerbose (natsOptions *opts, bool verbose)
| Sets the verbose mode. More...
NATS_EXTERN natsStatus | natsOptions_SetPedantic (natsOptions *opts, bool pedantic)
| Sets the pedantic mode. More...
NATS_EXTERN natsStatus | natsOptions_SetPingInterval (natsOptions *opts, int64_t interval)
| Sets the ping interval. More...
NATS_EXTERN natsStatus | natsOptions_SetMaxPingsOut (natsOptions *opts, int maxPingsOut)
| Sets the limit of outstanding `PING`s without corresponding `PONG`s. More...
NATS_EXTERN natsStatus | natsOptions_SetIOBufSize (natsOptions *opts, int ioBufSize)
| Sets the size of the internal read/write buffers. More...
NATS_EXTERN natsStatus | natsOptions_SetAllowReconnect (natsOptions *opts, bool allow)
| Indicates if the connection will be allowed to reconnect. More...
NATS_EXTERN natsStatus | natsOptions_SetMaxReconnect (natsOptions *opts, int maxReconnect)
| Sets the maximum number of reconnect attempts. More...
NATS_EXTERN natsStatus | natsOptions_SetReconnectWait (natsOptions *opts, int64_t reconnectWait)
| Sets the time between reconnect attempts. More...
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. More...
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. More...
NATS_EXTERN natsStatus | natsOptions_SetReconnectBufSize (natsOptions *opts, int reconnectBufSize)
| Sets the size of the backing buffer used during reconnect. More...
NATS_EXTERN natsStatus | natsOptions_SetMaxPendingMsgs (natsOptions *opts, int maxPending)
| Sets the maximum number of pending messages per subscription. More...
NATS_EXTERN natsStatus | natsOptions_SetErrorHandler (natsOptions *opts, natsErrHandler errHandler, void *closure)
| Sets the error handler for asynchronous events. More...
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. More...
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. More...
NATS_EXTERN natsStatus | natsOptions_SetReconnectedCB (natsOptions *opts, natsConnectionHandler reconnectedCb, void *closure)
| Sets the callback to be invoked when the connection has reconnected. More...
NATS_EXTERN natsStatus | natsOptions_SetDiscoveredServersCB (natsOptions *opts, natsConnectionHandler discoveredServersCb, void *closure)
| Sets the callback to be invoked when new servers are discovered. More...
NATS_EXTERN natsStatus | natsOptions_SetIgnoreDiscoveredServers (natsOptions *opts, bool ignore)
| Sets if the library should ignore or not discovered servers. More...
NATS_EXTERN natsStatus | natsOptions_SetLameDuckModeCB (natsOptions *opts, natsConnectionHandler lameDuckCb, void *closure)
| Sets the callback to be invoked when server enters lame duck mode. More...
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. More...
NATS_EXTERN natsStatus | natsOptions_UseGlobalMessageDelivery (natsOptions *opts, bool global)
| Switch on/off the use of a central message delivery thread pool. More...
NATS_EXTERN natsStatus | natsOptions_IPResolutionOrder (natsOptions *opts, int order)
| Dictates the order in which host name are resolved during connect. More...
NATS_EXTERN natsStatus | natsOptions_SetSendAsap (natsOptions *opts, bool sendAsap)
| Sets if Publish calls should send data right away. More...
NATS_EXTERN natsStatus | natsOptions_UseOldRequestStyle (natsOptions *opts, bool useOldStyle)
| Switches the use of old style requests. More...
NATS_EXTERN natsStatus | natsOptions_SetFailRequestsOnDisconnect (natsOptions *opts, bool failRequests)
| Fails pending requests on disconnect event. More...
NATS_EXTERN natsStatus | natsOptions_SetNoEcho (natsOptions *opts, bool noEcho)
| Sets if connection receives its own messages. More...
NATS_EXTERN natsStatus | natsOptions_SetRetryOnFailedConnect (natsOptions *opts, bool retry, natsConnectionHandler connectedCb, void *closure)
| Indicates if initial connect failure should be retried or not. More...
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. More...
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. More...
NATS_EXTERN natsStatus | natsOptions_SetNKey (natsOptions *opts, const char *pubKey, natsSignatureHandler sigCB, void *sigClosure)
| Sets the NKey public key and signature callback. More...
NATS_EXTERN natsStatus | natsOptions_SetNKeyFromSeed (natsOptions *opts, const char *pubKey, const char *seedFile)
| Sets the NKey public key and its seed file. More...
NATS_EXTERN natsStatus | natsOptions_SetWriteDeadline (natsOptions *opts, int64_t deadline)
| Sets the write deadline. More...
NATS_EXTERN natsStatus | natsOptions_DisableNoResponders (natsOptions *opts, bool disabled)
| Enable/Disable the "no responders" feature. More...
NATS_EXTERN natsStatus | natsOptions_SetCustomInboxPrefix (natsOptions *opts, const char *inboxPrefix)
| Sets a custom inbox prefix. More...
NATS_EXTERN void | natsOptions_Destroy (natsOptions *opts)
| Destroys a natsOptions object. More...

## 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 `PING`s without corresponding `PONG`s (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_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_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.