Publishing

Functions
NATS_EXTERN natsStatus	natsConnection_Publish (natsConnection *nc, const char *subj, const void *data, int dataLen)
	Publishes data on a subject.
NATS_EXTERN natsStatus	natsConnection_PublishString (natsConnection *nc, const char *subj, const char *str)
	Publishes a string on a subject.
NATS_EXTERN natsStatus	natsConnection_PublishMsg (natsConnection *nc, natsMsg *msg)
	Publishes a message on a subject.
NATS_EXTERN natsStatus	natsConnection_PublishRequest (natsConnection *nc, const char *subj, const char *reply, const void *data, int dataLen)
	Publishes data on a subject expecting replies on the given reply.
NATS_EXTERN natsStatus	natsConnection_PublishRequestString (natsConnection *nc, const char *subj, const char *reply, const char *str)
	Publishes a string on a subject expecting replies on the given reply.
NATS_EXTERN natsStatus	natsConnection_Request (natsMsg **replyMsg, natsConnection *nc, const char *subj, const void *data, int dataLen, int64_t timeout)
	Sends a request and waits for a reply.
NATS_EXTERN natsStatus	natsConnection_RequestString (natsMsg **replyMsg, natsConnection *nc, const char *subj, const char *str, int64_t timeout)
	Sends a request (as a string) and waits for a reply.
NATS_EXTERN natsStatus	natsConnection_RequestMsg (natsMsg **replyMsg, natsConnection *nc, natsMsg *requestMsg, int64_t timeout)
	Sends a request based on the given requestMsg and waits for a reply.
NATS_EXTERN natsStatus	natsConnection_Send (natsConnection *nc, const char *subj, const void *data, int dataLen)
	Sends data on a subject with reduced latency.
NATS_EXTERN natsStatus	natsConnection_SendMsg (natsConnection *nc, natsMsg *msg)
	Sends a message with reduced latency.
NATS_EXTERN natsStatus	natsConnection_SendRequest (natsConnection *nc, const char *subj, const char *reply, const void *data, int dataLen)
	Sends data with a reply subject with reduced latency.

Detailed Description

Publishing functions

Function Documentation

natsConnection_Publish()

NATS_EXTERN natsStatus natsConnection_Publish	(	natsConnection *	nc,
		const char *	subj,
		const void *	data,
		int	dataLen
	)

Publishes the data argument to the given subject. The data argument is left untouched and needs to be correctly interpreted on the receiver.

Note

Unless the connection is created with the natsOptions_SetSendAsap, the data is added to an internal buffer. If the buffer is considered full, then it is written to the TCP socket within this function, otherwise, the connection's flusher thread is notified. In order to maximize throughput, that thread tries to gather more data from future publish calls before writing to the TCP socket. This has an impact on latency. If latency is more important, use natsConnection_Send instead.

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the data is sent to.
data	the data to be sent, can be NULL.
dataLen	the length of the data to be sent.

natsConnection_PublishString()

NATS_EXTERN natsStatus natsConnection_PublishString	(	natsConnection *	nc,
		const char *	subj,
		const char *	str
	)

Convenient function to publish a string. This call is equivalent to:

const char* myString = "hello";
 
natsConnection_Publish(nc, subj, (const void*) myString, (int) strlen(myString));

See natsConnection_Publish note regarding when the data is sent.

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the data is sent to.
str	the string to be sent.

natsConnection_PublishMsg()

NATS_EXTERN natsStatus natsConnection_PublishMsg	(	natsConnection *	nc,
		natsMsg *	msg
	)

Publishes the natsMsg, which includes the subject, an optional reply and optional data.

See natsConnection_Publish note regarding when the data is sent.

See also

natsMsg_Create()

Parameters

nc	the pointer to the natsConnection object.
msg	the pointer to the natsMsg object to send.

natsConnection_PublishRequest()

NATS_EXTERN natsStatus natsConnection_PublishRequest	(	natsConnection *	nc,
		const char *	subj,
		const char *	reply,
		const void *	data,
		int	dataLen
	)

Publishes the data argument to the given subject expecting a response on the reply subject. Use natsConnection_Request() for automatically waiting for a response inline.

See natsConnection_Publish note regarding when the data is sent.

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the request is sent to.
reply	the reply on which responses are expected.
data	the data to be sent, can be NULL.
dataLen	the length of the data to be sent.

natsConnection_PublishRequestString()

NATS_EXTERN natsStatus natsConnection_PublishRequestString	(	natsConnection *	nc,
		const char *	subj,
		const char *	reply,
		const char *	str
	)

Convenient function to publish a request as a string. This call is equivalent to:

const char* myString = "hello";
 
natsPublishRequest(nc, subj, reply, (const void*) myString, (int) strlen(myString));

See natsConnection_Publish note regarding when the data is sent.

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the request is sent to.
reply	the reply on which responses are expected.
str	the string to send.

natsConnection_Request()

NATS_EXTERN natsStatus natsConnection_Request	(	natsMsg **	replyMsg,
		natsConnection *	nc,
		const char *	subj,
		const void *	data,
		int	dataLen,
		int64_t	timeout
	)

Sends a request payload and delivers the first response message, or an error, including a timeout if no message was received properly.

Note

See natsConnection_Publish note regarding how data is normally sent to the server. However, this call causes the internal buffer (along with this data) to be written to the server within this call. The rationale is that we don't want the connection to wait for more data to be sent, but instead for the request to be sent as soon as possible so that the latency waiting for the reply is reduced to a minimum.

Warning

If connected to a NATS Server v2.2.0+ with no responder running when the request is received, this call will return a NATS_NO_RESPONDERS error.

Parameters

replyMsg	the location where to store the pointer to the received natsMsg reply.
nc	the pointer to the natsConnection object.
subj	the subject the request is sent to.
data	the data of the request, can be NULL.
dataLen	the length of the data to send.
timeout	in milliseconds, before this call returns NATS_TIMEOUT if no response is received in this allotted time.

natsConnection_RequestString()

NATS_EXTERN natsStatus natsConnection_RequestString	(	natsMsg **	replyMsg,
		natsConnection *	nc,
		const char *	subj,
		const char *	str,
		int64_t	timeout
	)

Convenient function to send a request as a string. This call is equivalent to:

const char* myString = "hello";
 
natsConnection_Request(replyMsg, nc, subj, (const void*) myString, (int) strlen(myString));

See natsConnection_Request note regarding when data is sent.

Warning

See warning about no responders in natsConnection_Request().

Parameters

replyMsg	the location where to store the pointer to the received natsMsg reply.
nc	the pointer to the natsConnection object.
subj	the subject the request is sent to.
str	the string to send.
timeout	in milliseconds, before this call returns NATS_TIMEOUT if no response is received in this allotted time.

natsConnection_RequestMsg()

NATS_EXTERN natsStatus natsConnection_RequestMsg	(	natsMsg **	replyMsg,
		natsConnection *	nc,
		natsMsg *	requestMsg,
		int64_t	timeout
	)

Similar to natsConnection_Request but uses requestMsg to extract subject, and payload to send.

See natsConnection_Request note regarding when data is sent.

Warning

See warning about no responders in natsConnection_Request().

Parameters

replyMsg	the location where to store the pointer to the received natsMsg reply.
nc	the pointer to the natsConnection object.
requestMsg	the message used for the request.
timeout	in milliseconds, before this call returns NATS_TIMEOUT if no response is received in this allotted time.

natsConnection_Send()

NATS_EXTERN natsStatus natsConnection_Send	(	natsConnection *	nc,
		const char *	subj,
		const void *	data,
		int	dataLen
	)

This is similar to natsConnection_Publish but the data is written to the TCP socket within this function.

See natsConnection_Publish note for more information about how data is normally sent to the server.

Note

The data is still added to the internal buffer and is written to the socket from the function itself. It means that if the application mixes "publish" and "send" calls, it is possible that the "send" function writes a much bigger buffer than the data it is trying to send. In other words, this function doe not send the data out-of-order with regards to the "publish" calls.

See also

natsConnection_SendMsg

natsConnection_SendRequest

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the data is sent to.
data	the data to send, can be NULL.
dataLen	the length of the data to send.

natsConnection_SendMsg()

NATS_EXTERN natsStatus natsConnection_SendMsg	(	natsConnection *	nc,
		natsMsg *	msg
	)

This is similar to natsConnection_Send but uses a natsMsg which includes the subject, an optional reply and optional data.

This is needed if the application wants to send a message with headers.

See natsConnection_Send for more details.

See also

natsConnection_Send

natsConnection_SendRequest

Parameters

nc	the pointer to the natsConnection object.
msg	the natsMsg to send.

natsConnection_SendRequest()

NATS_EXTERN natsStatus natsConnection_SendRequest	(	natsConnection *	nc,
		const char *	subj,
		const char *	reply,
		const void *	data,
		int	dataLen
	)

This is similar to natsConnection_Send but requires a reply subject.

See natsConnection_Send for more details.

See also

natsConnection_Send

natsConnection_SendMsg

Parameters

nc	the pointer to the natsConnection object.
subj	the subject the request is sent to.
reply	the reply subject for this message.
data	the data of the request, can be NULL.
dataLen	the length of the data to send.