Functions
NATS_EXTERN natsStatus	jsSubOptions_Init (jsSubOptions *opts)
	Initializes a subscribe options structure. More...

NATS_EXTERN natsStatus	js_Subscribe (natsSubscription *sub, jsCtx js, const char subject, natsMsgHandler cb, void cbClosure, jsOptions opts, jsSubOptions subOpts, jsErrCode *errCode)
	Create an asynchronous subscription. More...

NATS_EXTERN natsStatus	js_SubscribeMulti (natsSubscription *sub, jsCtx js, const char *subjects, int numSubjects, natsMsgHandler cb, void cbClosure, jsOptions opts, jsSubOptions subOpts, jsErrCode *errCode)
	Create an asynchronous subscription to multiple subjects. More...

NATS_EXTERN natsStatus	js_SubscribeSync (natsSubscription *sub, jsCtx js, const char subject, jsOptions opts, jsSubOptions subOpts, jsErrCode errCode)
	Create a synchronous subscription. More...

NATS_EXTERN natsStatus	js_SubscribeSyncMulti (natsSubscription *sub, jsCtx js, const char *subjects, int numSubjects, jsOptions opts, jsSubOptions subOpts, jsErrCode errCode)
	Create an asynchronous subscription to multiple subjects. More...

NATS_EXTERN natsStatus	js_PullSubscribe (natsSubscription *sub, jsCtx js, const char subject, const char durable, jsOptions opts, jsSubOptions subOpts, jsErrCode *errCode)
	Create a pull subscriber. More...

NATS_EXTERN natsStatus	natsSubscription_Fetch (natsMsgList list, natsSubscription sub, int batch, int64_t timeout, jsErrCode *errCode)
	Fetches messages for a pull subscription. More...

NATS_EXTERN natsStatus	jsFetchRequest_Init (jsFetchRequest *request)
	Initializes a fetch request options structure. More...

NATS_EXTERN natsStatus	js_PullSubscribeAsync (natsSubscription *newsub, jsCtx js, const char subject, const char durable, natsMsgHandler msgCB, void msgCBClosure, jsOptions jsOpts, jsSubOptions opts, jsErrCode errCode)
	Starts a Pull based JetStream subscription, and delivers messages to a user callback asynchronously. More...

NATS_EXTERN natsStatus	natsSubscription_FetchRequest (natsMsgList list, natsSubscription sub, jsFetchRequest *request)
	Fetches messages for a pull subscription with a complete request configuration. More...

NATS_EXTERN natsStatus	natsSubscription_GetConsumerInfo (jsConsumerInfo *ci, natsSubscription sub, jsOptions opts, jsErrCode errCode)
	Returns the jsConsumerInfo associated with this subscription. More...

NATS_EXTERN natsStatus	natsSubscription_GetSequenceMismatch (jsConsumerSequenceMismatch csm, natsSubscription sub)
	Returns the consumer sequence mismatch information. More...

Detailed Description

Subscribing functions

Function Documentation

◆ jsSubOptions_Init()

NATS_EXTERN natsStatus jsSubOptions_Init ( jsSubOptions * opts )

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

Parameters

opts	the pointer to the jsSubOptions to initialize.

◆ js_Subscribe()

NATS_EXTERN natsStatus js_Subscribe	(	natsSubscription **	sub,
		jsCtx *	js,
		const char *	subject,
		natsMsgHandler	cb,
		void *	cbClosure,
		jsOptions *	opts,
		jsSubOptions *	subOpts,
		jsErrCode *	errCode
	)

Typically the user or administrator will have created a JetStream consumer and this call will reference the stream/consumer to bind to with the use of jsSubOptions's Stream and Consumer.

Without the stream information, the library will use the provided subject to try figure out which stream this subscription is for.

If a Durable is specified (with jsSubOptions' Config.Durable), the subscription will be durable. However, note the behavior described below regarding JetStream consumers created by this call.

If no Durable is specified, the subscription will be ephemeral and removed by the server either after calling natsSubscription_Unsubscribe or after the subscription is destroyed and the InactivityThreshold has elapsed.

Note: If a JetStream consumer does not exist and this call creates it, it will be removed in the server once the user calls natsSubscription_Unsubscribe or natsSubscription_Drain, even if this is a Durable subscription. If the subscription should be maintained, it should be explicitly created using js_AddConsumer and then bound to with the use of jsSubOptions' Stream and Consumer.

Warning: Prior to release v3.4.0, calling natsSubscription_Destroy would delete the JetStream consumer if it was created by this call. The original intent was that it would be deleted only with explicit calls to unsubscribe or drain. Therefore, starting v3.4.0, if the user calls only natsSubscription_Destroy (to free memory), the JetStream consumer will no longer be deleted. The user would have to explicitly call natsSubscription_Unsubscribe or js_DeleteConsumer.

Parameters

sub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subject	the subject this subscription is created for.
cb	the natsMsgHandler callback.
cbClosure	a pointer to an user defined object (can be `NULL`). See the natsMsgHandler prototype.
opts	the pointer to the jsOptions object, possibly `NULL`.
subOpts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ js_SubscribeMulti()

NATS_EXTERN natsStatus js_SubscribeMulti	(	natsSubscription **	sub,
		jsCtx *	js,
		const char **	subjects,
		int	numSubjects,
		natsMsgHandler	cb,
		void *	cbClosure,
		jsOptions *	opts,
		jsSubOptions *	subOpts,
		jsErrCode *	errCode
	)

Like js_Subscribe, but accepts multiple subjects, each can be a wildcard.

Parameters

sub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subjects	the subject this subscription is created for.
numSubjects	the number of subjects for the subscription.
cb	the natsMsgHandler callback.
cbClosure	a pointer to an user defined object (can be `NULL`). See the natsMsgHandler prototype.
opts	the pointer to the jsOptions object, possibly `NULL`.
subOpts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ js_SubscribeSync()

NATS_EXTERN natsStatus js_SubscribeSync	(	natsSubscription **	sub,
		jsCtx *	js,
		const char *	subject,
		jsOptions *	opts,
		jsSubOptions *	subOpts,
		jsErrCode *	errCode
	)

See important notes in js_Subscribe.

Parameters

sub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subject	the subject this subscription is created for (consumer's FilterSubject).
opts	the pointer to the jsOptions object, possibly `NULL`.
subOpts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ js_SubscribeSyncMulti()

NATS_EXTERN natsStatus js_SubscribeSyncMulti	(	natsSubscription **	sub,
		jsCtx *	js,
		const char **	subjects,
		int	numSubjects,
		jsOptions *	opts,
		jsSubOptions *	subOpts,
		jsErrCode *	errCode
	)

Like js_SubscribeSync, but accepts multiple subjects, each can be a wildcard.

Parameters

sub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subjects	the subjects this subscription is created for (consumer's FilterSubjects).
numSubjects	the number of subjects for the subscription (consumer's FilterSubjectsLen).
opts	the pointer to the jsOptions object, possibly `NULL`.
subOpts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ js_PullSubscribe()

NATS_EXTERN natsStatus js_PullSubscribe	(	natsSubscription **	sub,
		jsCtx *	js,
		const char *	subject,
		const char *	durable,
		jsOptions *	opts,
		jsSubOptions *	subOpts,
		jsErrCode *	errCode
	)

A pull based consumer is a type of consumer that does not have a delivery subject, that is the library has to request for the messages to be delivered as needed from the server.

Note: If no durable name is provided, the pull subscription will create an ephemeral JetStream consumer. The requirement for a durable name is lifted in NATS C client v3.4.0+ and NATS Server v2.7.0+.; If a durable name is specified, it cannot contain the character ".".

See important notes in js_Subscribe.

Parameters

sub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subject	the subject this subscription is created for.
durable	the optional durable name.
opts	the pointer to the jsOptions object, possibly `NULL`.
subOpts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ natsSubscription_Fetch()

NATS_EXTERN natsStatus natsSubscription_Fetch	(	natsMsgList *	list,
		natsSubscription *	sub,
		int	batch,
		int64_t	timeout,
		jsErrCode *	errCode
	)

Fetches up to batch messages from the server, waiting up to timeout milliseconds. No more thant batch messages will be returned, however, it can be less.

For batch greater than 1, this call will not necessarily wait up timeout milliseconds if some messages were collected and the library receives a notification that no more messages are available at this time.
It means that calling natsSubscription_Fetch(&list, sub, 10, 5000) may return after less than 5 seconds with only 3 messages.

Parameters

list	the location to a natsMsgList that will be filled by the result of this call.
sub	the pointer to the natsSubscription object.
batch	the batch size, that is, the maximum number of messages to return.
timeout	the timeout (required) expressed in number of milliseconds.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ jsFetchRequest_Init()

NATS_EXTERN natsStatus jsFetchRequest_Init ( jsFetchRequest * request )

Use this before setting specific fetch options and passing it to natsSubscription_FetchRequest.

Parameters

request the pointer to the jsFetchRequest object.

◆ js_PullSubscribeAsync()

NATS_EXTERN natsStatus js_PullSubscribeAsync	(	natsSubscription **	newsub,
		jsCtx *	js,
		const char *	subject,
		const char *	durable,
		natsMsgHandler	msgCB,
		void *	msgCBClosure,
		jsOptions *	jsOpts,
		jsSubOptions *	opts,
		jsErrCode *	errCode
	)

The subscription can be set up to run indefinitely, and issue pull requests as needed, or it can be set up to auto-terminate when certain conditions (like max messages, or a time-based expiration) are met. lifetime is used to control the basic limits, and whether to use server Heartbeats to detect connection failures. jsOpts->PullSubscribeAsync is used to control the pulling parameters, provide extra event callbacks and hooks, and to tune the handling of missing heartbets.

Parameters

newsub	the location where to store the pointer to the newly created natsSubscription object.
js	the pointer to the jsCtx object.
subject	the subject this subscription is created for.
durable	the optional durable name.
msgCB	the natsMsgHandler callback.
msgCBClosure	a pointer to an user defined object (can be `NULL`).
jsOpts	the pointer to the jsOptions object, possibly `NULL`.
opts	the subscribe options, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ natsSubscription_FetchRequest()

NATS_EXTERN natsStatus natsSubscription_FetchRequest	(	natsMsgList *	list,
		natsSubscription *	sub,
		jsFetchRequest *	request
	)

Similar to natsSubscription_Fetch but a full jsFetchRequest configuration is provided for maximum control.

Initialize the jsFetchRequest structure using jsFetchRequest_Init and then set the parameters desired, then invoke this function.

Parameters

list	the location to a natsMsgList that will be filled by the result of this call.
sub	the pointer to the natsSubscription object.
request	the pointer to a jsFetchRequest configuration.

◆ natsSubscription_GetConsumerInfo()

NATS_EXTERN natsStatus natsSubscription_GetConsumerInfo	(	jsConsumerInfo **	ci,
		natsSubscription *	sub,
		jsOptions *	opts,
		jsErrCode *	errCode
	)

Returns the jsConsumerInfo associated with this subscription.

Parameters

ci	the location where to store the pointer to the new jsConsumerInfo object.
sub	the pointer to the natsSubscription object.
opts	the pointer to the jsOptions object, possibly `NULL`.
errCode	the location where to store the JetStream specific error code, or `NULL` if not needed.

◆ natsSubscription_GetSequenceMismatch()

NATS_EXTERN natsStatus natsSubscription_GetSequenceMismatch	(	jsConsumerSequenceMismatch *	csm,
		natsSubscription *	sub
	)

If Heartbeat is configured in jsConsumerConfig object (or configured in an existing JetStream consumer), the server sends heartbeats to the client at the given interval.

Those heartbeats contains information that allow the application to detect a mismatch between the server and client's view of the state of the consumer.

If the library detects a sequence mismatch, the behavior is different depending on the type of subscription:

For asynchronous subscriptions: the error NATS_MISMATCH is published to the error handler (see natsOptions_SetErrorHandler).
For synchronous subscriptions: the next call to natsSubscription_NextMsg() will return the error NATS_MISMATCH (but will succeed afterwards).

In both cases, the user should check what the mismatch is using this function and possibly recreate the consumer based on the provided information.

Note: For a valid JetStream subscription, this function will return NATS_NOT_FOUND if no consumer sequence mismatch has been detected.

See also: jsConsumerSequenceMismatch

Parameters

csm	the pointer location where to copy the consumer sequence mismatch information.
sub	the pointer to the natsSubscription object.

Functions

Detailed Description

Function Documentation

◆ jsSubOptions_Init()

◆ js_Subscribe()

◆ js_SubscribeMulti()

◆ js_SubscribeSync()

◆ js_SubscribeSyncMulti()

◆ js_PullSubscribe()

◆ natsSubscription_Fetch()

◆ jsFetchRequest_Init()

◆ js_PullSubscribeAsync()

◆ natsSubscription_FetchRequest()

◆ natsSubscription_GetConsumerInfo()

◆ natsSubscription_GetSequenceMismatch()