Callbacks

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

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 istrue) or stop (addisfalse`) 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 istrue) or stop (addisfalse`) 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.