NATS C Client with JetStream and Streaming support  3.9.1
The nats.io C Client, Supported by Synadia Communications Inc.
JetStream Assets Management

Functions

NATS_EXTERN natsStatus jsStreamConfig_Init (jsStreamConfig *cfg)
 Initializes a streaming configuration structure. More...
 
NATS_EXTERN natsStatus jsPlacement_Init (jsPlacement *placement)
 Initializes a placement configuration structure. More...
 
NATS_EXTERN natsStatus jsStreamSource_Init (jsStreamSource *source)
 Initializes a stream source configuration structure. More...
 
NATS_EXTERN natsStatus jsExternalStream_Init (jsExternalStream *external)
 Initializes an external stream configuration structure. More...
 
NATS_EXTERN natsStatus jsRePublish_Init (jsRePublish *rp)
 Initializes a republish structure. More...
 
NATS_EXTERN natsStatus js_AddStream (jsStreamInfo **si, jsCtx *js, jsStreamConfig *cfg, jsOptions *opts, jsErrCode *errCode)
 Creates a stream. More...
 
NATS_EXTERN natsStatus js_UpdateStream (jsStreamInfo **si, jsCtx *js, jsStreamConfig *cfg, jsOptions *opts, jsErrCode *errCode)
 Updates a stream. More...
 
NATS_EXTERN natsStatus js_PurgeStream (jsCtx *js, const char *stream, jsOptions *opts, jsErrCode *errCode)
 Purges a stream. More...
 
NATS_EXTERN natsStatus js_DeleteStream (jsCtx *js, const char *stream, jsOptions *opts, jsErrCode *errCode)
 Deletes a stream. More...
 
NATS_EXTERN natsStatus js_GetMsg (natsMsg **msg, jsCtx *js, const char *stream, uint64_t seq, jsOptions *opts, jsErrCode *errCode)
 Retrieves a JetStream message from the stream by sequence. More...
 
NATS_EXTERN natsStatus js_GetLastMsg (natsMsg **msg, jsCtx *js, const char *stream, const char *subject, jsOptions *opts, jsErrCode *errCode)
 Retrieves the last JetStream message from the stream for a given subject. More...
 
NATS_EXTERN natsStatus jsDirectGetMsgOptions_Init (jsDirectGetMsgOptions *opts)
 Initializes a direct get message options structure. More...
 
NATS_EXTERN natsStatus js_DirectGetMsg (natsMsg **msg, jsCtx *js, const char *stream, jsOptions *opts, jsDirectGetMsgOptions *dgOpts)
 Retrieves directly a JetStream message based on provided options. More...
 
NATS_EXTERN natsStatus js_DeleteMsg (jsCtx *js, const char *stream, uint64_t seq, jsOptions *opts, jsErrCode *errCode)
 Deletes a message from the stream. More...
 
NATS_EXTERN natsStatus js_EraseMsg (jsCtx *js, const char *stream, uint64_t seq, jsOptions *opts, jsErrCode *errCode)
 Erases a message from the stream. More...
 
NATS_EXTERN natsStatus js_GetStreamInfo (jsStreamInfo **si, jsCtx *js, const char *stream, jsOptions *opts, jsErrCode *errCode)
 Retreives information from a stream. More...
 
NATS_EXTERN void jsStreamInfo_Destroy (jsStreamInfo *si)
 Destroys the stream information object. More...
 
NATS_EXTERN natsStatus js_Streams (jsStreamInfoList **list, jsCtx *js, jsOptions *opts, jsErrCode *errCode)
 Retrieves the list of all available streams. More...
 
NATS_EXTERN void jsStreamInfoList_Destroy (jsStreamInfoList *list)
 Destroys the stream information list object. More...
 
NATS_EXTERN natsStatus js_StreamNames (jsStreamNamesList **list, jsCtx *js, jsOptions *opts, jsErrCode *errCode)
 Retrieves the list of all available stream names. More...
 
NATS_EXTERN void jsStreamNamesList_Destroy (jsStreamNamesList *list)
 Destroys the stream names list object. More...
 
NATS_EXTERN natsStatus jsConsumerConfig_Init (jsConsumerConfig *cc)
 Initializes a consumer configuration structure. More...
 
NATS_EXTERN natsStatus js_AddConsumer (jsConsumerInfo **ci, jsCtx *js, const char *stream, jsConsumerConfig *cfg, jsOptions *opts, jsErrCode *errCode)
 Adds a JetStream consumer. More...
 
NATS_EXTERN natsStatus js_UpdateConsumer (jsConsumerInfo **ci, jsCtx *js, const char *stream, jsConsumerConfig *cfg, jsOptions *opts, jsErrCode *errCode)
 Updates a JetStream consumer. More...
 
NATS_EXTERN natsStatus js_GetConsumerInfo (jsConsumerInfo **ci, jsCtx *js, const char *stream, const char *consumer, jsOptions *opts, jsErrCode *errCode)
 Retrieves information about a consumer. More...
 
NATS_EXTERN natsStatus js_DeleteConsumer (jsCtx *js, const char *stream, const char *consumer, jsOptions *opts, jsErrCode *errCode)
 Deletes a consumer. More...
 
NATS_EXTERN natsStatus js_PauseConsumer (jsConsumerPauseResponse **new_cpr, jsCtx *js, const char *stream, const char *consumer, uint64_t pauseUntil, jsOptions *opts, jsErrCode *errCode)
 Pauses a consumer. More...
 
NATS_EXTERN void jsConsumerPauseResponse_Destroy (jsConsumerPauseResponse *cpr)
 Destroys the PauseConsumer response object. More...
 
NATS_EXTERN void jsConsumerInfo_Destroy (jsConsumerInfo *ci)
 Destroys the consumer information object. More...
 
NATS_EXTERN natsStatus js_Consumers (jsConsumerInfoList **list, jsCtx *js, const char *stream, jsOptions *opts, jsErrCode *errCode)
 Retrieves the list of all available consumers for a stream. More...
 
NATS_EXTERN void jsConsumerInfoList_Destroy (jsConsumerInfoList *list)
 Destroys the consumer information list object. More...
 
NATS_EXTERN natsStatus js_ConsumerNames (jsConsumerNamesList **list, jsCtx *js, const char *stream, jsOptions *opts, jsErrCode *errCode)
 Retrieves the list of all available consumer names for a stream. More...
 
NATS_EXTERN void jsConsumerNamesList_Destroy (jsConsumerNamesList *list)
 Destroys the consumer names list object. More...
 
NATS_EXTERN natsStatus js_GetAccountInfo (jsAccountInfo **ai, jsCtx *js, jsOptions *opts, jsErrCode *errCode)
 Retrieves information about the JetStream usage from an account. More...
 
NATS_EXTERN void jsAccountInfo_Destroy (jsAccountInfo *ai)
 Destroys the account information object. More...
 

Detailed Description

JetStream Assets Management

Function Documentation

◆ jsStreamConfig_Init()

NATS_EXTERN natsStatus jsStreamConfig_Init ( jsStreamConfig cfg)

Use this before setting specific stream configuration options and passing this configuration to some of the stream management APIs.

Parameters
cfgthe pointer to the jsStreamConfig to initialize.

◆ jsPlacement_Init()

NATS_EXTERN natsStatus jsPlacement_Init ( jsPlacement placement)

Use this before setting specific stream placement options.

Parameters
placementthe pointer to the jsPlacement to initialize.

◆ jsStreamSource_Init()

NATS_EXTERN natsStatus jsStreamSource_Init ( jsStreamSource source)

Use this before setting specific stream source options.

Parameters
sourcethe pointer to the jsStreamSource to initialize.

◆ jsExternalStream_Init()

NATS_EXTERN natsStatus jsExternalStream_Init ( jsExternalStream external)

Use this before setting specific external stream options.

Parameters
externalthe pointer to the jsExternalStream to initialize.

◆ jsRePublish_Init()

NATS_EXTERN natsStatus jsRePublish_Init ( jsRePublish rp)

Use this to set the source, destination and/or headers only for a stream re-publish.

Parameters
rpthe pointer to the jsRePublish to initialize.

◆ js_AddStream()

NATS_EXTERN natsStatus js_AddStream ( jsStreamInfo **  si,
jsCtx js,
jsStreamConfig cfg,
jsOptions opts,
jsErrCode errCode 
)

Creates a stream based on the provided configuration (that cannot be NULL). The name is mandatory and cannot contain . characters.

Note
If you do not need a jsStreamInfo to be returned, you can pass NULL, otherwise, on success you are responsible for freeing this object.
See also
jsStreamConfig_Init
jsStreamInfo_Destroy
Parameters
sithe location where to store the pointer to the new jsStreamInfo object in response to the creation request, or NULL if the stream information is not needed.
jsthe pointer to the jsCtx context.
cfgthe pointer to the jsStreamConfig.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_UpdateStream()

NATS_EXTERN natsStatus js_UpdateStream ( jsStreamInfo **  si,
jsCtx js,
jsStreamConfig cfg,
jsOptions opts,
jsErrCode errCode 
)

Updates a stream based on the provided configuration (that cannot be NULL). The name is mandatory and cannot contain . characters.

Note
If you do not need a jsStreamInfo to be returned, you can pass NULL, otherwise, on success you are responsible for freeing this object.
See also
jsStreamConfig_Init
jsStreamInfo_Destroy
Parameters
sithe location where to store the pointer to the new jsStreamInfo object in response to the creation request, or NULL if the stream information is not needed.
jsthe pointer to the jsCtx context.
cfgthe pointer to the jsStreamConfig.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_PurgeStream()

NATS_EXTERN natsStatus js_PurgeStream ( jsCtx js,
const char *  stream,
jsOptions opts,
jsErrCode errCode 
)

Purges the stream named stream.

For more advanced purge options, you can specify them through jsOptions.

jsOptions o;
jsOptions_Init(&o);
o.Stream.Purge.Subject = "foo";
o.Stream.Purge.Sequence = 4;
js_PurgeStream(js, "MY_STREAM", &o, &jerr);
Parameters
jsthe pointer to the jsCtx context.
streamthe name of the stream to purge.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_DeleteStream()

NATS_EXTERN natsStatus js_DeleteStream ( jsCtx js,
const char *  stream,
jsOptions opts,
jsErrCode errCode 
)

Deletes the stream named stream.

Parameters
jsthe pointer to the jsCtx context.
streamthe name of the stream to delete.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_GetMsg()

NATS_EXTERN natsStatus js_GetMsg ( natsMsg **  msg,
jsCtx js,
const char *  stream,
uint64_t  seq,
jsOptions opts,
jsErrCode errCode 
)

Retrieves a raw stream message stored in JetStream by sequence number.

Note
The message needs to be destroyed by calling natsMsg_Destroy.
See also
js_GetLastMsg
natsMsg_Destroy
Parameters
msgthe memory location where the library will store the pointer to the natsMsg.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
seqthe sequence in the stream of the message being retrieved.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_GetLastMsg()

NATS_EXTERN natsStatus js_GetLastMsg ( natsMsg **  msg,
jsCtx js,
const char *  stream,
const char *  subject,
jsOptions opts,
jsErrCode errCode 
)

Retrieves the last JetStream message from the stream for a given subject.

Note
The message needs to be destroyed by calling natsMsg_Destroy.
See also
js_GetMsg
natsMsg_Destroy
Parameters
msgthe memory location where the library will store the pointer to the natsMsg.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
subjectthe subject for which the last message is being retrieved.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsDirectGetMsgOptions_Init()

NATS_EXTERN natsStatus jsDirectGetMsgOptions_Init ( jsDirectGetMsgOptions opts)

Use this before setting specific direct get message options and passing it to js_DirectGetMsg API.

Parameters
optsthe pointer to the jsDirectGetMsgOptions object.

◆ js_DirectGetMsg()

NATS_EXTERN natsStatus js_DirectGetMsg ( natsMsg **  msg,
jsCtx js,
const char *  stream,
jsOptions opts,
jsDirectGetMsgOptions dgOpts 
)

If a stream is created with AllowDirect, it is possible to retrieve a message without going through the leader.

To specify the options, call jsDirectGetMsgOptions_Init first and the set the appropriate options, then invoke this function.

Note
Some options are mutually exclusive but the library is not doing the check and leave it to the server to do it and return the error returned by the server.
This API can only be used against servers that support the direct get feature, which is v2.9.0+. If running against an older server the call will likely timeout.
Parameters
msgthe location where to store the pointer to the retrieved message.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
optsthe pointer to the jsOptions object, possibly NULL.
dgOptsthe pointer to the jsDirectGetMsgOptions object, cannot be NULL.

◆ js_DeleteMsg()

NATS_EXTERN natsStatus js_DeleteMsg ( jsCtx js,
const char *  stream,
uint64_t  seq,
jsOptions opts,
jsErrCode errCode 
)

Deletes the message at sequence seq in the stream named stream.

Note
To completely erase the content of the deleted message when stored on disk, use js_EraseMsg instead.
See also
js_EraseMsg
Parameters
jsthe pointer to the jsCtx context.
streamthe name of the stream.
seqthe sequence in the stream of the message to delete.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_EraseMsg()

NATS_EXTERN natsStatus js_EraseMsg ( jsCtx js,
const char *  stream,
uint64_t  seq,
jsOptions opts,
jsErrCode errCode 
)

Similar to js_DeleteMsg except that the content of the deleted message is erased from stable storage.

See also
js_DeleteMsg
Parameters
jsthe pointer to the jsCtx context.
streamthe name of the stream.
seqthe sequence in the stream of the message to erase.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_GetStreamInfo()

NATS_EXTERN natsStatus js_GetStreamInfo ( jsStreamInfo **  si,
jsCtx js,
const char *  stream,
jsOptions opts,
jsErrCode errCode 
)

Returns information about the stream named stream.

Note
You need to free the returned object.

To get some detailed information about deleted messages, set this option:

jsOptions o;
jsOptions_Init(&o);
o.Stream.Info.DeletedDetails = true;
js_GetStreamInfo(&si, js, "MY_STREAM", &o, &jerr);
See also
jsStreamInfo_Destroy
Parameters
sithe location where to store the pointer to the new jsStreamInfo object in response to the creation request.
jsthe pointer to the jsCtx context.
streamthe name of the stream which information is retrieved.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsStreamInfo_Destroy()

NATS_EXTERN void jsStreamInfo_Destroy ( jsStreamInfo si)

Releases memory allocated for this stream information object.

Parameters
sithe pointer to the jsStreamInfo object.

◆ js_Streams()

NATS_EXTERN natsStatus js_Streams ( jsStreamInfoList **  list,
jsCtx js,
jsOptions opts,
jsErrCode errCode 
)

Retrieves the list of all jsStreamInfo. It is possible to filter which streams are to be retrieved based on a subject filter.

Warning
The list should be destroyed when no longer used by calling jsStreamInfoList_Destroy.
Parameters
listthe location where to store the pointer to the new jsStreamInfoList object.
jsthe pointer to the jsCtx context.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsStreamInfoList_Destroy()

NATS_EXTERN void jsStreamInfoList_Destroy ( jsStreamInfoList list)

Releases memory allocated for this stream information list.

Warning
All jsStreamInfo pointers contained in the list will be destroyed by this call.
Parameters
listthe pointer to the jsStreamInfoList object.

◆ js_StreamNames()

NATS_EXTERN natsStatus js_StreamNames ( jsStreamNamesList **  list,
jsCtx js,
jsOptions opts,
jsErrCode errCode 
)

Retrieves the list of all stream names. It is possible to filter which streams are to be retrieved based on a subject filter.

Warning
The list should be destroyed when no longer used by calling jsStreamNamesList_Destroy.
Parameters
listthe location where to store the pointer to the new jsStreamNamesList object.
jsthe pointer to the jsCtx context.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsStreamNamesList_Destroy()

NATS_EXTERN void jsStreamNamesList_Destroy ( jsStreamNamesList list)

Releases memory allocated for this list of stream names.

Warning
All string pointers contained in the list will be destroyed by this call.
Parameters
listthe pointer to the jsStreamNamesList object.

◆ jsConsumerConfig_Init()

NATS_EXTERN natsStatus jsConsumerConfig_Init ( jsConsumerConfig cc)

Use this before adding a consumer.

See also
jsConsumerConfig
Parameters
ccthe pointer to the jsConsumerConfig to initialize.

◆ js_AddConsumer()

NATS_EXTERN natsStatus js_AddConsumer ( jsConsumerInfo **  ci,
jsCtx js,
const char *  stream,
jsConsumerConfig cfg,
jsOptions opts,
jsErrCode errCode 
)

Adds a consumer based on the provided configuration (that cannot be NULL).

Note
If you do not need a jsConsumerInfo to be returned, you can pass NULL, otherwise, on success you are responsible for freeing this object.
See also
jsConsumerConfig_Init
jsConsumerInfo_Destroy
Parameters
cithe location where to store the pointer to the new jsConsumerInfo object in response to the creation request, or NULL if the consumer information is not needed.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
cfgthe pointer to the jsConsumerConfig.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_UpdateConsumer()

NATS_EXTERN natsStatus js_UpdateConsumer ( jsConsumerInfo **  ci,
jsCtx js,
const char *  stream,
jsConsumerConfig cfg,
jsOptions opts,
jsErrCode errCode 
)

Updates a consumer based on the provided configuration (that cannot be NULL).

Note
If you do not need a jsConsumerInfo to be returned, you can pass NULL, otherwise, on success you are responsible for freeing this object.
See also
jsConsumerConfig_Init
jsConsumerInfo_Destroy
Parameters
cithe location where to store the pointer to the new jsConsumerInfo object in response to the creation request, or NULL if the consumer information is not needed.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
cfgthe pointer to the jsConsumerConfig.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_GetConsumerInfo()

NATS_EXTERN natsStatus js_GetConsumerInfo ( jsConsumerInfo **  ci,
jsCtx js,
const char *  stream,
const char *  consumer,
jsOptions opts,
jsErrCode errCode 
)
Note
The returned object should be destroyed using jsConsumerInfo_Destroy in order to free allocated memory.
Parameters
cithe location where to store the pointer to the new jsConsumerInfo object.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
consumerthe name of the consumer.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_DeleteConsumer()

NATS_EXTERN natsStatus js_DeleteConsumer ( jsCtx js,
const char *  stream,
const char *  consumer,
jsOptions opts,
jsErrCode errCode 
)

Deletes the consumer named consumer from stream named stream.

Parameters
jsthe pointer to the jsCtx context.
streamthe name of the stream.
consumerthe name of the consumer.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ js_PauseConsumer()

NATS_EXTERN natsStatus js_PauseConsumer ( jsConsumerPauseResponse **  new_cpr,
jsCtx js,
const char *  stream,
const char *  consumer,
uint64_t  pauseUntil,
jsOptions opts,
jsErrCode errCode 
)

Pauses the consumer named consumer on stream named stream.

Parameters
new_cprif not NULL, will receive the response of the operation.
jsthe pointer to the jsCtx context.
streamthe name of the stream.
consumerthe name of the consumer.
pauseUntilthe time in nanoseconds since the Unix epoch to pause the consumer until.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsConsumerPauseResponse_Destroy()

NATS_EXTERN void jsConsumerPauseResponse_Destroy ( jsConsumerPauseResponse cpr)

Releases memory allocated for this object.

Parameters
cprthe pointer to the jsConsumerPauseResponse object.

◆ jsConsumerInfo_Destroy()

NATS_EXTERN void jsConsumerInfo_Destroy ( jsConsumerInfo ci)

Releases memory allocated for this consumer information object.

Parameters
cithe pointer to the jsConsumerInfo object.

◆ js_Consumers()

NATS_EXTERN natsStatus js_Consumers ( jsConsumerInfoList **  list,
jsCtx js,
const char *  stream,
jsOptions opts,
jsErrCode errCode 
)

Retrieves the list of all jsConsumerInfo for a given stream.

Warning
The list should be destroyed when no longer used by calling jsConsumerInfoList_Destroy.
Parameters
listthe location where to store the pointer to the new jsConsumerInfoList object.
jsthe pointer to the jsCtx context.
streamthe stream name whose consumer list is requested.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsConsumerInfoList_Destroy()

NATS_EXTERN void jsConsumerInfoList_Destroy ( jsConsumerInfoList list)

Releases memory allocated for this consumer information list.

Warning
All jsConsumerInfo pointers contained in the list will be destroyed by this call.
Parameters
listthe pointer to the jsConsumerInfoList object.

◆ js_ConsumerNames()

NATS_EXTERN natsStatus js_ConsumerNames ( jsConsumerNamesList **  list,
jsCtx js,
const char *  stream,
jsOptions opts,
jsErrCode errCode 
)

Retrieves the list of all consumer names for a given stream.

Warning
The list should be destroyed when no longer used by calling jsConsumerNamesList_Destroy.
Parameters
listthe location where to store the pointer to the new jsConsumerNamesList object.
jsthe pointer to the jsCtx context.
streamthe stream name whose consumer list is requested.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsConsumerNamesList_Destroy()

NATS_EXTERN void jsConsumerNamesList_Destroy ( jsConsumerNamesList list)

Releases memory allocated for this list of consumer names.

Warning
All string pointers contained in the list will be destroyed by this call.
Parameters
listthe pointer to the jsConsumerNamesList object.

◆ js_GetAccountInfo()

NATS_EXTERN natsStatus js_GetAccountInfo ( jsAccountInfo **  ai,
jsCtx js,
jsOptions opts,
jsErrCode errCode 
)

Retrieves information about the JetStream usage from an account.

Note
The returned object should be destroyed using jsAccountInfo_Destroy in order to free allocated memory.
Parameters
aithe location where to store the pointer to the new jsAccountInfo object in response to the account information request.
jsthe pointer to the jsCtx context.
optsthe pointer to the jsOptions object, possibly NULL.
errCodethe location where to store the JetStream specific error code, or NULL if not needed.

◆ jsAccountInfo_Destroy()

NATS_EXTERN void jsAccountInfo_Destroy ( jsAccountInfo ai)

Releases memory allocated for this account information object.

Parameters
aithe pointer to the jsAccountInfo object.