NATS C Client with JetStream and Streaming support: Streaming Subscription Options

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

Loading...
Searching...
No Matches
Functions
Streaming Subscription Options
Functions

## Functions
NATS_EXTERN natsStatus | stanSubOptions_Create (stanSubOptions **newOpts)
| Creates a stanSubOptions object. More...
NATS_EXTERN natsStatus | stanSubOptions_SetDurableName (stanSubOptions *opts, const char *durableName)
| Sets the Durable Name for this subscription. More...
NATS_EXTERN natsStatus | stanSubOptions_SetAckWait (stanSubOptions *opts, int64_t wait)
| Sets the timeout for waiting for an ACK from the cluster's point of view for delivered messages. More...
NATS_EXTERN natsStatus | stanSubOptions_SetMaxInflight (stanSubOptions *opts, int maxInflight)
| Sets the the maximum number of messages the cluster will send without an ACK. More...
NATS_EXTERN natsStatus | stanSubOptions_StartAtSequence (stanSubOptions *opts, uint64_t seq)
| Sets the desired start position based on the given sequence number. More...
NATS_EXTERN natsStatus | stanSubOptions_StartAtTime (stanSubOptions *opts, int64_t time)
| Sets the desired start position based on the given time. More...
NATS_EXTERN natsStatus | stanSubOptions_StartAtTimeDelta (stanSubOptions *opts, int64_t delta)
| Sets the desired start position based on the given delta. More...
NATS_EXTERN natsStatus | stanSubOptions_StartWithLastReceived (stanSubOptions *opts)
| The subscription should start with the last message in the channel. More...
NATS_EXTERN natsStatus | stanSubOptions_DeliverAllAvailable (stanSubOptions *opts)
| The subscription should start with the first message in the channel. More...
NATS_EXTERN natsStatus | stanSubOptions_SetManualAckMode (stanSubOptions *opts, bool manual)
| Sets the subscription's acknowledgment mode. More...
NATS_EXTERN void | stanSubOptions_Destroy (stanSubOptions *opts)
| Destroys a stanSubOptions object. More...

## Detailed Description

NATS Streaming Subscription Options.

## Function Documentation

## ◆ stanSubOptions_Create()

NATS_EXTERN natsStatus stanSubOptions_Create | ( | stanSubOptions ** | newOpts | ) |

Creates a stanSubOptions object. This object is used when one wants to set specific options prior to create a subscription.

After making the appropriate `stanSubOptions_SetXXX()` calls, this object is passed to the stanConnection_Subscribe() or stanConnection_QueueSubscribe() call, which will clone this object. It means that modifications to the options object will not affect the created subscription.

The default options set in this call are: ackWait: 30000 milliseconds (30 seconds) maxIinflight: 1024 start position: new only

Note
  The object needs to be destroyed when no longer needed.

See also
  stanConnection_Subscribe()
  stanConnection_QueueSubscribe()
  stanSubOptions_Destroy()

Parameters

  newOpts | the location where store the pointer to the newly created stanSubOptions object.

## ◆ stanSubOptions_SetDurableName()

NATS_EXTERN natsStatus stanSubOptions_SetDurableName | ( | stanSubOptions * | opts,
|  | const char * | durableName
| ) |  |

If a durable name is set, this subscription will be durable. It means that if the application stops and re-create the same subscription with the same connection client ID and durable name (or simply durable name for queue subscriptions), then the server will resume (re)delivery of messages from the last known position in the steam for that durable.

It means that the start position, if provided, is used only when the durable subscription is first created, then is ignored by the server for the rest of the durable subscription lifetime.

Note
  Durable names should be alphanumeric and not contain the character `:`.

Parameters

  opts | the pointer to the stanSubOptions object.
  durableName | the string representing the name of the durable subscription.

## ◆ stanSubOptions_SetAckWait()

NATS_EXTERN natsStatus stanSubOptions_SetAckWait | ( | stanSubOptions * | opts,
|  | int64_t | wait
| ) |  |

Value expressed in milliseconds.

Default is 30000 milliseconds (30 seconds).

If the server does not receive an acknowledgment from the subscription for a delivered message after this amount of time, the server will re-deliver the unacknowledged message.

Parameters

  opts | the pointer to the stanSubOptions object.
  wait | how long the server will wait for an acknowledgment from the subscription.

## ◆ stanSubOptions_SetMaxInflight()

NATS_EXTERN natsStatus stanSubOptions_SetMaxInflight | ( | stanSubOptions * | opts,
|  | int | maxInflight
| ) |  |

Default is 1024.

If a subscription receives messages but does not acknowledge them, the server will stop sending new messages when it reaches this number. Unacknowledged messages are re-delivered regardless of that setting.

Parameters

  opts | the pointer to the stanSubOptions object.
  maxInflight | the maximum number of messages the subscription will receive without sending back ACKs.

## ◆ stanSubOptions_StartAtSequence()

NATS_EXTERN natsStatus stanSubOptions_StartAtSequence | ( | stanSubOptions * | opts,
|  | uint64_t | seq
| ) |  |

This allows the subscription to start at a specific sequence number in the channel's message log.

If the sequence is smaller than the first available message in the message log (old messages dropped due to channel limits), the subscription will be created with the first available sequence.

Conversely, if the given sequence is higher than the currently last sequence number, the subscription will receive only new published messages.

Parameters

  opts | the pointer to the stanSubOptions object.
  seq | the starting sequence.

## ◆ stanSubOptions_StartAtTime()

NATS_EXTERN natsStatus stanSubOptions_StartAtTime | ( | stanSubOptions * | opts,
|  | int64_t | time
| ) |  |

When the subscription is created, the server will send messages starting with the message which timestamp is at least the given time. The time is expressed in number of milliseconds since the EPOCH, as given by nats_Now() for instance.

If the time is in the past and the most recent message's timestamp is older than the given time, or if the time is in the future, the subscription will receive only new messages.

Parameters

  opts | the pointer to the stanSubOptions object.
  time | the start time, expressed in milliseconds since the EPOCH.

## ◆ stanSubOptions_StartAtTimeDelta()

NATS_EXTERN natsStatus stanSubOptions_StartAtTimeDelta | ( | stanSubOptions * | opts,
|  | int64_t | delta
| ) |  |

When the subscription is created, the server will send messages starting with the message which timestamp is at least now minus `delta`. In other words, this means start receiving messages that were sent n milliseconds ago.

The delta is expressed in milliseconds.

Parameters

  opts | the pointer to the stanSubOptions object.
  delta | he historical time delta (from now) from which to start receiving messages.

## ◆ stanSubOptions_StartWithLastReceived()

NATS_EXTERN natsStatus stanSubOptions_StartWithLastReceived | ( | stanSubOptions * | opts | ) |

When the subscription is created, the server will start sending messages starting with the last message currently in the channel message's log. The subscription will then receive any new published message.

Parameters

  opts | the pointer to the stanSubOptions object.

## ◆ stanSubOptions_DeliverAllAvailable()

NATS_EXTERN natsStatus stanSubOptions_DeliverAllAvailable | ( | stanSubOptions * | opts | ) |

When the subscription is created, the server will start sending messages starting with the first message currently in the channel message's log.

Parameters

  opts | the pointer to the stanSubOptions object.

## ◆ stanSubOptions_SetManualAckMode()

NATS_EXTERN natsStatus stanSubOptions_SetManualAckMode | ( | stanSubOptions * | opts,
|  | bool | manual
| ) |  |

By default, a subscription will automatically send a message acknowledgment after the stanMsgHandler callback returns.

In order to control when the acknowledgment is sent, set the acknowledgment mode to `manual` and call stanSubscription_AckMsg().

See also
  stanSubscription_AckMsg()

Parameters

  opts | the pointer to the stanSubOptions object.
  manual | a boolean indicating if the subscription should auto-acknowledge or if the user will.

## ◆ stanSubOptions_Destroy()

NATS_EXTERN void stanSubOptions_Destroy | ( | stanSubOptions * | opts | ) |

Destroys the stanSubOptions object, freeing used memory. See the note in the stanSubOptions_Create() call.

Parameters

  opts | the pointer to the stanSubOptions object to destroy.