Publishing

Functions
NATS_EXTERN natsStatus	jsPubOptions_Init (jsPubOptions *opts)
	Initializes a publish options structure. More...
NATS_EXTERN natsStatus	js_Publish (jsPubAck **pubAck, jsCtx *js, const char *subj, const void *data, int dataLen, jsPubOptions *opts, jsErrCode *errCode)
	Publishes data on a subject to JetStream. More...
NATS_EXTERN natsStatus	js_PublishMsg (jsPubAck **pubAck, jsCtx *js, natsMsg *msg, jsPubOptions *opts, jsErrCode *errCode)
	Publishes a message to JetStream. More...
NATS_EXTERN void	jsPubAck_Destroy (jsPubAck *pubAck)
	Destroys the publish acknowledgment object. More...
NATS_EXTERN natsStatus	js_PublishAsync (jsCtx *js, const char *subj, const void *data, int dataLen, jsPubOptions *opts)
	Publishes data to JetStream but does not wait for a jsPubAck. More...
NATS_EXTERN natsStatus	js_PublishMsgAsync (jsCtx *js, natsMsg **msg, jsPubOptions *opts)
	Publishes a message to JetStream but does not wait for a jsPubAck. More...
NATS_EXTERN natsStatus	js_PublishAsyncComplete (jsCtx *js, jsPubOptions *opts)
	Wait for all outstanding messages to be acknowledged. More...
NATS_EXTERN natsStatus	js_PublishAsyncGetPendingList (natsMsgList *pending, jsCtx *js)
	Returns the list of pending messages published asynchronously. More...

Detailed Description

Publishing functions

Function Documentation

jsPubOptions_Init()

NATS_EXTERN natsStatus jsPubOptions_Init

(

jsPubOptions *

opts

)

Use this before setting specific publish options and passing this configuration to the JetStream publish APIs.

Parameters

opts	the pointer to the jsPubOptions to initialize.

js_Publish()

NATS_EXTERN natsStatus js_Publish	(	jsPubAck **	pubAck,
		jsCtx *	js,
		const char *	subj,
		const void *	data,
		int	dataLen,
		jsPubOptions *	opts,
		jsErrCode *	errCode
	)

Publishes the data to the given subject to JetStream.

See js_PublishMsg for details.

Parameters

pubAck	the location where to store the pub acknowledgment, or NULL if not needed.
js	the pointer to the jsCtx 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.
opts	the publish options, possibly NULL.
errCode	the location where to store the JetStream specific error code, or NULL if not needed.

js_PublishMsg()

NATS_EXTERN natsStatus js_PublishMsg	(	jsPubAck **	pubAck,
		jsCtx *	js,
		natsMsg *	msg,
		jsPubOptions *	opts,
		jsErrCode *	errCode
	)

Publishes the given message to JetStream.

Note

If you are not interested in inspecting the publish acknowledgment, you can pass NULL, but keep in mind that the publish acknowledgment is still sent by the server.

The returned jsPubAck object needs to be destroyed with jsPubAck_Destroy when no longer needed.

See also

jsPubAck_Destroy

Parameters

pubAck	the location where to store the pub acknowledgment, or NULL if not needed.
js	the pointer to the jsCtx object.
msg	the pointer to the natsMsg object to send.
opts	the publish options, possibly NULL.
errCode	the location where to store the JetStream specific error code, or NULL if not needed.

jsPubAck_Destroy()

NATS_EXTERN void jsPubAck_Destroy

(

jsPubAck *

pubAck

)

Releases memory allocated for this publish acknowledgment object.

Parameters

pubAck

the jsPubAck object to destroy.

js_PublishAsync()

NATS_EXTERN natsStatus js_PublishAsync	(	jsCtx *	js,
		const char *	subj,
		const void *	data,
		int	dataLen,
		jsPubOptions *	opts
	)

See js_PublishMsgAsync for details.

Parameters

js	the pointer to the jsCtx 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.
opts	the publish options, possibly NULL.

js_PublishMsgAsync()

NATS_EXTERN natsStatus js_PublishMsgAsync	(	jsCtx *	js,
		natsMsg **	msg,
		jsPubOptions *	opts
	)

Publishes a message asynchronously to JetStream. User can call js_PublishAsyncComplete to be notified when all publish acknowledgments for the pending publish calls have been received.

Note

If this call is successful, the library takes ownership of the message and will destroy it after the acknowledgment has been received, or will present it to the user through the jsPubAckErrHandler callback. To prevent the user from accessing/destroying the message while in use by the library, this function requires a pointer to the pointer of the message so that it can be cleared. That way, the user should always call natsMsg_Destroy, regardless of success or failure, since natsMsg_Destroy will have no effect if the message pointer is NULL.

See also

js_PublishAsyncComplete

jsPubAckErrHandler

Parameters

js	the pointer to the jsCtx object.
msg	the memory location where the pointer to the natsMsg object is located. If the library takes ownership of the message, this location will be cleared so a following call to natsMsg_Destroy would have no effect.
opts	the publish options, possibly NULL.

js_PublishAsyncComplete()

NATS_EXTERN natsStatus js_PublishAsyncComplete	(	jsCtx *	js,
		jsPubOptions *	opts
	)

This call will block until the library has received acknowledgment for all outstanding published messages.

To limit the wait, user can pass a jsPubOptions with a MaxWait set to the maximum number of milliseconds that the call should block.

Parameters

js	the pointer to the jsCtx object.
opts	the publish options, possibly NULL.

js_PublishAsyncGetPendingList()

NATS_EXTERN natsStatus js_PublishAsyncGetPendingList	(	natsMsgList *	pending,
		jsCtx *	js
	)

This call returns the list of all asynchronously published messages for which no acknowledgment have been received yet.

The user has now back ownership of the messages and can resend send if desired or simply destroy them.

Note

After this call returns, it is possible that acknowledgments arrive from the server but since they have been removed from the pending list, the acknowledgments will be discarded (no jsPubAckErrHandler callback invoked). If the server did receive a particular message and the user in the meantime has resent that message, it would be a duplicate, so in order for the server to detect this duplicate, ensure that the stream's duplicate window setting is specified and a unique message ID was set when sending the message.

Warning

The user must call natsMsgList_Destroy to release memory allocated by this call and destroy all pending messages still present in the list.

natsMsgList pending;
 
s = js_PublishAsyncGetPendingList(&pending, js);
if (s == NATS_OK)
{
     int i;
 
     for (i=0; i<pending.Count; i++)
     {
             if (your_decision_to_resend(pending.Msgs[i]))
             {
                     // If the call is successful, pending.Msgs[i] will
                     // be set to NULL so the message will not be
                     // destroyed.
                     js_PublishMsgAsync(js, &(pending.Msgs[i]), NULL);
             }
     }
 
     // Calling this will release memory allocated to hold the
     // array of messages but also call natsMsg_Destroy on all
     // messages still present in the array.
     natsMsgList_Destroy(&pending);
}

Parameters

pending	pointer to a natsMsgList object, typically defined on the stack.
js	the pointer to the jsCtx object.