Streaming Subscription Options

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

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.