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

Functions
Publishing
Functions » JetStream

## Functions
NATS_EXTERN natsStatus | jsPubOptions_Init (jsPubOptions *opts)
| Initializes a publish options structure. More...
NATS_EXTERN natsStatus | js_Publish (jsPubAck **pubAck, jsCtx *js, const char *subj, const void *data, int dataLen, jsPubOptions *opts, jsErrCode *errCode)
| Publishes data on a subject to JetStream. More...
NATS_EXTERN natsStatus | js_PublishMsg (jsPubAck **pubAck, jsCtx *js, natsMsg *msg, jsPubOptions *opts, jsErrCode *errCode)
| Publishes a message to JetStream. More...
NATS_EXTERN void | jsPubAck_Destroy (jsPubAck *pubAck)
| Destroys the publish acknowledgment object. More...
NATS_EXTERN natsStatus | js_PublishAsync (jsCtx *js, const char *subj, const void *data, int dataLen, jsPubOptions *opts)
| Publishes data to JetStream but does not wait for a jsPubAck. More...
NATS_EXTERN natsStatus | js_PublishMsgAsync (jsCtx *js, natsMsg **msg, jsPubOptions *opts)
| Publishes a message to JetStream but does not wait for a jsPubAck. More...
NATS_EXTERN natsStatus | js_PublishAsyncComplete (jsCtx *js, jsPubOptions *opts)
| Wait for all outstanding messages to be acknowledged. More...
NATS_EXTERN natsStatus | js_PublishAsyncGetPendingList (natsMsgList *pending, jsCtx *js)
| Returns the list of pending messages published asynchronously. More...

## Detailed Description

Publishing functions

## Function Documentation

## ◆ jsPubOptions_Init()

NATS_EXTERN natsStatus jsPubOptions_Init | ( | jsPubOptions * | opts | ) |

Use this before setting specific publish options and passing this configuration to the JetStream publish APIs.

Parameters

  opts | the pointer to the jsPubOptions to initialize.

## ◆ js_Publish()

NATS_EXTERN natsStatus js_Publish | ( | jsPubAck ** | pubAck,
|  | jsCtx * | js,
|  | const char * | subj,
|  | const void * | data,
|  | int | dataLen,
|  | jsPubOptions * | opts,
|  | jsErrCode * | errCode
| ) |  |

Publishes the data to the given subject to JetStream.

See js_PublishMsg for details.

Parameters

  pubAck | the location where to store the pub acknowledgment, or `NULL` if not needed.
  js | the pointer to the jsCtx object.
  subj | the subject the data is sent to.
  data | the data to be sent, can be `NULL`.
  dataLen | the length of the data to be sent.
  opts | the publish options, possibly `NULL`.
  errCode | the location where to store the JetStream specific error code, or `NULL` if not needed.

## ◆ js_PublishMsg()

NATS_EXTERN natsStatus js_PublishMsg | ( | jsPubAck ** | pubAck,
|  | jsCtx * | js,
|  | natsMsg * | msg,
|  | jsPubOptions * | opts,
|  | jsErrCode * | errCode
| ) |  |

Publishes the given message to JetStream.

Note
  If you are not interested in inspecting the publish acknowledgment, you can pass `NULL`, but keep in mind that the publish acknowledgment is still sent by the server.
  The returned jsPubAck object needs to be destroyed with jsPubAck_Destroy when no longer needed.

See also
  jsPubAck_Destroy

Parameters

  pubAck | the location where to store the pub acknowledgment, or `NULL` if not needed.
  js | the pointer to the jsCtx object.
  msg | the pointer to the natsMsg object to send.
  opts | the publish options, possibly `NULL`.
  errCode | the location where to store the JetStream specific error code, or `NULL` if not needed.

## ◆ jsPubAck_Destroy()

NATS_EXTERN void jsPubAck_Destroy | ( | jsPubAck * | pubAck | ) |

Releases memory allocated for this publish acknowledgment object.

Parameters

  pubAck | the jsPubAck object to destroy.

## ◆ js_PublishAsync()

NATS_EXTERN natsStatus js_PublishAsync | ( | jsCtx * | js,
|  | const char * | subj,
|  | const void * | data,
|  | int | dataLen,
|  | jsPubOptions * | opts
| ) |  |

See js_PublishMsgAsync for details.

Parameters

  js | the pointer to the jsCtx object.
  subj | the subject the data is sent to.
  data | the data to be sent, can be `NULL`.
  dataLen | the length of the data to be sent.
  opts | the publish options, possibly `NULL`.

## ◆ js_PublishMsgAsync()

NATS_EXTERN natsStatus js_PublishMsgAsync | ( | jsCtx * | js,
|  | natsMsg ** | msg,
|  | jsPubOptions * | opts
| ) |  |

Publishes a message asynchronously to JetStream. User can call js_PublishAsyncComplete to be notified when all publish acknowledgments for the pending publish calls have been received.

Note
  If this call is successful, the library takes ownership of the message and will destroy it after the acknowledgment has been received, or will present it to the user through the jsPubAckErrHandler callback. To prevent the user from accessing/destroying the message while in use by the library, this function requires a pointer to the pointer of the message so that it can be cleared. That way, the user should always call natsMsg_Destroy, regardless of success or failure, since natsMsg_Destroy will have no effect if the message pointer is `NULL`.

See also
  js_PublishAsyncComplete
  jsPubAckErrHandler

Parameters

  js | the pointer to the jsCtx object.
  msg | the memory location where the pointer to the natsMsg object is located. If the library takes ownership of the message, this location will be cleared so a following call to natsMsg_Destroy would have no effect.
  opts | the publish options, possibly `NULL`.

## ◆ js_PublishAsyncComplete()

NATS_EXTERN natsStatus js_PublishAsyncComplete | ( | jsCtx * | js,
|  | jsPubOptions * | opts
| ) |  |

This call will block until the library has received acknowledgment for all outstanding published messages.

To limit the wait, user can pass a jsPubOptions with a `MaxWait` set to the maximum number of milliseconds that the call should block.

Parameters

  js | the pointer to the jsCtx object.
  opts | the publish options, possibly `NULL`.

## ◆ js_PublishAsyncGetPendingList()

NATS_EXTERN natsStatus js_PublishAsyncGetPendingList | ( | natsMsgList * | pending,
|  | jsCtx * | js
| ) |  |

This call returns the list of all asynchronously published messages for which no acknowledgment have been received yet.

The user has now back ownership of the messages and can resend send if desired or simply destroy them.

Note
  After this call returns, it is possible that acknowledgments arrive from the server but since they have been removed from the pending list, the acknowledgments will be discarded (no jsPubAckErrHandler callback invoked). If the server did receive a particular message and the user in the meantime has resent that message, it would be a duplicate, so in order for the server to detect this duplicate, ensure that the stream's duplicate window setting is specified and a unique message ID was set when sending the message.

Warning
  The user must call natsMsgList_Destroy to release memory allocated by this call and destroy all pending messages still present in the list.

natsMsgList pending;
s = js_PublishAsyncGetPendingList(&pending, js);
if (s == NATS_OK)
{
int i;
for (i=0; i<pending.Count; i++)
{
if (your_decision_to_resend(pending.Msgs[i]))
{
// If the call is successful, pending.Msgs[i] will
// be set to NULL so the message will not be
// destroyed.
js_PublishMsgAsync(js, &(pending.Msgs[i]), NULL);
}
}
// Calling this will release memory allocated to hold the
// array of messages but also call natsMsg_Destroy on all
// messages still present in the array.
natsMsgList_Destroy(&pending);
}

Parameters

  pending | pointer to a natsMsgList object, typically defined on the stack.
  js | the pointer to the jsCtx object.