NATS C Client with JetStream and Streaming support  3.2.0
The nats.io C Client, Supported by Synadia Communications Inc.
Subscribing

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_SubscribeSync (natsSubscription **sub, jsCtx *js, const char *subject, jsOptions *opts, jsSubOptions *subOpts, jsErrCode *errCode)
 Create a synchronous subscription. 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 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
optsthe 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 
)
Parameters
subthe location where to store the pointer to the newly created natsSubscription object.
jsthe pointer to the jsCtx object.
subjectthe subject this subscription is created for.
cbthe natsMsgHandler callback.
cbClosurea pointer to an user defined object (can be NULL). See the natsMsgHandler prototype.
optsthe pointer to the jsOptions object, possibly NULL.
subOptsthe subscribe options, possibly NULL.
errCodethe 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 
)
Parameters
subthe location where to store the pointer to the newly created natsSubscription object.
jsthe pointer to the jsCtx object.
subjectthe subject this subscription is created for. the natsMsgHandler prototype.
optsthe pointer to the jsOptions object, possibly NULL.
subOptsthe subscribe options, possibly NULL.
errCodethe 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
All pull subscriptions must have a durable name.
A durable name cannot contain the character ".".
Parameters
subthe location where to store the pointer to the newly created natsSubscription object.
jsthe pointer to the jsCtx object.
subjectthe subject this subscription is created for.
durablethe durable name, which is required for pull subscriptions.
optsthe pointer to the jsOptions object, possibly NULL.
subOptsthe subscribe options, possibly NULL.
errCodethe 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
listthe location to a natsMsgList that will be filled by the result of this call.
subthe pointer to the natsSubscription object.
batchthe batch size, that is, the maximum number of messages to return.
timeoutthe timeout (required) expressed in number of milliseconds.
errCodethe 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:

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
csmthe pointer location where to copy the consumer sequence mismatch information.
subthe pointer to the natsSubscription object.