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

Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations
Types

## Classes
struct | natsMsgList
| A list of NATS messages. More...
struct | jsPubOptions
struct | jsPlacement
struct | jsExternalStream
struct | jsStreamSource
struct | jsRePublish
struct | jsStreamConfig
struct | jsLostStreamData
struct | jsStreamStateSubject
struct | jsStreamStateSubjects
struct | jsStreamState
struct | jsPeerInfo
struct | jsClusterInfo
struct | jsStreamSourceInfo
struct | jsStreamAlternate
struct | jsStreamInfo
struct | jsStreamInfoList
struct | jsStreamNamesList
struct | jsConsumerConfig
struct | jsConsumerSequenceMismatch
struct | jsSubOptions
struct | jsSequencePair
struct | jsSequenceInfo
struct | jsConsumerInfo
struct | jsConsumerInfoList
struct | jsConsumerNamesList
struct | jsAPIStats
struct | jsAccountLimits
struct | jsTier
struct | jsAccountInfo
struct | jsMsgMetaData
struct | jsPubAck
struct | jsPubAckErr
struct | jsDirectGetMsgOptions
struct | jsFetchRequest
struct | jsOptions
struct | kvConfig
struct | kvWatchOptions
struct | kvPurgeOptions
struct | kvEntryList
| A list of KeyValue store entries. More...
struct | kvKeysList
| A list of KeyValue store keys. More...

## Typedefs
typedef struct __natsConnection | natsConnection
| A connection to a `NATS Server`.
typedef struct __natsStatistics | natsStatistics
| Statistics of a natsConnection.
typedef struct __natsSubscription | natsSubscription
| Interest on a given subject.
typedef struct __natsMsg | natsMsg
| A structure holding a subject, optional reply and payload.
typedef struct __natsOptions | natsOptions
| Way to configure a natsConnection.
typedef char | natsInbox
| Unique subject often used for point-to-point communication.
typedef struct natsMsgList | natsMsgList
| A list of NATS messages.
typedef struct __jsCtx | jsCtx
typedef struct jsPubOptions | jsPubOptions
typedef struct jsPlacement | jsPlacement
typedef struct jsExternalStream | jsExternalStream
typedef struct jsStreamSource | jsStreamSource
typedef struct jsRePublish | jsRePublish
typedef struct jsStreamConfig | jsStreamConfig
typedef struct jsLostStreamData | jsLostStreamData
typedef struct jsStreamStateSubject | jsStreamStateSubject
typedef struct jsStreamStateSubjects | jsStreamStateSubjects
typedef struct jsStreamState | jsStreamState
typedef struct jsPeerInfo | jsPeerInfo
typedef struct jsClusterInfo | jsClusterInfo
typedef struct jsStreamSourceInfo | jsStreamSourceInfo
typedef struct jsStreamAlternate | jsStreamAlternate
typedef struct jsStreamInfo | jsStreamInfo
typedef struct jsStreamInfoList | jsStreamInfoList
typedef struct jsStreamNamesList | jsStreamNamesList
typedef struct jsConsumerConfig | jsConsumerConfig
typedef struct jsConsumerSequenceMismatch | jsConsumerSequenceMismatch
typedef struct jsSubOptions | jsSubOptions
typedef struct jsSequencePair | jsSequencePair
typedef struct jsSequenceInfo | jsSequenceInfo
typedef struct jsConsumerInfo | jsConsumerInfo
typedef struct jsConsumerInfoList | jsConsumerInfoList
typedef struct jsConsumerNamesList | jsConsumerNamesList
typedef struct jsAPIStats | jsAPIStats
typedef struct jsAccountLimits | jsAccountLimits
typedef struct jsTier | jsTier
typedef struct jsAccountInfo | jsAccountInfo
typedef struct jsMsgMetaData | jsMsgMetaData
typedef struct jsPubAck | jsPubAck
typedef struct jsPubAckErr | jsPubAckErr
typedef struct jsDirectGetMsgOptions | jsDirectGetMsgOptions
typedef struct jsFetchRequest | jsFetchRequest
typedef struct jsOptions | jsOptions
typedef struct __kvStore | kvStore
typedef struct __kvEntry | kvEntry
typedef struct __kvStatus | kvStatus
typedef struct __kvWatcher | kvWatcher
typedef struct kvConfig | kvConfig
typedef struct kvWatchOptions | kvWatchOptions
typedef struct kvPurgeOptions | kvPurgeOptions
typedef struct kvEntryList | kvEntryList
| A list of KeyValue store entries.
typedef struct kvKeysList | kvKeysList
| A list of KeyValue store keys.
typedef struct __stanConnection | stanConnection
| A connection to a `NATS Streaming Server`.
typedef struct __stanSubscription | stanSubscription
| Interest on a given channel.
typedef struct __stanMsg | stanMsg
| The Streaming message.
typedef struct __stanConnOptions | stanConnOptions
| Way to configure a stanConnection.
typedef struct __stanSubOptions | stanSubOptions
| Way to configure a stanSubscription.

## Enumerations
enum | jsRetentionPolicy { js_LimitsPolicy = 0 , js_InterestPolicy , js_WorkQueuePolicy }
enum | jsDiscardPolicy { js_DiscardOld = 0 , js_DiscardNew }
enum | jsStorageType { js_FileStorage = 0 , js_MemoryStorage }
enum | jsDeliverPolicy { js_DeliverAll = 0 , js_DeliverLast , js_DeliverNew , js_DeliverByStartSequence , js_DeliverByStartTime , js_DeliverLastPerSubject }
enum | jsAckPolicy { js_AckExplicit = 0 , js_AckNone , js_AckAll }
enum | jsReplayPolicy { js_ReplayInstant = 0 , js_ReplayOriginal }
enum | kvOperation { kvOp_Unknown = 0 , kvOp_Put , kvOp_Delete , kvOp_Purge }

## Detailed Description

NATS Types.

## Typedef Documentation

## ◆ natsConnection

typedef struct __natsConnection natsConnection

A natsConnection represents a bare connection to a `NATS Server`. It will send and receive byte array payloads.

## ◆ natsStatistics

typedef struct __natsStatistics natsStatistics

Tracks various statistics received and sent on a connection, including counts for messages and bytes.

## ◆ natsSubscription

typedef struct __natsSubscription natsSubscription

A natsSubscription represents interest in a given subject.

## ◆ natsMsg

typedef struct __natsMsg natsMsg

natsMsg is a structure used by Subscribers and natsConnection_PublishMsg().

## ◆ natsOptions

typedef struct __natsOptions natsOptions

Options can be used to create a customized natsConnection.

## ◆ natsInbox

typedef char natsInbox

This can be used as the reply for a request. Inboxes are meant to be unique so that replies can be sent to a specific subscriber. That being said, inboxes can be shared across multiple subscribers if desired.

## ◆ natsMsgList

typedef struct natsMsgList natsMsgList

Used by some APIs which return a list of natsMsg objects.

Those APIs will not create the object, but instead initialize the object to which a pointer to that object will be passed to it. Typically, the user will define the object on the stack and pass a pointer to this object to APIs that require a pointer to a natsMsgList object.

Similarly, calling natsMsgList_Destroy will call natsMsg_Destroy on any message still in the list, free the array containing pointers to the messages, but not free the natsMsgList object itself.

Note
  If the user wants to keep some of the messages from the list, the pointers of those messages in the `Msgs` array should be set to `NULL`. The value `Count` MUST not be changed. The function natsMsgList_Destroy will iterate through all pointers in the list and only destroy the ones that have not been set to `NULL`.

See also
  natsMsgList_Destroy

## ◆ jsCtx

typedef struct __jsCtx jsCtx

The JetStream context. Use for JetStream assets management and communication.

Warning
  A context MUST not be destroyed concurrently with jsCtx API calls (for instance js_Publish or js_PublishAsync, etc...). However, it is safe to destroy the context while a jsPubAckErrHandler callback is running or while inside js_PublishAsyncComplete.

## ◆ jsPubOptions

typedef struct jsPubOptions jsPubOptions

JetStream publish options.

These are options that you can provide to JetStream publish APIs.

The common usage will be to initialize a structure on the stack by calling jsPubOptions_Init. Note that strings are owned by the application and need to be valid for the duration of the API call this object is passed to.

Note
  It is the user responsibility to free the strings if they have been allocated.

See also
  jsPubOptions_Init

## ◆ jsPlacement

typedef struct jsPlacement jsPlacement

Used to guide placement of streams in clustered JetStream.

Initialize the object with jsPlacement_Init.

Note
  The strings are applications owned and will not be freed by the library.

See jsStreamConfig for information on how to configure a stream.

See also
  jsPlacement_Init

## ◆ jsExternalStream

typedef struct jsExternalStream jsExternalStream

Allows you to qualify access to a stream source in another account.

Initialize the object with jsExternalStream_Init.

Note
  The strings are applications owned and will not be freed by the library.

See jsStreamConfig for information on how to configure a stream.

## ◆ jsStreamSource

typedef struct jsStreamSource jsStreamSource

Dictates how streams can source from other streams.

Initialize the object with jsStreamSource_Init.

Note
  The strings are applications owned and will not be freed by the library.
  The `OptStartTime` needs to be expressed as the number of nanoseconds passed since 00:00:00 UTC Thursday, 1 January 1970.

See jsStreamConfig for information on how to configure a stream.

## ◆ jsRePublish

typedef struct jsRePublish jsRePublish

Allows a source subject to be mapped to a destination subject for republishing.

## ◆ jsStreamConfig

typedef struct jsStreamConfig jsStreamConfig

Configuration of a JetStream stream.

There are sensible defaults for most. If no subjects are given the name will be used as the only subject.

In order to add/update a stream, a configuration needs to be set. The typical usage would be to initialize all required objects on the stack and configure them, then pass the pointer to the configuration to js_AddStream or js_UpdateStream.

Note
  The strings are applications owned and will not be freed by the library.

See also
  jsStreamConfig_Init

jsStreamConfig sc;
jsPlacement p;
jsStreamSource m;
jsExternalStream esm;
jsStreamSource s1;
jsStreamSource s2;
jsExternalStream esmS2;
const char *subjects[] = {"foo", "bar"};
const char *tags[] = {"tag1", "tag2"};
jsStreamSource *sources[] = {&s1, &s2};
jsRePublish rp;
jsStreamConfig_Init(&sc);
jsPlacement_Init(&p);
p.Cluster = "MyCluster";
p.Tags = tags;
p.TagsLen = 2;
jsStreamSource_Init(&m);
m.Name = "AStream";
m.OptStartSeq = 100;
m.FilterSubject = "foo";
jsExternalStream_Init(&esm);
esm.APIPrefix = "mirror.prefix.";
esm.DeliverPrefix = "deliver.prefix.";
m.External = &esm;
jsStreamSource_Init(&s1);
s1.Name = "StreamOne";
s1.OptStartSeq = 10;
s1.FilterSubject = "stream.one";
jsStreamSource_Init(&s2);
s2.Name = "StreamTwo";
s2.FilterSubject = "stream.two";
jsExternalStream_Init(&esmS2);
esmS2.APIPrefix = "mirror.prefix.";
esmS2.DeliverPrefix = "deliver.prefix.";
s2.External = &esmS2;
sc.Name = "MyStream";
sc.Subjects = subjects;
sc.SubjectsLen = 2;
sc.Retention = js_InterestPolicy;
sc.Replicas = 3;
sc.Placement = &p;
sc.Mirror = &m;
sc.Sources = sources;
sc.SourcesLen = 2;
// For RePublish subject:
jsRePublish_Init(&rp);
rp.Source = ">";
rp.Destination = "RP.>";
sc.RePublish = &rp;
s = js_AddStream(&si, js, &sc, NULL, &jerr);

## ◆ jsLostStreamData

typedef struct jsLostStreamData jsLostStreamData

Information about messages that have been lost

## ◆ jsStreamStateSubject

typedef struct jsStreamStateSubject jsStreamStateSubject

This indicate that the given `Subject` in a stream contains `Msgs` messages.

See also
  jsStreamStateSubjects

## ◆ jsStreamStateSubjects

typedef struct jsStreamStateSubjects jsStreamStateSubjects

List of subjects optionally returned in the stream information request.

This structure indicates the number of elements in the list, that is, the list contains `Count` jsStreamStateSubject elements.

To get this list in jsStreamState, you have to ask for it through jsOptions.

jsStreamInfo *si = NULL;
jsOptions o;
jsOptions_Init(&o);
o.Stream.Info.SubjectsFilter = "foo.>";
s = js_GetStreamInfo(&si, js, "MY_STREAM", &o, &jerr);
// handle errors and assume si->State.Subjects is not NULL
for (i=0; i<si->State.Subjects->Count; i++)
{
jsStreamStateSubject *subj = &(si->State.Subjects->List[i]);
printf("Subject=%s Messages count=%d\n", subj->Subject, (int) subj->Msgs);
}

See also
  jsStreamStateSubject
  js_GetStreamInfo
  jsOptions.Stream.Info.SubjectsFilter

## ◆ jsStreamState

typedef struct jsStreamState jsStreamState

Information about the given stream

Note
  `FirstTime` and `LastTime` are message timestamps expressed as the number of nanoseconds passed since 00:00:00 UTC Thursday, 1 January 1970.

## ◆ jsPeerInfo

typedef struct jsPeerInfo jsPeerInfo

Information about all the peers in the cluster that are supporting the stream or consumer.

## ◆ jsClusterInfo

typedef struct jsClusterInfo jsClusterInfo

Information about the underlying set of servers that make up the stream or consumer.

## ◆ jsStreamSourceInfo

typedef struct jsStreamSourceInfo jsStreamSourceInfo

Information about an upstream stream source.

## ◆ jsStreamAlternate

typedef struct jsStreamAlternate jsStreamAlternate

Information about an alternate stream represented by a mirror.

## ◆ jsStreamInfo

typedef struct jsStreamInfo jsStreamInfo

Configuration and current state for this stream.

Note
  `Created` is the timestamp when the stream was created, expressed as the number of nanoseconds passed since 00:00:00 UTC Thursday, 1 January 1970.

## ◆ jsStreamInfoList

typedef struct jsStreamInfoList jsStreamInfoList

List of stream information objects returned by js_Streams

Note
  Once done, the list should be destroyed calling jsStreamInfoList_Destroy

See also
  jsStreamInfoList_Destroy

## ◆ jsStreamNamesList

typedef struct jsStreamNamesList jsStreamNamesList

List of stream names returned by js_StreamNames

Note
  Once done, the list should be destroyed calling jsStreamNamesList_Destroy

See also
  jsStreamNamesList_Destroy

## ◆ jsConsumerConfig

typedef struct jsConsumerConfig jsConsumerConfig

Configuration of a JetStream consumer.

In order to add a consumer, a configuration needs to be set. The typical usage would be to initialize all required objects on the stack and configure them, then pass the pointer to the configuration to js_AddConsumer.

Note
  `OptStartTime` needs to be expressed as the number of nanoseconds passed since 00:00:00 UTC Thursday, 1 January 1970.
  The strings are applications owned and will not be freed by the library.
  `SampleFrequency` is a sampling value, represented as a string such as "50" for 50%, that causes the server to produce advisories for consumer ack metrics.
  `Durable` cannot contain the character ".".
  `HeadersOnly` means that the subscription will not receive any message payload, instead, it will receive only messages headers (if present) with the addition of the header JSMsgSize ("Nats-Msg-Size"), whose value is the payload size.

See also
  jsConsumerConfig_Init

jsConsumerInfo *ci = NULL;
jsConsumerConfig cc;
jsConsumerConfig_Init(&cc);
cc.Durable = "MY_DURABLE";
cc.DeliverSubject = "foo";
cc.DeliverPolicy = js_DeliverNew;
s = js_AddConsumer(&ci, js, &cc, NULL, &jerr);

## ◆ jsConsumerSequenceMismatch

typedef struct jsConsumerSequenceMismatch jsConsumerSequenceMismatch

This represents a consumer sequence mismatch between the server and client views.

This can help applications find out if messages have been missed. Without this and during a disconnect, it would be possible that a subscription is not aware that it missed messages from the server. When acknowledgment mode is other than js_AckNone, messages would ultimately be redelivered, but for js_AckNone, they would not. But even with an acknowledgment mode this may help finding sooner that something went wrong and let the application decide if it wants to recreate the subscription starting at a given sequence.

The gap of missing messages could be calculated as `ConsumerServer-ConsumerClient`.

See also
  natsSubscription_GetSequenceMismatch

## ◆ jsSubOptions

typedef struct jsSubOptions jsSubOptions

JetStream subscribe options.

These are options that you can provide to JetStream subscribe APIs.

The common usage will be to initialize a structure on the stack by calling jsSubOptions_Init. Note that strings are owned by the application and need to be valid for the duration of the API call this object is passed to.

Note
  It is the user responsibility to free the strings if they have been allocated.

See also
  jsSubOptions_Init

## ◆ jsSequencePair

typedef struct jsSequencePair jsSequencePair

Includes the consumer and stream sequence info from a JetStream consumer.

## ◆ jsSequenceInfo

typedef struct jsSequenceInfo jsSequenceInfo

Has both the consumer and the stream sequence and last activity.

## ◆ jsConsumerInfo

typedef struct jsConsumerInfo jsConsumerInfo

Configuration and current state for this consumer.

Note
  `Created` is the timestamp when the consumer was created, expressed as the number of nanoseconds passed since 00:00:00 UTC Thursday, 1 January 1970.

## ◆ jsConsumerInfoList

typedef struct jsConsumerInfoList jsConsumerInfoList

List of consumers information objects returned by js_Consumers

Note
  Once done, the list should be destroyed calling jsConsumerInfoList_Destroy

See also
  jsStreamInfoList_Destroy

## ◆ jsConsumerNamesList

typedef struct jsConsumerNamesList jsConsumerNamesList

List of consumer names returned by js_ConsumerNames

Note
  Once done, the list should be destroyed calling jsConsumerNamesList_Destroy

See also
  jsConsumerNamesList_Destroy

## ◆ jsAPIStats

typedef struct jsAPIStats jsAPIStats

Reports on API calls to JetStream for this account.

## ◆ jsAccountLimits

typedef struct jsAccountLimits jsAccountLimits

Includes the JetStream limits of the current account.

## ◆ jsTier

typedef struct jsTier jsTier

## ◆ jsAccountInfo

typedef struct jsAccountInfo jsAccountInfo

Information about the JetStream usage from the current account.

## ◆ jsMsgMetaData

typedef struct jsMsgMetaData jsMsgMetaData

This represents the JetStream metadata associated with received messages.

See also
  natsMsg_GetMetaData
  jsMsgMetaData_Destroy

## ◆ jsPubAck

typedef struct jsPubAck jsPubAck

Ack received after successfully publishing a message.

## ◆ jsPubAckErr

typedef struct jsPubAckErr jsPubAckErr

Publish acknowledgment failure that will be passed to the optional jsPubAckErrHandler callback.

## ◆ jsDirectGetMsgOptions

typedef struct jsDirectGetMsgOptions jsDirectGetMsgOptions

Options for the js_DirectGetMsg() call, which retrieves a message from any server (not only the leader) as long as the stream has been created with a AllowDirect option.

Note that some options are mutually exclusive but are not checked byt the library. The server will reject invalid requests and the library will return the error returned from the server.

## ◆ jsFetchRequest

typedef struct jsFetchRequest jsFetchRequest

Options for the natsSubscription_FetchRequest() call, which is similar to natsSubscription_Fetch() but gives more control in the configuration of the fetch.

## ◆ jsOptions

typedef struct jsOptions jsOptions

JetStream context options.

Initialize the object with jsOptions_Init.

## ◆ kvStore

typedef struct __kvStore kvStore

The KeyValue store object.

## ◆ kvEntry

typedef struct __kvEntry kvEntry

The KeyValue entry object.

## ◆ kvStatus

typedef struct __kvStatus kvStatus

The KeyValue status object.

## ◆ kvWatcher

typedef struct __kvWatcher kvWatcher

The KeyValue watcher object.

## ◆ kvConfig

typedef struct kvConfig kvConfig

KeyValue configuration object.

Initialize the object with kvConfig_Init.

## ◆ kvWatchOptions

typedef struct kvWatchOptions kvWatchOptions

KeyValue watcher options object.

Initialize the object with kvWatchOptions_Init

## ◆ kvPurgeOptions

typedef struct kvPurgeOptions kvPurgeOptions

KeyValue purge options object.

Initialize the object with kvPurgeOptions_Init

## ◆ kvEntryList

typedef struct kvEntryList kvEntryList

Used by some APIs which return a list of kvEntry objects.

Those APIs will not create the object, but instead initialize the object.

Typically, the user will define the object on the stack and pass a pointer to this object to APIs that require a pointer to a kvEntryList object.

Similarly, calling kvEntryList_Destroy will call kvEntry_Destroy on entries in the list, free the array containing pointers to the entries, but not free the kvEntryList object itself.

See also
  kvEntryList_Destroy

## ◆ kvKeysList

typedef struct kvKeysList kvKeysList

Used by some APIs which return a list of key names.

Those APIs will not create the object, but instead initialize the object.

Typically, the user will define the object on the stack and pass a pointer to this object to APIs that require a pointer to a kvKeysList object.

Similarly, calling kvKeysList_Destroy will free key strings in the list, free the array containing pointers to the keys, but not free the kvKeysList object itself.

See also
  kvKeysList_Cleanup

## ◆ stanConnection

typedef struct __stanConnection stanConnection

A stanConnection represents a connection to a `NATS Streaming Server`.

## ◆ stanSubscription

typedef struct __stanSubscription stanSubscription

A stanSubscription represents interest in a given channel.

## ◆ stanMsg

typedef struct __stanMsg stanMsg

stanMsg is the object passed to the subscriptions' message callbacks.

## ◆ stanConnOptions

typedef struct __stanConnOptions stanConnOptions

Options can be used to create a customized stanConnection.

## ◆ stanSubOptions

typedef struct __stanSubOptions stanSubOptions

Options can be used to create a customized stanSubscription.

## Enumeration Type Documentation

## ◆ jsRetentionPolicy

enum jsRetentionPolicy

Determines how messages in a set are retained.

Enumerator
js_LimitsPolicy | Specifies that messages are retained until any given limit is reached, which could be one of MaxMsgs, MaxBytes, or MaxAge. This is the default.
js_InterestPolicy | Specifies that when all known observables have acknowledged a message it can be removed.
js_WorkQueuePolicy | Specifies that when the first worker or subscriber acknowledges the message it can be removed.

## ◆ jsDiscardPolicy

enum jsDiscardPolicy

Determines how to proceed when limits of messages or bytes are reached.

Enumerator
js_DiscardOld | Will remove older messages to return to the limits. This is the default.
js_DiscardNew | Will fail to store new messages.

## ◆ jsStorageType

enum jsStorageType

Determines how messages are stored for retention.

Enumerator
js_FileStorage | Specifies on disk storage. It's the default.
js_MemoryStorage | Specifies in memory only.

## ◆ jsDeliverPolicy

enum jsDeliverPolicy

Determines how the consumer should select the first message to deliver.

Enumerator
js_DeliverAll | Starts from the very beginning of a stream. This is the default.
js_DeliverLast | Starts with the last sequence received.
js_DeliverNew | Starts with messages sent after the consumer is created.
js_DeliverByStartSequence | Starts from a given sequence.
js_DeliverByStartTime | Starts from a given UTC time (number of nanoseconds since epoch)
js_DeliverLastPerSubject | Starts with the last message for all subjects received.

## ◆ jsAckPolicy

enum jsAckPolicy

Determines how the consumer should acknowledge delivered messages.

Enumerator
js_AckExplicit | Requires ack or nack for all messages.
js_AckNone | Requires no acks for delivered messages.
js_AckAll | When acking a sequence number, this implicitly acks all sequences below this one as well.

## ◆ jsReplayPolicy

enum jsReplayPolicy

Determines how the consumer should replay messages it already has queued in the stream.

Enumerator
js_ReplayInstant | Replays messages as fast as possible.
js_ReplayOriginal | Maintains the same timing as the messages were received.

## ◆ kvOperation

enum kvOperation

Determines the type of operation of a kvEntry

Enumerator
kvOp_Unknown |
kvOp_Put |
kvOp_Delete |
kvOp_Purge |