Functions
NATS_EXTERN natsStatus	stanConnection_Connect (stanConnection *sc, const char clusterID, const char clientID, stanConnOptions options)
	Connects to a `NATS Streaming Server` using the provided options.

NATS_EXTERN natsStatus	stanConnection_GetNATSConnection (stanConnection sc, natsConnection *nc)
	Returns the underlying NATS Connection.

NATS_EXTERN void	stanConnection_ReleaseNATSConnection (stanConnection *sc)
	Releases the NATS Connection.

NATS_EXTERN natsStatus	stanConnection_Close (stanConnection *sc)
	Closes the connection.

NATS_EXTERN natsStatus	stanConnection_Destroy (stanConnection *sc)
	Destroys the connection object.

Detailed Description

Functions related to connection management.

Function Documentation

◆ stanConnection_Connect()

NATS_EXTERN natsStatus stanConnection_Connect	(	stanConnection **	sc,
		const char *	clusterID,
		const char *	clientID,
		stanConnOptions *	options )

Attempts to connect to a NATS Streaming Server.

This call is cloning the stanConnOptions object, if given. Once this call returns, changes made to the options will not have an effect to this connection. The options can however be changed prior to be passed to another stanConnection_Connect() call if desired.

Note: The Streaming connection does not honor the NATS Connection option natsOptions_SetRetryOnFailedConnect(). If you pass NATS Options with this option enabled, no error is returned, but if the connection cannot be established "right away", the connect call will return an error.

Warning: If connecting to a NATS Server v2.2.0+ and there is no Streaming server listening on the connect request subject, this call will return NATS_NO_RESPONDERS, not NATS_TIMEOUT.

See also: stanConnOptions; stanConnection_Destroy()

Parameters

sc	the location where to store the pointer to the newly created natsConnection object.
clusterID	the name of the cluster this connection is for.
clientID	the client ID for this connection. Only one connection with this ID will be accepted by the server. Use only a-zA-Z0-9_- characters.
options	the options to use for this connection (can be `NULL`).

◆ stanConnection_GetNATSConnection()

NATS_EXTERN natsStatus stanConnection_GetNATSConnection	(	stanConnection *	sc,
		natsConnection **	nc )

This can be used if the application needs to do non streaming messaging but does not want to create a separate NATS Connection.

Obtain a NATS connection from a NATS streaming connection. The NATS connection can be used to perform regular NATS operations, but it is owned and managed by the NATS streaming connection. It cannot be closed, which will happen when the NATS streaming connection is closed.

Note: For each call to this function, the user must call stanConnection_ReleaseNATSConnection() when access to the NATS Connection is no longer needed.

Warning: The returned connection cannot be closed, drained nor destroyed. Calling corresponding functions will have no effect or return NATS_ILLEGAL_STATE.

See also: stanConnection_ReleaseNATSConnection()

Parameters

sc	the pointer to the stanConnection object.
nc	the location where to store the pointer of the natsConnection object.

◆ stanConnection_ReleaseNATSConnection()

NATS_EXTERN void stanConnection_ReleaseNATSConnection ( stanConnection * sc )

This should be paired with the stanConnection_GetNATSConnection() call. That is, after getting a reference to the underlying NATS Connection and once that connection is no longer needed, calling this function will allow resources to be properly released when the streaming connection is destroyed.

You would normally call stanConnection_GetNATSConnection() and this function only once.

After the last stanConnection_ReleaseNATSConnection() call is made, you must no longer use the NATS Connection because if stanConnection_Destroy() is called, that could make the pointer to the NATS Connection invalid.

Note: If the streaming connection is closed/destroyed before the last call to stanConnection_ReleaseNATSConnection, the pointer to the NATS connection will still be valid, although all calls will fail since the connection is now closed. Calling this function will release the streaming object allowing memory to be freed.

See also: stanConnection_GetNATSConnection

Parameters

sc	the pointer to the stanConnection object.

◆ stanConnection_Close()

NATS_EXTERN natsStatus stanConnection_Close ( stanConnection * sc )

Closes the connection to the server. This call will release all blocking calls. The connection object is still usable until the call to stanConnection_Destroy().

Warning: See warning about connecting to a NATS Server v2.2.0+ in stanConnection_Connect().

Parameters

sc	the pointer to the stanConnection object.

◆ stanConnection_Destroy()

NATS_EXTERN natsStatus stanConnection_Destroy ( stanConnection * sc )

Destroys the connection object, freeing up memory. If not already done, this call first closes the connection to the server.

Parameters

sc	the pointer to the stanConnection object.