NATS C Client with JetStream and Streaming support
3.8.0
The nats.io C Client, Supported by Synadia Communications Inc.
|
Functions | |
NATS_EXTERN natsStatus | jsSubOptions_Init (jsSubOptions *opts) |
Initializes a subscribe options structure. | |
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. | |
NATS_EXTERN natsStatus | js_SubscribeSync (natsSubscription **sub, jsCtx *js, const char *subject, jsOptions *opts, jsSubOptions *subOpts, jsErrCode *errCode) |
Create a synchronous subscription. | |
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. | |
NATS_EXTERN natsStatus | natsSubscription_Fetch (natsMsgList *list, natsSubscription *sub, int batch, int64_t timeout, jsErrCode *errCode) |
Fetches messages for a pull subscription. | |
NATS_EXTERN natsStatus | jsFetchRequest_Init (jsFetchRequest *request) |
Initializes a fetch request options structure. | |
NATS_EXTERN natsStatus | natsSubscription_FetchRequest (natsMsgList *list, natsSubscription *sub, jsFetchRequest *request) |
Fetches messages for a pull subscription with a complete request configuration. | |
NATS_EXTERN natsStatus | natsSubscription_GetConsumerInfo (jsConsumerInfo **ci, natsSubscription *sub, jsOptions *opts, jsErrCode *errCode) |
Returns the jsConsumerInfo associated with this subscription. | |
NATS_EXTERN natsStatus | natsSubscription_GetSequenceMismatch (jsConsumerSequenceMismatch *csm, natsSubscription *sub) |
Returns the consumer sequence mismatch information. | |
Subscribing functions
NATS_EXTERN natsStatus jsSubOptions_Init | ( | jsSubOptions * | opts | ) |
Use this before setting specific subscribe options and passing this configuration to the JetStream subscribe APIs.
opts | the pointer to the jsSubOptions to initialize. |
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.
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
.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. |
NATS_EXTERN natsStatus js_SubscribeSync | ( | natsSubscription ** | sub, |
jsCtx * | js, | ||
const char * | subject, | ||
jsOptions * | opts, | ||
jsSubOptions * | subOpts, | ||
jsErrCode * | errCode ) |
See important notes in js_Subscribe.
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. 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. |
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.
See important notes in js_Subscribe.
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. |
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.
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. |
NATS_EXTERN natsStatus jsFetchRequest_Init | ( | jsFetchRequest * | request | ) |
Use this before setting specific fetch options and passing it to natsSubscription_FetchRequest.
request | the pointer to the jsFetchRequest object. |
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.
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. |
NATS_EXTERN natsStatus natsSubscription_GetConsumerInfo | ( | jsConsumerInfo ** | ci, |
natsSubscription * | sub, | ||
jsOptions * | opts, | ||
jsErrCode * | errCode ) |
Returns the jsConsumerInfo associated with this subscription.
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. |
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.
csm | the pointer location where to copy the consumer sequence mismatch information. |
sub | the pointer to the natsSubscription object. |