Functions
NATS_EXTERN natsStatus	natsConnection_Connect (natsConnection *nc, natsOptions options)
	Connects to a `NATS Server` using the provided options.

NATS_EXTERN void	natsConnection_ProcessReadEvent (natsConnection *nc)
	Process a read event when using external event loop.

NATS_EXTERN void	natsConnection_ProcessWriteEvent (natsConnection *nc)
	Process a write event when using external event loop.

NATS_EXTERN natsStatus	natsConnection_ConnectTo (natsConnection *nc, const char urls)
	Connects to a `NATS Server` using any of the URL from the given list.

NATS_EXTERN bool	natsConnection_IsClosed (natsConnection *nc)
	Test if connection has been closed.

NATS_EXTERN bool	natsConnection_IsReconnecting (natsConnection *nc)
	Test if connection is reconnecting.

NATS_EXTERN bool	natsConnection_IsDraining (natsConnection *nc)
	Test if connection is draining.

NATS_EXTERN natsConnStatus	natsConnection_Status (natsConnection *nc)
	Returns the current state of the connection.

NATS_EXTERN int	natsConnection_Buffered (natsConnection *nc)
	Returns the number of bytes to be sent to the server.

NATS_EXTERN natsStatus	natsConnection_Flush (natsConnection *nc)
	Flushes the connection.

NATS_EXTERN natsStatus	natsConnection_FlushTimeout (natsConnection *nc, int64_t timeout)
	Flushes the connection with a given timeout.

NATS_EXTERN int64_t	natsConnection_GetMaxPayload (natsConnection *nc)
	Returns the maximum message payload.

NATS_EXTERN natsStatus	natsConnection_GetStats (natsConnection nc, natsStatistics stats)
	Gets the connection statistics.

NATS_EXTERN natsStatus	natsConnection_GetConnectedUrl (natsConnection nc, char buffer, size_t bufferSize)
	Gets the URL of the currently connected server.

NATS_EXTERN natsStatus	natsConnection_GetConnectedServerId (natsConnection nc, char buffer, size_t bufferSize)
	Gets the server Id.

NATS_EXTERN natsStatus	natsConnection_GetServers (natsConnection nc, char *servers, int count)
	Returns the list of server URLs known to this connection.

NATS_EXTERN natsStatus	natsConnection_GetDiscoveredServers (natsConnection nc, char *servers, int count)
	Returns the list of discovered server URLs.

NATS_EXTERN natsStatus	natsConnection_GetLastError (natsConnection nc, const char *lastError)
	Gets the last connection error.

NATS_EXTERN natsStatus	natsConnection_GetClientID (natsConnection nc, uint64_t cid)
	Gets the current client ID assigned by the server.

NATS_EXTERN natsStatus	natsConnection_Drain (natsConnection *nc)
	Drains the connection with default timeout.

NATS_EXTERN natsStatus	natsConnection_DrainTimeout (natsConnection *nc, int64_t timeout)
	Drains the connection with given timeout.

NATS_EXTERN natsStatus	natsConnection_Sign (natsConnection nc, const unsigned char message, int messageLen, unsigned char sig[64])
	Signs any 'message' using the connection's user credentials.

NATS_EXTERN natsStatus	natsConnection_GetClientIP (natsConnection nc, char *ip)
	Returns the client's IP address as reported by the server.

NATS_EXTERN natsStatus	natsConnection_GetRTT (natsConnection nc, int64_t rtt)
	Returns the round trip time between this client and the server.

NATS_EXTERN natsStatus	natsConnection_HasHeaderSupport (natsConnection *nc)
	Returns if the connection to current server supports headers.

NATS_EXTERN natsStatus	natsConnection_GetLocalIPAndPort (natsConnection nc, char ip, int port)
	Returns the connection local IP and port.

NATS_EXTERN void	natsConnection_Close (natsConnection *nc)
	Closes the connection.

NATS_EXTERN void	natsConnection_Destroy (natsConnection *nc)
	Destroys the connection object.

Detailed Description

Functions related to connection management.

Function Documentation

◆ natsConnection_Connect()

NATS_EXTERN natsStatus natsConnection_Connect	(	natsConnection **	nc,
		natsOptions *	options )

Attempts to connect to a NATS Server with multiple options.

This call is cloning the natsOptions object. 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 natsConnection_Connect() call if desired.

See also: natsOptions; natsConnection_Destroy()

Parameters

nc	the location where to store the pointer to the newly created natsConnection object.
options	the options to use for this connection. If `NULL` this call is equivalent to natsConnection_ConnectTo() with NATS_DEFAULT_URL.

◆ natsConnection_ProcessReadEvent()

NATS_EXTERN void natsConnection_ProcessReadEvent ( natsConnection * nc )

When using an external event loop, and the callback indicating that the socket is ready for reading, this call will read data from the socket and process it.

Parameters

nc	the pointer to the natsConnection object.

Warning: This API is reserved for external event loop adapters.

◆ natsConnection_ProcessWriteEvent()

NATS_EXTERN void natsConnection_ProcessWriteEvent ( natsConnection * nc )

When using an external event loop, and the callback indicating that the socket is ready for writing, this call will write data to the socket.

Parameters

nc	the pointer to the natsConnection object.

Warning: This API is reserved for external event loop adapters.

◆ natsConnection_ConnectTo()

NATS_EXTERN natsStatus natsConnection_ConnectTo	(	natsConnection **	nc,
		const char *	urls )

Attempts to connect to a NATS Server.

This call supports multiple comma separated URLs. If more than one is specified, it behaves as if you were using a natsOptions object and called natsOptions_SetServers() with the equivalent array of URLs. The list is randomized before the connect sequence starts.

See also: natsConnection_Destroy(); natsOptions_SetServers()

Parameters

nc	the location where to store the pointer to the newly created natsConnection object.
urls	the URL to connect to, or the list of URLs to chose from. If `NULL` this call is equivalent to natsConnection_ConnectTo() with NATS_DEFAULT_URL

◆ natsConnection_IsClosed()

NATS_EXTERN bool natsConnection_IsClosed ( natsConnection * nc )

Tests if connection has been closed.

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_IsReconnecting()

NATS_EXTERN bool natsConnection_IsReconnecting ( natsConnection * nc )

Tests if connection is reconnecting.

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_IsDraining()

NATS_EXTERN bool natsConnection_IsDraining ( natsConnection * nc )

Tests if connection is draining.

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_Status()

NATS_EXTERN natsConnStatus natsConnection_Status ( natsConnection * nc )

Returns the current state of the connection.

See also: natsConnStatus

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_Buffered()

NATS_EXTERN int natsConnection_Buffered ( natsConnection * nc )

When calling any of the publish functions, data is not necessarily immediately sent to the server. Some buffering occurs, allowing for better performance. This function indicates if there is any data not yet transmitted to the server.

Parameters

nc	the pointer to the natsConnection object.

Returns: the number of bytes to be sent to the server, or -1 if the connection is closed.

◆ natsConnection_Flush()

NATS_EXTERN natsStatus natsConnection_Flush ( natsConnection * nc )

Performs a round trip to the server and return when it receives the internal reply.

Note that if this call occurs when the connection to the server is lost, the PING will not be echoed even if the library can connect to a new (or the same) server. Therefore, in such situation, this call will fail with the status NATS_CONNECTION_DISCONNECTED.

If the connection is closed while this call is in progress, then the status NATS_CONN_STATUS_CLOSED would be returned instead.

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_FlushTimeout()

NATS_EXTERN natsStatus natsConnection_FlushTimeout	(	natsConnection *	nc,
		int64_t	timeout )

Performs a round trip to the server and return when it receives the internal reply, or if the call times-out (timeout is expressed in milliseconds).

See possible failure case described in natsConnection_Flush().

Parameters

nc	the pointer to the natsConnection object.
timeout	in milliseconds, is the time allowed for the flush to complete before NATS_TIMEOUT error is returned.

◆ natsConnection_GetMaxPayload()

NATS_EXTERN int64_t natsConnection_GetMaxPayload ( natsConnection * nc )

Returns the maximum message payload accepted by the server. The information is gathered from the NATS Server when the connection is first established.

Parameters

nc	the pointer to the natsConnection object.

Returns: the maximum message payload.

◆ natsConnection_GetStats()

NATS_EXTERN natsStatus natsConnection_GetStats	(	natsConnection *	nc,
		natsStatistics *	stats )

Copies in the provided statistics structure, a snapshot of the statistics for this connection.

Parameters

nc	the pointer to the natsConnection object.
stats	the pointer to a natsStatistics object in which statistics will be copied.

◆ natsConnection_GetConnectedUrl()

NATS_EXTERN natsStatus natsConnection_GetConnectedUrl	(	natsConnection *	nc,
		char *	buffer,
		size_t	bufferSize )

Copies in the given buffer, the connected server's Url. If the buffer is too small, an error is returned.

Parameters

nc	the pointer to the natsConnection object.
buffer	the buffer in which the URL is copied.
bufferSize	the size of the buffer.

◆ natsConnection_GetConnectedServerId()

NATS_EXTERN natsStatus natsConnection_GetConnectedServerId	(	natsConnection *	nc,
		char *	buffer,
		size_t	bufferSize )

Copies in the given buffer, the connected server's Id. If the buffer is too small, an error is returned.

Parameters

nc	the pointer to the natsConnection object.
buffer	the buffer in which the server id is copied.
bufferSize	the size of the buffer.

◆ natsConnection_GetServers()

NATS_EXTERN natsStatus natsConnection_GetServers	(	natsConnection *	nc,
		char ***	servers,
		int *	count )

Returns the list of known servers, including additional servers discovered after a connection has been established (with servers version 0.9.2 and above).

No credential information is included in any of the server URLs returned by this call.
If you want to use any of these URLs to connect to a server that requires authentication, you will need to use natsOptions_SetUserInfo or natsOptions_SetToken.

Note: The user is responsible for freeing the memory of the returned array.

Parameters

nc	the pointer to the natsConnection object.
servers	the location where to store the pointer to the array of server URLs.
count	the location where to store the number of elements of the returned array.

◆ natsConnection_GetDiscoveredServers()

NATS_EXTERN natsStatus natsConnection_GetDiscoveredServers	(	natsConnection *	nc,
		char ***	servers,
		int *	count )

Unlike natsConnection_GetServers, this function only returns the list of servers that have been discovered after the a connection has been established (with servers version 0.9.2 and above).

No credential information is included in any of the server URLs returned by this call.
If you want to use any of these URLs to connect to a server that requires authentication, you will need to use natsOptions_SetUserInfo or natsOptions_SetToken.

Note: The user is responsible for freeing the memory of the returned array.

Parameters

nc	the pointer to the natsConnection object.
servers	the location where to store the pointer to the array of server URLs.
count	the location where to store the number of elements of the returned array.

◆ natsConnection_GetLastError()

NATS_EXTERN natsStatus natsConnection_GetLastError	(	natsConnection *	nc,
		const char **	lastError )

Returns the last known error as a 'natsStatus' and the location to the null-terminated error string.

Warning: The returned string is owned by the connection object and must not be freed.

Parameters

nc	the pointer to the natsConnection object.
lastError	the location where the pointer to the connection's last error string is copied.

◆ natsConnection_GetClientID()

NATS_EXTERN natsStatus natsConnection_GetClientID	(	natsConnection *	nc,
		uint64_t *	cid )

Returns the client ID assigned by the server to which the client is currently connected to.

Note: The value may change if the client reconnects.

This function returns NATS_NO_SERVER_SUPPORT if the server's version is less than 1.2.0.

Parameters

nc	the pointer to the natsConnection object.
cid	the location where to store the client ID.

◆ natsConnection_Drain()

NATS_EXTERN natsStatus natsConnection_Drain ( natsConnection * nc )

Drain will put a connection into a drain state. All subscriptions will immediately be put into a drain state. Upon completion, the publishers will be drained and can not publish any additional messages. Upon draining of the publishers, the connection will be closed. Use the natsOptions_SetClosedCB() option to know when the connection has moved from draining to closed.

This call uses a default drain timeout of 30 seconds.

Warning: This function does not block waiting for the draining operation to complete.

See also: natsOptions_SetClosedCB; natsConnection_DrainTimeout

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_DrainTimeout()

NATS_EXTERN natsStatus natsConnection_DrainTimeout	(	natsConnection *	nc,
		int64_t	timeout )

Identical to natsConnection_Drain but the timeout can be specified here.

The value is expressed in milliseconds. Zero or negative value means that the operation will not timeout.

Warning: This function does not block waiting for the draining operation to complete.

See also: natsOptions_SetClosedCB; natsConnection_Drain

Parameters

nc	the pointer to the natsConnection object.
timeout	the allowed time for a drain operation to complete, expressed in milliseconds.

◆ natsConnection_Sign()

NATS_EXTERN natsStatus natsConnection_Sign	(	natsConnection *	nc,
		const unsigned char *	message,
		int	messageLen,
		unsigned char	sig[64] )

The connection must have been created with the natsOptions_SetUserCredentialsFromFiles.

This call will sign the given message with the private key extracted through the user credentials file(s).

Parameters

nc	the pointer to the natsConnection object.
message	the byte array to sign.
messageLen	the length of the given byte array.
sig	an array of 64 bytes in which the signature will be copied.

◆ natsConnection_GetClientIP()

NATS_EXTERN natsStatus natsConnection_GetClientIP	(	natsConnection *	nc,
		char **	ip )

When a connection is created to the server, the server identifies the connection's remote IP address and return it back to the client.

Note: The user is responsible to free memory allocated to store the client IP address.; This is supported on servers >= version 2.1.6. Calling natsConnection_GetClientIP() with server below this version will return the NATS_NO_SERVER_SUPPORT error.

See also: natsConnection_GetLocalIPAndPort to get the local IP and port instead.

Parameters

nc	the pointer to the natsConnection object.
ip	the memory location where to store the client's IP string. The user is responsible from freeing this memory.

◆ natsConnection_GetRTT()

NATS_EXTERN natsStatus natsConnection_GetRTT	(	natsConnection *	nc,
		int64_t *	rtt )

The value returned is in nanoseconds.

Note: If the library is currently trying to reconnect, this call will return NATS_CONNECTION_DISCONNECTED.

Parameters

nc	the pointer to the natsConnection object.
rtt	the memory location where to store the rtt.

◆ natsConnection_HasHeaderSupport()

NATS_EXTERN natsStatus natsConnection_HasHeaderSupport ( natsConnection * nc )

Returns NATS_OK if the server this client is currently connected to supports headers, NATS_NO_SERVER_SUPPORT otherwise.

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_GetLocalIPAndPort()

NATS_EXTERN natsStatus natsConnection_GetLocalIPAndPort	(	natsConnection *	nc,
		char **	ip,
		int *	port )

Unlike natsConnection_GetClientIP, this function returns the connection's local IP and port.

Note: The user is responsible for freeing the memory allocated for the returned IP string.

Parameters

nc	the pointer of the natsConnection object.
ip	the memory location where to store the local IP string. The user is responsible from freeing this memory.
port	the memory location where to store the local port.

Returns: NATS_OK on success.; NATS_CONNECTION_DISCONNECTED if disconnected.; NATS_CONNECTION_CLOSED is connection is closed.; NATS_SYS_ERROR if a system error getting the IP and port occurred.; NATS_NO_MEMORY if the library was unable to allocate memory for the returned IP string.

◆ natsConnection_Close()

NATS_EXTERN void natsConnection_Close ( natsConnection * nc )

Closes the connection to the server. This call will release all blocking calls, such as natsConnection_Flush() and natsSubscription_NextMsg(). The connection object is still usable until the call to natsConnection_Destroy().

Parameters

nc	the pointer to the natsConnection object.

◆ natsConnection_Destroy()

NATS_EXTERN void natsConnection_Destroy ( natsConnection * nc )

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

Parameters

nc	the pointer to the natsConnection object.