Header

Functions
NATS_EXTERN natsStatus	natsHeader_New (natsHeader **new_header)
	Creates an header object.
NATS_EXTERN natsStatus	natsHeader_Set (natsHeader *h, const char *key, const char *value)
	Set the header entries associated with key to the single element value.
NATS_EXTERN natsStatus	natsHeader_Add (natsHeader *h, const char *key, const char *value)
	Add value to the header associated with key.
NATS_EXTERN natsStatus	natsHeader_Get (natsHeader *h, const char *key, const char **value)
	Get the header entry associated with key.
NATS_EXTERN natsStatus	natsHeader_Values (natsHeader *h, const char *key, const char ***values, int *count)
	Get all header values associated with key.
NATS_EXTERN natsStatus	natsHeader_Keys (natsHeader *h, const char ***keys, int *count)
	Get all header keys.
NATS_EXTERN int	natsHeader_KeysCount (natsHeader *h)
	Returns the number of keys.
NATS_EXTERN natsStatus	natsHeader_Delete (natsHeader *h, const char *key)
	Delete the value(s) associated with key.
NATS_EXTERN void	natsHeader_Destroy (natsHeader *h)
	Destroys the natsHeader object.

Detailed Description

This is represented as a map, with the key being a string and value being an array of strings.

Function Documentation

natsHeader_New()

NATS_EXTERN natsStatus natsHeader_New

(

natsHeader **

new_header

)

Creates an header object that is empty.

Note

The returned natsHeader object needs be destroyed using natsHeader_Destroy when no longer needed to free allocated memory.

See also

natsHeader_Destroy

Parameters

new_header

the location where to store the pointer to the natsHeader object.

natsHeader_Set()

NATS_EXTERN natsStatus natsHeader_Set	(	natsHeader *	h,
		const char *	key,
		const char *	value
	)

It will replace any existing value associated with key.

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.

Parameters

h	the pointer to the natsHeader 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.

natsHeader_Add()

NATS_EXTERN natsStatus natsHeader_Add	(	natsHeader *	h,
		const char *	key,
		const char *	value
	)

It will append to any existing values associated with key.

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.

Parameters

h	the pointer to the natsHeader 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.

natsHeader_Get()

NATS_EXTERN natsStatus natsHeader_Get	(	natsHeader *	h,
		const char *	key,
		const char **	value
	)

If more than one entry for the key is available, the first is returned.

Warning

The returned value is owned by the library and MUST not be freed or altered.

Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads.

Parameters

h	the pointer to the natsHeader 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.

natsHeader_Values()

NATS_EXTERN natsStatus natsHeader_Values	(	natsHeader *	h,
		const char *	key,
		const char ***	values,
		int *	count
	)

Warning

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 = natsHeader_Values(h, "My-Key", &values, &count);
if (s == NATS_OK)
{
     // do something with the values
 
     // then free the array of pointers.
     free((void*) values);
}

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.

Parameters

h	the pointer to the natsHeader 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.

natsHeader_Keys()

NATS_EXTERN natsStatus natsHeader_Keys	(	natsHeader *	h,
		const char ***	keys,
		int *	count
	)

Warning

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(h, &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.

Parameters

h	the pointer to the natsHeader 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.

natsHeader_KeysCount()

NATS_EXTERN int natsHeader_KeysCount

(

natsHeader *

h

)

Parameters

h	the pointer to the natsHeader object.

Returns

The number of keys. If h is NULL, retunrs 0.

natsHeader_Delete()

NATS_EXTERN natsStatus natsHeader_Delete	(	natsHeader *	h,
		const char *	key
	)

Delete the value(s) associated with key.

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.

Parameters

h	the pointer to the natsHeader object.
key	the key to delete from the headers map.

Returns

NATS_NOT_FOUND if key is not present in the headers.

natsHeader_Destroy()

NATS_EXTERN void natsHeader_Destroy

(

natsHeader *

h

)

Releases memory allocated for this natsHeader object.

Parameters

h	the pointer to the natsHeader object.