Streaming Connection Options

Functions
NATS_EXTERN natsStatus	stanConnOptions_Create (stanConnOptions **newOpts)
	Creates a stanConnOptions object.
NATS_EXTERN natsStatus	stanConnOptions_SetURL (stanConnOptions *opts, const char *url)
	Sets the URL to connect to.
NATS_EXTERN natsStatus	stanConnOptions_SetNATSOptions (stanConnOptions *opts, natsOptions *nOpts)
	Sets the NATS Options to use to create the connection.
NATS_EXTERN natsStatus	stanConnOptions_SetConnectionWait (stanConnOptions *opts, int64_t wait)
	Sets the timeout for establishing a connection.
NATS_EXTERN natsStatus	stanConnOptions_SetPubAckWait (stanConnOptions *opts, int64_t wait)
	Sets the timeout for waiting for an ACK for a published message.
NATS_EXTERN natsStatus	stanConnOptions_SetDiscoveryPrefix (stanConnOptions *opts, const char *prefix)
	Sets the subject prefix the library sends the connect request to.
NATS_EXTERN natsStatus	stanConnOptions_SetMaxPubAcksInflight (stanConnOptions *opts, int maxPubAcksInflight, float percentage)
	Sets the maximum number of published messages without outstanding ACKs from the server.
NATS_EXTERN natsStatus	stanConnOptions_SetPings (stanConnOptions *opts, int interval, int maxOut)
	Sets the ping interval and max out values.
NATS_EXTERN natsStatus	stanConnOptions_SetConnectionLostHandler (stanConnOptions *opts, stanConnectionLostHandler handler, void *closure)
	Sets the connection lost handler.
NATS_EXTERN void	stanConnOptions_Destroy (stanConnOptions *opts)
	Destroys a stanConnOptions object.

Detailed Description

NATS Streaming Connection Options.

Function Documentation

stanConnOptions_Create()

NATS_EXTERN natsStatus stanConnOptions_Create

(

stanConnOptions **

newOpts

)

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

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

The default options set in this call are: url: nats://localhost:4222 connection wait: 2 seconds publish ack wait: 30 seconds discovery prefix: _STAN.discovery maximum publish acks inflight and percentage: 16384, 50% ping interval: 5 seconds max ping out without response: 3

Note

The object needs to be destroyed when no longer needed.

See also

stanConnection_Connect()

stanConnOptions_Destroy()

Parameters

newOpts

the location where store the pointer to the newly created stanConnOptions object.

stanConnOptions_SetURL()

NATS_EXTERN natsStatus stanConnOptions_SetURL	(	stanConnOptions *	opts,
		const char *	url )

Sets the URL of the NATS Streaming Server the client should try to connect to. The URL can contain optional user name and password. You can provide a comma separated list of URLs too.

Some valid URLS:

• nats://localhost:4222
• nats://user@localhost:4222
• nats://user:password@localhost:4222
• nats://host1:4222,nats://host2:4222,nats://host3:4222

Note

This option takes precedence over natsOptions_SetURL when NATS options are passed with stanConnOptions_SetNATSOptions.

Parameters

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

stanConnOptions_SetNATSOptions()

NATS_EXTERN natsStatus stanConnOptions_SetNATSOptions	(	stanConnOptions *	opts,
		natsOptions *	nOpts )

The Streaming client connects to the NATS Streaming Server through a regular NATS Connection (natsConnection). To configure this connection create a natsOptions and configure it as needed, then call this function.

This function clones the passed options, so after this call, any changes to the given natsOptions will not affect the stanConnOptions.

Note

If both natsOptions_SetURL and stanConnOptions_SetURL are used the URL(s) set in the later take precedence.

Parameters

opts	the pointer to the stanConnOptions object.
nOpts	the pointer to the natsOptions object to use to create the connection to the server.

stanConnOptions_SetConnectionWait()

NATS_EXTERN natsStatus stanConnOptions_SetConnectionWait	(	stanConnOptions *	opts,
		int64_t	wait )

Value expressed in milliseconds.

Default is 2000 milliseconds (2 seconds).

Parameters

opts	the pointer to the stanConnOptions object.
wait	how long to wait for a response from the streaming server.

stanConnOptions_SetPubAckWait()

NATS_EXTERN natsStatus stanConnOptions_SetPubAckWait	(	stanConnOptions *	opts,
		int64_t	wait )

Value expressed in milliseconds.

Default is 30000 milliseconds (30 seconds).

Parameters

opts	the pointer to the stanConnOptions object.
wait	how long to wait for a response from the streaming server.

stanConnOptions_SetDiscoveryPrefix()

NATS_EXTERN natsStatus stanConnOptions_SetDiscoveryPrefix	(	stanConnOptions *	opts,
		const char *	prefix )

Default is _STAN.discovery

Parameters

opts	the pointer to the stanConnOptions object.
prefix	the subject prefix the library sends the connect request to.

stanConnOptions_SetMaxPubAcksInflight()

NATS_EXTERN natsStatus stanConnOptions_SetMaxPubAcksInflight	(	stanConnOptions *	opts,
		int	maxPubAcksInflight,
		float	percentage )

A connection will block stanConnection_Publish() or stanConnection_PublishAsync calls if the number of outstanding published messages has reached this number.

When the connection receives ACKs, the number of outstanding messages will decrease. If the number falls between maxPubAcksInflight * percentage, then the blocked publish calls will be released.

Parameters

opts	the pointer to the stanConnOptions object.
maxPubAcksInflight	the maximum number of published messages without ACKs from the server.
percentage	the percentage (expressed as a float between ]0.0 and 1.0]) of the maxPubAcksInflight number below which a blocked publish call is released.

stanConnOptions_SetPings()

NATS_EXTERN natsStatus stanConnOptions_SetPings	(	stanConnOptions *	opts,
		int	interval,
		int	maxOut )

Value expressed in number of seconds.

Default is 5 seconds and 3 missed PONGs.

The interval needs to be at least 1 and represents the number of seconds. The maxOut needs to be at least 2, since the count of sent PINGs increase whenever a PING is sent and reset to 0 when a response is received. Setting to 1 would cause the library to close the connection right away.

Parameters

opts	the pointer to the stanConnOptions object.
interval	the number of seconds between each PING.
maxOut	the maximum number of PINGs without receiving a PONG back.

stanConnOptions_SetConnectionLostHandler()

NATS_EXTERN natsStatus stanConnOptions_SetConnectionLostHandler	(	stanConnOptions *	opts,
		stanConnectionLostHandler	handler,
		void *	closure )

This callback will be invoked should the client permanently lose contact with the server (or another client replaces it while being disconnected). The callback will not be invoked on normal stanConnection_Close().

Parameters

opts	the pointer to the stanConnOptions object.
handler	the handler to be invoked when the connection to the streaming server is lost.
closure	the closure the library will pass to the callback.

stanConnOptions_Destroy()

NATS_EXTERN void stanConnOptions_Destroy

(

stanConnOptions *

opts

)

Destroys the stanConnOptions object, freeing used memory. See the note in the stanConnOptions_Create() call.

Parameters

opts	the pointer to the stanConnOptions object to destroy.