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

Functions
Subscription
Functions

## Functions
NATS_EXTERN natsStatus | natsSubscription_NoDeliveryDelay (natsSubscription *sub)
| Enables the No Delivery Delay mode. More...
NATS_EXTERN natsStatus | natsSubscription_NextMsg (natsMsg **nextMsg, natsSubscription *sub, int64_t timeout)
| Returns the next available message. More...
NATS_EXTERN natsStatus | natsSubscription_Unsubscribe (natsSubscription *sub)
| Unsubscribes. More...
NATS_EXTERN natsStatus | natsSubscription_AutoUnsubscribe (natsSubscription *sub, int max)
| Auto-Unsubscribes. More...
NATS_EXTERN natsStatus | natsSubscription_QueuedMsgs (natsSubscription *sub, uint64_t *queuedMsgs)
| Gets the number of pending messages. More...
NATS_EXTERN int64_t | natsSubscription_GetID (natsSubscription *sub)
| Gets the subscription id. More...
NATS_EXTERN const char * | natsSubscription_GetSubject (natsSubscription *sub)
| Gets the subject name. More...
NATS_EXTERN natsStatus | natsSubscription_SetPendingLimits (natsSubscription *sub, int msgLimit, int bytesLimit)
| Sets the limit for pending messages and bytes. More...
NATS_EXTERN natsStatus | natsSubscription_GetPendingLimits (natsSubscription *sub, int *msgLimit, int *bytesLimit)
| Returns the current limit for pending messages and bytes. More...
NATS_EXTERN natsStatus | natsSubscription_GetPending (natsSubscription *sub, int *msgs, int *bytes)
| Returns the number of pending messages and bytes. More...
NATS_EXTERN natsStatus | natsSubscription_GetDelivered (natsSubscription *sub, int64_t *msgs)
| Returns the number of delivered messages. More...
NATS_EXTERN natsStatus | natsSubscription_GetDropped (natsSubscription *sub, int64_t *msgs)
| Returns the number of dropped messages. More...
NATS_EXTERN natsStatus | natsSubscription_GetMaxPending (natsSubscription *sub, int *msgs, int *bytes)
| Returns the maximum number of pending messages and bytes. More...
NATS_EXTERN natsStatus | natsSubscription_ClearMaxPending (natsSubscription *sub)
| Clears the statistics regarding the maximum pending values. More...
NATS_EXTERN natsStatus | natsSubscription_GetStats (natsSubscription *sub, int *pendingMsgs, int *pendingBytes, int *maxPendingMsgs, int *maxPendingBytes, int64_t *deliveredMsgs, int64_t *droppedMsgs)
| Get various statistics from this subscription. More...
NATS_EXTERN bool | natsSubscription_IsValid (natsSubscription *sub)
| Checks the validity of the subscription. More...
NATS_EXTERN natsStatus | natsSubscription_Drain (natsSubscription *sub)
| Drains the subscription with a default timeout. More...
NATS_EXTERN natsStatus | natsSubscription_DrainTimeout (natsSubscription *sub, int64_t timeout)
| Drains the subscription with the specified timeout. More...
NATS_EXTERN natsStatus | natsSubscription_WaitForDrainCompletion (natsSubscription *sub, int64_t timeout)
| Blocks until the drain operation completes. More...
NATS_EXTERN natsStatus | natsSubscription_DrainCompletionStatus (natsSubscription *sub)
| Returns the status of the drain after completion. More...
NATS_EXTERN natsStatus | natsSubscription_SetOnCompleteCB (natsSubscription *sub, natsOnCompleteCB cb, void *closure)
| Sets a completion callback. More...
NATS_EXTERN void | natsSubscription_Destroy (natsSubscription *sub)
| Destroys the subscription. More...

## Detailed Description

NATS Subscriptions.

## Function Documentation

## ◆ natsSubscription_NoDeliveryDelay()

NATS_EXTERN natsStatus natsSubscription_NoDeliveryDelay | ( | natsSubscription * | sub | ) |

By default, messages that arrive are not immediately delivered. This generally improves performance. However, in case of request-reply, this delay has a negative impact. In such case, call this function to have the subscriber be notified immediately each time a message arrives.

Parameters

  sub | the pointer to the natsSubscription object.

Deprecated:
  No longer needed. Will be removed in the future.

## ◆ natsSubscription_NextMsg()

NATS_EXTERN natsStatus natsSubscription_NextMsg | ( | natsMsg ** | nextMsg,
|  | natsSubscription * | sub,
|  | int64_t | timeout
| ) |  |

Return the next message available to a synchronous subscriber or block until one is available. A timeout (expressed in milliseconds) can be used to return when no message has been delivered. If the value is zero, then this call will not wait and return the next message that was pending in the client, and NATS_TIMEOUT otherwise.

Note
  If you create a subscription for a subject used as the reply subject of a natsConnection_PublishRequest call (or any of its variant), and there are no responders for the request subject, NATS Servers v2.2.0+ will return an empty message with a header "Status" and value "503". The library v2.2.0 until v2.4.1 would return this message to the user, which was wrong.
  The library now returns no message and NATS_NO_RESPONDERS status.

Parameters

  nextMsg | the location where to store the pointer to the next available message.
  sub | the pointer to the natsSubscription object.
  timeout | time, in milliseconds, after which this call will return NATS_TIMEOUT if no message is available.

## ◆ natsSubscription_Unsubscribe()

NATS_EXTERN natsStatus natsSubscription_Unsubscribe | ( | natsSubscription * | sub | ) |

Removes interest on the subject. Asynchronous subscription may still have a callback in progress, in that case, the subscription will still be valid until the callback returns.

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_AutoUnsubscribe()

NATS_EXTERN natsStatus natsSubscription_AutoUnsubscribe | ( | natsSubscription * | sub,
|  | int | max
| ) |  |

This call issues an automatic natsSubscription_Unsubscribe that is processed by the server when 'max' messages have been received. This can be useful when sending a request to an unknown number of subscribers.

Parameters

  sub | the pointer to the natsSubscription object.
  max | the maximum number of message you want this subscription to receive.

## ◆ natsSubscription_QueuedMsgs()

NATS_EXTERN natsStatus natsSubscription_QueuedMsgs | ( | natsSubscription * | sub,
|  | uint64_t * | queuedMsgs
| ) |  |

Returns the number of queued messages in the client for this subscription.

Deprecated:
  Use natsSubscription_GetPending instead.

Parameters

  sub | the pointer to the natsSubscription object.
  queuedMsgs | the location where to store the number of queued messages.

## ◆ natsSubscription_GetID()

NATS_EXTERN int64_t natsSubscription_GetID | ( | natsSubscription * | sub | ) |

Returns the id of the given subscription.

Note
  Invalid or closed subscriptions will cause a value of 0 to be returned.

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_GetSubject()

NATS_EXTERN const char* natsSubscription_GetSubject | ( | natsSubscription * | sub | ) |

Returns the subject of the given subscription.

Note
  Invalid or closed subscriptions will cause a value of NULL to be returned.

Warning
  The string belongs to the subscription and must not be freed. Copy it if needed.

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_SetPendingLimits()

NATS_EXTERN natsStatus natsSubscription_SetPendingLimits | ( | natsSubscription * | sub,
|  | int | msgLimit,
|  | int | bytesLimit
| ) |  |

Specifies the maximum number and size of incoming messages that can be buffered in the library for this subscription, before new incoming messages are dropped and NATS_SLOW_CONSUMER status is reported to the natsErrHandler callback (if one has been set).

If no limit is set at the subscription level, the limit set by natsOptions_SetMaxPendingMsgs before creating the connection will be used.

Note
  If no option is set, there is still a default of `65536` messages and `65536 * 1024` bytes.

See also
  natsOptions_SetMaxPendingMsgs
  natsSubscription_GetPendingLimits

Parameters

  sub | he pointer to the natsSubscription object.
  msgLimit | the limit in number of messages that the subscription can hold.
  bytesLimit | the limit in bytes that the subscription can hold.

## ◆ natsSubscription_GetPendingLimits()

NATS_EXTERN natsStatus natsSubscription_GetPendingLimits | ( | natsSubscription * | sub,
|  | int * | msgLimit,
|  | int * | bytesLimit
| ) |  |

Regardless if limits have been explicitly set with natsSubscription_SetPendingLimits, this call will store in the provided memory locations, the limits set for this subscription.

Note
  It is possible for `msgLimit` and/or `bytesLimits` to be `NULL`, in which case the corresponding value is obviously not stored, but the function will not return an error.

See also
  natsOptions_SetMaxPendingMsgs
  natsSubscription_SetPendingLimits

Parameters

  sub | the pointer to the natsSubscription object.
  msgLimit | if not `NULL`, the memory location where to store the maximum number of pending messages for this subscription.
  bytesLimit | if not `NULL`, the memory location where to store the maximum size of pending messages for this subscription.

## ◆ natsSubscription_GetPending()

NATS_EXTERN natsStatus natsSubscription_GetPending | ( | natsSubscription * | sub,
|  | int * | msgs,
|  | int * | bytes
| ) |  |

Returns the total number and size of pending messages on this subscription.

Note
  It is possible for `msgs` and `bytes` to be NULL, in which case the corresponding values are obviously not stored, but the function will not return an error.

Parameters

  sub | the pointer to the natsSubscription object.
  msgs | if not `NULL`, the memory location where to store the number of pending messages.
  bytes | if not `NULL`, the memory location where to store the total size of pending messages.

## ◆ natsSubscription_GetDelivered()

NATS_EXTERN natsStatus natsSubscription_GetDelivered | ( | natsSubscription * | sub,
|  | int64_t * | msgs
| ) |  |

Returns the number of delivered messages for this subscription.

Parameters

  sub | the pointer to the natsSubscription object.
  msgs | the memory location where to store the number of delivered messages.

## ◆ natsSubscription_GetDropped()

NATS_EXTERN natsStatus natsSubscription_GetDropped | ( | natsSubscription * | sub,
|  | int64_t * | msgs
| ) |  |

Returns the number of known dropped messages for this subscription. This happens when a consumer is not keeping up and the library starts to drop messages when the maximum number (and/or size) of pending messages has been reached.

Note
  If the server declares the connection a slow consumer, this number may not be valid.

See also
  natsOptions_SetMaxPendingMsgs
  natsSubscription_SetPendingLimits

Parameters

  sub | the pointer to the natsSubscription object.
  msgs | the memory location where to store the number of dropped messages.

## ◆ natsSubscription_GetMaxPending()

NATS_EXTERN natsStatus natsSubscription_GetMaxPending | ( | natsSubscription * | sub,
|  | int * | msgs,
|  | int * | bytes
| ) |  |

Returns the maximum of pending messages and bytes seen so far.

Note
  `msgs` and/or `bytes` can be NULL.

Parameters

  sub | the pointer to the natsSubscription object.
  msgs | if not `NULL`, the memory location where to store the maximum number of pending messages seen so far.
  bytes | if not `NULL`, the memory location where to store the maximum number of bytes pending seen so far.

## ◆ natsSubscription_ClearMaxPending()

NATS_EXTERN natsStatus natsSubscription_ClearMaxPending | ( | natsSubscription * | sub | ) |

Clears the statistics regarding the maximum pending values.

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_GetStats()

NATS_EXTERN natsStatus natsSubscription_GetStats | ( | natsSubscription * | sub,
|  | int * | pendingMsgs,
|  | int * | pendingBytes,
|  | int * | maxPendingMsgs,
|  | int * | maxPendingBytes,
|  | int64_t * | deliveredMsgs,
|  | int64_t * | droppedMsgs
| ) |  |

This is a convenient function to get several subscription's statistics in one call.

Note
  Any or all of the statistics pointers can be `NULL`.

See also
  natsSubscription_GetPending
  natsSubscription_GetMaxPending
  natsSubscription_GetDelivered
  natsSubscription_GetDropped

Parameters

  sub | the pointer to the natsSubscription object.
  pendingMsgs | if not `NULL`, memory location where to store the number of pending messages.
  pendingBytes | if not `NULL`, memory location where to store the total size of pending messages.
  maxPendingMsgs | if not `NULL`, memory location where to store the maximum number of pending messages seen so far.
  maxPendingBytes | if not `NULL`, memory location where to store the maximum total size of pending messages seen so far.
  deliveredMsgs | if not `NULL`, memory location where to store the number of delivered messages.
  droppedMsgs | if not `NULL`, memory location where to store the number of dropped messages.

## ◆ natsSubscription_IsValid()

NATS_EXTERN bool natsSubscription_IsValid | ( | natsSubscription * | sub | ) |

Returns a boolean indicating whether the subscription is still active. This will return false if the subscription has already been closed, or auto unsubscribed.

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_Drain()

NATS_EXTERN natsStatus natsSubscription_Drain | ( | natsSubscription * | sub | ) |

Drain will remove interest but continue to invoke callbacks until all messages have been processed.

This call uses a default drain timeout of 30 seconds. See natsSubscription_DrainTimeout for details on behavior when timeout elapses.

Warning
  This function does not block waiting for the operation to complete. To synchronously wait, see natsSubscription_WaitForDrainCompletion

See also
  natsSubscription_DrainTimeout
  natsSubscription_WaitForDrainCompletion
  natsSubscription_DrainCompletionStatus

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_DrainTimeout()

NATS_EXTERN natsStatus natsSubscription_DrainTimeout | ( | natsSubscription * | sub,
|  | int64_t | timeout
| ) |  |

Drain will remove interest but continue to invoke callbacks until all messages have been processed, or the specified timeout has elapsed. In that case, the subscription will be forcibly closed and remaining pending messages (if any) will not be processed.

The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout, but see below for more details.

When this call returns, the UNSUBSCRIBE protocol for this subscription has been enqueued to the outgoing connection buffer, but not sent to the server, ensuring that this call does not block.

The library then asynchronously ensures that this protocol is sent and waits for a confirmation from the server. After that, it is guaranteed that no new message for this subscription will be received and the library can proceed with the rest of the draining.

However, should the "flush" of the protocol fail, the library will ensure that no new message is added to the subscription (in the event the server did not receive the UNSUBSCRIBE protocol and still attempts to deliver messages), and will proceed with the draining of the pending messages. Users can check the status of the draining after it has completed by calling natsSubscription_DrainCompletionStatus.

If no timeout is specified (that is, value is zero or negative), a timeout will be used for the "flush" of the protocol. Again, even in case of failure, the draining will proceed.

If a timeout is specified, the complete process: "flush" of the protocol and draining of messages, must happen before the timeout elapses otherwise the subscription will be forcibly closed, and not all message callbacks may be invoked.

Regardless of the presence of a timeout or not, should the subscription or connection be closed while draining occurs, the draining process will stop. The natsSubscription_WaitForDrainCompletion call will not report an error. To know if an error occurred, the user can call natsSubscription_DrainCompletionStatus after ensuring that the drain has completed.

Warning
  This function does not block waiting for the operation to complete. To synchronously wait, see natsSubscription_WaitForDrainCompletion

See also
  natsSubscription_Drain
  natsSubscription_WaitForDrainCompletion
  natsSubscription_DrainCompletionStatus

Parameters

  sub | the pointer to the natsSubscription object.
  timeout | how long to wait for the operation to complete, expressed in milliseconds. If the timeout elapses the subscription will be closed.

## ◆ natsSubscription_WaitForDrainCompletion()

NATS_EXTERN natsStatus natsSubscription_WaitForDrainCompletion | ( | natsSubscription * | sub,
|  | int64_t | timeout
| ) |  |

This function blocks until the subscription is fully drained. Returns no error if the subscription is drained or closed, otherwise returns the error if the subscription was not in drained mode (NATS_ILLEGAL_STATE) or if this subscription was not drained or closed prior to the specified timeout (NATS_TIMEOUT).

The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout.

Note that if this call times-out, it does not mean that the drain stops. The drain will continue until its own timeout elapses.

See also
  natsSubscription_Drain
  natsSubscription_DrainTimeout
  natsSubscription_DrainCompletionStatus

Parameters

  sub | the pointer to the natsSubscription object.
  timeout | how long to wait for the operation to complete, expressed in milliseconds.

## ◆ natsSubscription_DrainCompletionStatus()

NATS_EXTERN natsStatus natsSubscription_DrainCompletionStatus | ( | natsSubscription * | sub | ) |

Once the drain has completed, users can use this function to know if the drain completed successfully or not.

Possible return values (the list is not exhaustive):

`NATS_OK` the library sent the UNSUBSCRIBE protocol and finished processing all messages that were pending.
`NATS_ILLEGAL_STATE` this call was made for a subscription that had not started draining or the draining is still in progress.
`NATS_INVALID_SUBSCRIPTION` the subscription was closed while draining, which means that some messages may not have been processed.
`NATS_CONNECTION_CLOSED` the connection was closed while draining, which means that some messages may not have been processed.

Note
  This call does not wait for the drain completion (see natsSubscription_WaitForDrainCompletion for that).

See also
  natsSubscription_Drain
  natsSubscription_DrainTimeout
  natsSubscription_WaitForDrainCompletion

Parameters

  sub | the pointer to the natsSubscription object.

## ◆ natsSubscription_SetOnCompleteCB()

NATS_EXTERN natsStatus natsSubscription_SetOnCompleteCB | ( | natsSubscription * | sub,
|  | natsOnCompleteCB | cb,
|  | void * | closure
| ) |  |

In order to make sure that an asynchronous subscription's message handler is no longer invoked once the subscription is closed (natsSubscription_Unsubscribe), the subscription should be closed from the message handler itslef.

If the application closes the subscription from a different thread and immediately frees resources needed in the message handler, there is a risk of a crash since the subscription's message handler may still be invoked one last time or already in the process of executing.

To address this, the user can set a callback that will be invoked after the subscription is closed and the message handler has returned. This applies to asynchronous subscriptions using their own dispatcher or using the library's delivery thread pool.

Note
  You don't need to call this function if you are not freeing resources needed in the message handler or if you always close the subscription from the message handler itself.
  If you plan on calling this function, you should do so before calling natsSubscription_AutoUnsubscribe, since there is a risk that the subscription be removed as soon as natsSubscription_AutoUnsubscribe returns.

Calling this function on a synchronous or closed subscription will return NATS_INVALID_SUBSCRIPTION.

See also
  natsOnCompleteCB

Parameters

  sub | the pointer to the natsSubscription object
  cb | the callback to invoke when the last message of a closed subscription has been dispatched
  closure | the pointer to a user defined object (possibly `NULL`) that will be passed to the callback

## ◆ natsSubscription_Destroy()

NATS_EXTERN void natsSubscription_Destroy | ( | natsSubscription * | sub | ) |

Destroys the subscription object, freeing up memory. If not already done, this call will removes interest on the subject.

Parameters

  sub | the pointer to the natsSubscription object to destroy.