Message

Functions
NATS_EXTERN void	natsMsgList_Destroy (natsMsgList *list)
	Destroys this list of messages.
NATS_EXTERN natsStatus	natsMsg_Create (natsMsg **newMsg, const char *subj, const char *reply, const char *data, int dataLen)
	Creates a natsMsg object.
NATS_EXTERN const char *	natsMsg_GetSubject (const natsMsg *msg)
	Returns the subject set in this message.
NATS_EXTERN const char *	natsMsg_GetReply (const natsMsg *msg)
	Returns the reply set in this message.
NATS_EXTERN const char *	natsMsg_GetData (const natsMsg *msg)
	Returns the message payload.
NATS_EXTERN int	natsMsg_GetDataLength (const natsMsg *msg)
	Returns the message length.
NATS_EXTERN natsStatus	natsMsgHeader_Set (natsMsg *msg, const char *key, const char *value)
	Set the header entries associated with key to the single element value.
NATS_EXTERN natsStatus	natsMsgHeader_Add (natsMsg *msg, const char *key, const char *value)
	Add value to the header associated with key.
NATS_EXTERN natsStatus	natsMsgHeader_Get (natsMsg *msg, const char *key, const char **value)
	Get the header entry associated with key.
NATS_EXTERN natsStatus	natsMsgHeader_Values (natsMsg *msg, const char *key, const char ***values, int *count)
	Get all header values associated with key.
NATS_EXTERN natsStatus	natsMsgHeader_Keys (natsMsg *msg, const char ***keys, int *count)
	Get all header keys.
NATS_EXTERN natsStatus	natsMsgHeader_Delete (natsMsg *msg, const char *key)
	Delete the value(s) associated with key.
NATS_EXTERN bool	natsMsg_IsNoResponders (natsMsg *msg)
	Indicates if this message is a "no responders" message from the server.
NATS_EXTERN void	natsMsg_Destroy (natsMsg *msg)
	Destroys the message object.

Detailed Description

NATS Message.

Function Documentation

natsMsgList_Destroy()

NATS_EXTERN void natsMsgList_Destroy

(

natsMsgList *

list

)

This function iterates through the list of all messages and call natsMsg_Destroy for each valid (not set to NULL) message. It then frees the array that was allocated to hold pointers to those messages.

Note

The natsMsgList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

list	the natsMsgList list of natsMsg objects to destroy.

natsMsg_Create()

NATS_EXTERN natsStatus natsMsg_Create	(	natsMsg **	newMsg,
		const char *	subj,
		const char *	reply,
		const char *	data,
		int	dataLen )

Creates a natsMsg object. This is used by the subscription related calls and by natsConnection_PublishMsg().

Note

Messages need to be destroyed with natsMsg_Destroy() when no longer needed.

See also

natsMsg_Destroy()

Parameters

newMsg	the location where to store the pointer to the newly created natsMsg object.
subj	the subject this message will be sent to. Cannot be NULL.
reply	the optional reply for this message.
data	the optional message payload.
dataLen	the size of the payload.

natsMsg_GetSubject()

NATS_EXTERN const char * natsMsg_GetSubject

(

const natsMsg *

msg

)

Returns the subject set on that message.

Warning

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

Parameters

msg	the pointer to the natsMsg object.

natsMsg_GetReply()

NATS_EXTERN const char * natsMsg_GetReply

(

const natsMsg *

msg

)

Returns the reply, possibly NULL.

Warning

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

Parameters

msg	the pointer to the natsMsg object.

natsMsg_GetData()

NATS_EXTERN const char * natsMsg_GetData

(

const natsMsg *

msg

)

Returns the message payload, possibly NULL.

Note that although the data sent and received from the server is not NULL terminated, the NATS C Client does add a NULL byte to the received payload. If you expect the received data to be a "string", then this conveniently allows you to call natsMsg_GetData() without having to copy the returned data to a buffer to add the NULL byte at the end.

Warning

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

Parameters

msg	the pointer to the natsMsg object.

natsMsg_GetDataLength()

NATS_EXTERN int natsMsg_GetDataLength

(

const natsMsg *

msg

)

Returns the message's payload length, possibly 0.

Parameters

msg	the pointer to the natsMsg object.

natsMsgHeader_Set()

NATS_EXTERN natsStatus natsMsgHeader_Set	(	natsMsg *	msg,
		const char *	key,
		const char *	value )

It will replace any existing value associated with key.

Warning

Prior to v3.0.0, the key was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
key	the key under which the value will be stored. It can't ne NULL or empty.
value	the string to store under the given key. The value can be NULL or empty string.

natsMsgHeader_Add()

NATS_EXTERN natsStatus natsMsgHeader_Add	(	natsMsg *	msg,
		const char *	key,
		const char *	value )

It will append to any existing values associated with key.

Warning

Prior to v3.0.0, the key was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
key	the key under which the value will be stored. It can't ne NULL or empty.
value	the string to add to the values associated with the given key. The value can be NULL or empty string.

natsMsgHeader_Get()

NATS_EXTERN natsStatus natsMsgHeader_Get	(	natsMsg *	msg,
		const char *	key,
		const char **	value )

If more than one entry for the key is available, the first is returned. The returned value is owned by the library and MUST not be freed or altered.

Warning

Prior to v3.0.0, the key was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
key	the key for which the value is requested.
value	the memory location where the library will store the pointer to the first value (if more than one is found) associated with the key.

Returns

NATS_NOT_FOUND if key is not present in the headers.

natsMsgHeader_Values()

NATS_EXTERN natsStatus natsMsgHeader_Values	(	natsMsg *	msg,
		const char *	key,
		const char ***	values,
		int *	count )

The returned strings are own by the library and MUST not be freed or altered. However, the returned array values MUST be freed by the user.

const char* *values = NULL;
int         count   = 0;
 
s = natsMsgHeader_Values(msg, "My-Key", &values, &count);
if (s == NATS_OK)
{
     // do something with the values
 
     // then free the array of pointers.
     free((void*) values);
}

Warning

Prior to v3.0.0, the key was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
key	the key for which the values are requested.
values	the memory location where the library will store the pointer to the array of values.
count	the memory location where the library will store the number of values returned.

Returns

NATS_NOT_FOUND if key is not present in the headers.

natsMsgHeader_Keys()

NATS_EXTERN natsStatus natsMsgHeader_Keys	(	natsMsg *	msg,
		const char ***	keys,
		int *	count )

The returned strings are own by the library and MUST not be freed or altered. However, the returned array keys MUST be freed by the user.

const char* *keys = NULL;
int         count   = 0;
 
s = natsMsgHeader_Keys(msg, &keys, &count);
if (s == NATS_OK)
{
     // do something with the keys
 
     // then free the array of pointers.
     free((void*) keys);
}

Warning

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
keys	the memory location where the library will store the pointer to the array of keys.
count	the memory location where the library will store the number of keys returned.

Returns

NATS_NOT_FOUND if no key is present.

natsMsgHeader_Delete()

NATS_EXTERN natsStatus natsMsgHeader_Delete	(	natsMsg *	msg,
		const char *	key )

Warning

Prior to v3.0.0, the key was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of natsMsg may possible be altered during this call.

Parameters

msg	the pointer to the natsMsg object.
key	the key to delete from the headers map.

Returns

NATS_NOT_FOUND if key is not present in the headers.

natsMsg_IsNoResponders()

NATS_EXTERN bool natsMsg_IsNoResponders

(

natsMsg *

msg

)

Starting with the NATS Server v2.2.0+ and the C client v2.2.0+ releases, which introduced support for message headers and the "no responders" feature, if a request is received by the server and there are no subscriptions on the request's subject, the server sends a message with no payload but with a header "Status" with value "503".

The call natsConnection_Request() and its variants intercept this special message and instead of returning it to the user, they return NATS_NO_RESPONDERS.

If a synchronous subscription is created on a subject used as a reply subject to a natsConnection_PublishRequest call (and its variants), natsSubscription_NextMsg also detects this message and returns NATS_NO_RESPONDERS (but it was not from release v2.2.0 to v2.4.1).

For asynchronous subscriptions, the user may want to know that the request failed because there are no responders. For that reason, the message is passed to the message callback, and this function can be used to detect that this is a "no responders" message from the server and act accordingly.

Parameters

msg	the pointer to the natsMsg object.

Returns

true if this message is a "no responders" message from the server, that is, has no payload and the "Status" header with "503" as the value.

natsMsg_Destroy()

NATS_EXTERN void natsMsg_Destroy

(

natsMsg *

msg

)

Destroys the message, freeing memory.

Parameters

msg	the pointer to the natsMsg object to destroy.