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

Typedefs
Callbacks

## Typedefs
typedef void(* | natsMsgHandler) (natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)
| Callback used to deliver messages to the application. More...
typedef void(* | natsConnectionHandler) (natsConnection *nc, void *closure)
| Callback used to notify the user of asynchronous connection events. More...
typedef void(* | natsErrHandler) (natsConnection *nc, natsSubscription *subscription, natsStatus err, void *closure)
| Callback used to notify the user of errors encountered while processing inbound messages. More...
typedef natsStatus(* | natsEvLoop_Attach) (void **userData, void *loop, natsConnection *nc, natsSock socket)
| Attach this connection to the external event loop. More...
typedef natsStatus(* | natsEvLoop_ReadAddRemove) (void *userData, bool add)
| Read event needs to be added or removed. More...
typedef natsStatus(* | natsEvLoop_WriteAddRemove) (void *userData, bool add)
| Write event needs to be added or removed. More...
typedef natsStatus(* | natsEvLoop_Detach) (void *userData)
| Detach from the event loop. More...
typedef natsStatus(* | natsUserJWTHandler) (char **userJWT, char **customErrTxt, void *closure)
| Callback used to fetch and return account signed user JWT. More...
typedef natsStatus(* | natsSignatureHandler) (char **customErrTxt, unsigned char **signature, int *signatureLength, const char *nonce, void *closure)
| Callback used to sign a nonce sent by the server. More...
typedef const char *(* | natsTokenHandler) (void *closure)
| Callback used to build a token on connections and reconnections. More...
typedef void(* | natsOnCompleteCB) (void *closure)
| Callback used to notify that an object lifecycle is complete. More...
typedef int64_t(* | natsCustomReconnectDelayHandler) (natsConnection *nc, int attempts, void *closure)
| Callback used to specify how long to wait between reconnects. More...
typedef void(* | jsPubAckErrHandler) (jsCtx *js, jsPubAckErr *pae, void *closure)
| Callback used to process asynchronous publish errors from JetStream. More...
typedef void(* | jsPubAckHandler) (jsCtx *js, natsMsg *msg, jsPubAck *pa, jsPubAckErr *pae, void *closure)
| Callback used to process asynchronous publish responses from JetStream. More...
typedef void(* | stanPubAckHandler) (const char *guid, const char *error, void *closure)
| Callback used to notify of an asynchronous publish result. More...
typedef void(* | stanMsgHandler) (stanConnection *sc, stanSubscription *sub, const char *channel, stanMsg *msg, void *closure)
| Callback used to deliver messages to the application. More...
typedef void(* | stanConnectionLostHandler) (stanConnection *sc, const char *errorTxt, void *closure)
| Callback used to notify the user of the permanent loss of the connection. More...

## Detailed Description

NATS Callbacks.

## Typedef Documentation

## ◆ natsMsgHandler

typedef void(* natsMsgHandler) (natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)

This is the callback that one provides when creating an asynchronous subscription. The library will invoke this callback for each message arriving through the subscription's connection.

Warning
  If this callback is setup for a subject that is used as the reply subject to natsConnection_PublishRequest calls (and its variants), it is possible to get an empty message with a header "Status" with value "503" that is sent by the server when there were no responders on the request's subject. Use natsMsg_IsNoResponders to know if that is the case.

See also
  natsConnection_Subscribe()
  natsConnection_QueueSubscribe()
  natsMsg_IsNoResponders()

## ◆ natsConnectionHandler

typedef void(* natsConnectionHandler) (natsConnection *nc, void *closure)

This callback is used for asynchronous events such as disconnected and closed connections.

See also
  natsOptions_SetClosedCB()
  natsOptions_SetDisconnectedCB()
  natsOptions_SetReconnectedCB()

Warning
  Such callback is invoked from a dedicated thread and the state of the connection that triggered the event may have changed since that event was generated.

## ◆ natsErrHandler

typedef void(* natsErrHandler) (natsConnection *nc, natsSubscription *subscription, natsStatus err, void *closure)

This callback is used to process asynchronous errors encountered while processing inbound messages, such as NATS_SLOW_CONSUMER.

## ◆ natsEvLoop_Attach

typedef natsStatus(* natsEvLoop_Attach) (void **userData, void *loop, natsConnection *nc, natsSock socket)

After a connection has (re)connected, this callback is invoked. It should perform the necessary work to start polling the given socket for READ events.

Parameters

  userData | location where the adapter implementation will store the object it created and that will later be passed to all other callbacks. If `*userData` is not `NULL`, this means that this is a reconnect event.
  loop | the event loop (as a generic void*) this connection is being attached to.
  nc | the connection being attached to the event loop.
  socket | the socket to poll for read/write events.

## ◆ natsEvLoop_ReadAddRemove

typedef natsStatus(* natsEvLoop_ReadAddRemove) (void *userData, bool add)

The `NATS` library will invoke this callback to indicate if the event loop should start (`add is`true`) or stop (`add`is`false`) polling for read events on the socket.

Parameters

  userData | the pointer to an user object created in natsEvLoop_Attach.
  add | `true` if the event library should start polling, `false` otherwise.

## ◆ natsEvLoop_WriteAddRemove

typedef natsStatus(* natsEvLoop_WriteAddRemove) (void *userData, bool add)

The `NATS` library will invoke this callback to indicate if the event loop should start (`add is`true`) or stop (`add`is`false`) polling for write events on the socket.

Parameters

  userData | the pointer to an user object created in natsEvLoop_Attach.
  add | `true` if the event library should start polling, `false` otherwise.

## ◆ natsEvLoop_Detach

typedef natsStatus(* natsEvLoop_Detach) (void *userData)

The `NATS` library will invoke this callback to indicate that the connection no longer needs to be attached to the event loop. User can cleanup some state.

Parameters

  userData | the pointer to an user object created in natsEvLoop_Attach.

## ◆ natsUserJWTHandler

typedef natsStatus(* natsUserJWTHandler) (char **userJWT, char **customErrTxt, void *closure)

This handler is invoked when connecting and reconnecting. It should return the user JWT that will be sent to the server.

The user JWT is returned as a string that is allocated by the user and is freed by the library after the handler is invoked.

If the user is unable to return the JWT, a status other than `NATS_OK` should be returned (we recommend `NATS_ERR`). A custom error message can be returned through `customErrTxt`. The user must allocate the memory for this error message and the library will free it after the invocation of the handler.

Warning
  There may be repeated invocations of this handler for a given connection so it is crucial to always return a copy of the user JWT maintained by the application, since again, the library will free the memory pointed by `userJWT` after each invocation of this handler.

See also
  natsOptions_SetUserCredentialsCallbacks()
  natsOptions_SetUserCredentialsFromFiles()

## ◆ natsSignatureHandler

typedef natsStatus(* natsSignatureHandler) (char **customErrTxt, unsigned char **signature, int *signatureLength, const char *nonce, void *closure)

This handler is invoked when connecting and reconnecting. It should sign the given `nonce` and return a raw signature through `signature` and specify how many characters the signature has using `signatureLength`.

The memory pointed by `signature` must be allocated by the user and will be freed by the library after each invocation of this handler.

If the user is unable to sign, a status other than `NATS_OK` (we recommend `NATS_ERR`) should be returned. A custom error message can be returned through `customErrTxt`. The user must allocate the memory for this error message and the library will free it after the invocation of this handler.

The library will base64 encode this raw signature and send that to the server.

Warning
  There may be repeated invocations of this handler for a given connection so it is crucial to always return a copy of the signature, since again, the library will free the memory pointed by `signature` after each invocation of this handler.

See also
  natsOptions_SetUserCredentialsCallbacks()
  natsOptions_SetUserCredentialsFromFiles()
  natsOptions_SetNKey()

## ◆ natsTokenHandler

typedef const char*(* natsTokenHandler) (void *closure)

This is the function that one provides to build a different token at each reconnect.

See also
  natsOptions_SetTokenHandler()

Warning
  Such callback is invoked synchronously from the connection thread.

## ◆ natsOnCompleteCB

typedef void(* natsOnCompleteCB) (void *closure)

Currently used for asynchronous natsSubscription objects. When set, this callback will be invoked after the subscription is closed and the message handler has returned.

See also
  natsSubscription_SetOnCompleteCB()

## ◆ natsCustomReconnectDelayHandler

typedef int64_t(* natsCustomReconnectDelayHandler) (natsConnection *nc, int attempts, void *closure)

This callback is used to get from the user the desired delay the library should pause before attempting to reconnect again. Note that this is invoked after the library tried the whole list of URLs and failed to reconnect.

Note
  This callback is invoked from the connection reconnect thread and waits for user input. It should not block and instead quickly return the desired reconnect delay. The state of the connection is disconnected when this callback is invoked. Not much can be done with the passed connection, but user can call natsConnection_Close() if desired. This will abort the reconnect attempts and close the connection.

Parameters

  nc | the pointer to the natsConnection invoking this handler.
  attempts | the number of times the library tried the whole list of server URLs.
  closure | an optional pointer to a user defined object that was specified when registering the callback.

Returns
  the number of milliseconds to wait before trying to reconnect.

## ◆ jsPubAckErrHandler

typedef void(* jsPubAckErrHandler) (jsCtx *js, jsPubAckErr *pae, void *closure)

Callback used to process asynchronous publish errors from JetStream js_PublishAsync and js_PublishMsgAsync calls. The provided jsPubAckErr object gives the user access to the encountered error along with the original message sent to the server for possible restransmitting.

Note
  If the message is resent, the library will not destroy the original message and once again take ownership of it. To resend the message, do the following so that the library knows not to destroy the message (since the call will clear the `Msg` field from the jsPubAckErr object).

void myPAECallback(jsCtx *js, jsPubAckErr *pae, void* closure)
{
...
// Resend the message
js_PublishMsgAsync(js, &(pae->Msg), NULL);
}

Warning
  The jsPubAckErr object and its content will be invalid as soon as the callback returns.
  Unlike a NATS message callback, the user does not have to destroy the original NATS message (present in the jsPubAckErr object), the library will do it.

Parameters

  js | the pointer to the jsCtx object.
  pae | the pointer to the jsPubAckErr object.
  closure | an optional pointer to a user defined object that was specified when registering the callback.

## ◆ jsPubAckHandler

typedef void(* jsPubAckHandler) (jsCtx *js, natsMsg *msg, jsPubAck *pa, jsPubAckErr *pae, void *closure)

Callback used to process asynchronous publish responses (positive and negatives) from JetStream js_PublishAsync and js_PublishMsgAsync calls. The provided jsPubAck or jsPubAckErr objects give the user access to the successful acknowledgment from the server or the encountered error along with the original message sent to the server for possible restransmitting.

Warning
  The user is responsible for destroying the message. If the message is resent using the js_PublishMsgAsync call, the library is taking ownership of the message and calling natsMsg_Destroy will have no effect because the pointer will have been set to `NULL`. So it is recommended to always call natsMsg_Destroy at the end of the function.

void myAckHandler(jsCtx *js, natsMsg *msg, jsPubAck *pa, jsPubAckErr *pae, void *closure)
{
if (pa != NULL)
{
// Success case...
}
else if (pae != NULL)
{
// Error case...
// If the application wants to resend the message:
js_PublishMsgAsync(js, &msg, NULL);
}
natsMsg_Destroy(msg);
}

Warning
  The jsPubAck and jsPubAckErr objects and their content will be invalid as soon as the callback returns.

Parameters

  js | the pointer to the jsCtx object.
  msg | the pointer to the original published natsMsg.
  pa | the pointer to the jsPubAck object.
  pae | the pointer to the jsPubAckErr object.
  closure | an optional pointer to a user defined object that was specified when registering the callback.

## ◆ stanPubAckHandler

typedef void(* stanPubAckHandler) (const char *guid, const char *error, void *closure)

This is used for asynchronous publishing to provide status of the acknowledgment. The function will be passed the GUID and any error state. No error means the message was successfully received by NATS Streaming.

See also
  stanConnection_PublishAsync()

## ◆ stanMsgHandler

typedef void(* stanMsgHandler) (stanConnection *sc, stanSubscription *sub, const char *channel, stanMsg *msg, void *closure)

This is the callback that one provides when creating an asynchronous subscription. The library will invoke this callback for each message arriving through the subscription's connection.

See also
  stanConnection_Subscribe()
  stanConnection_QueueSubscribe()

## ◆ stanConnectionLostHandler

typedef void(* stanConnectionLostHandler) (stanConnection *sc, const char *errorTxt, void *closure)

This callback is used to notify the user that the connection to the Streaming server is permanently lost.