Functions for marshalling NMSG containers. More...

Functions
nmsg_container_t	nmsg_container_init (size_t bufsz)
	Initialize a new NMSG container object.

void	nmsg_container_destroy (nmsg_container_t *c)
	Deallocate the resources associated with an nmsg_container_t object.

void	nmsg_container_set_sequence (nmsg_container_t c, bool do_sequence)
	Enable or disable NMSG container sequence tracking.

nmsg_res	nmsg_container_add (nmsg_container_t c, nmsg_message_t msg)
	Add an NMSG message object to an NMSG container object.

size_t	nmsg_container_get_num_payloads (nmsg_container_t c)
	Get the current number of payloads in the NMSG container object.

nmsg_res	nmsg_container_serialize (nmsg_container_t c, uint8_t *pbuf, size_t buf_len, bool do_header, bool do_zlib, uint32_t sequence, uint64_t sequence_id)
	Serialize an NMSG container object, allocating memory as needed and returning a free()able buffer containing the serialized data.

nmsg_res	nmsg_container_deserialize (const uint8_t buf, size_t buf_len, nmsg_message_t msgarray, size_t n_msg)
	Deserialize a collection of NMSG messages contained in a buffer containing a serialized NMSG container.

Detailed Description

Functions for marshalling NMSG containers.

Definition in file container.h.

Function Documentation

◆ nmsg_container_init()

nmsg_container_t nmsg_container_init ( size_t bufsz )

Initialize a new NMSG container object.

NMSG container objects are used to accumulate NMSG payload objects with nmsg_container_add() prior to being marshalled into a buffer containing a serialized NMSG container with nmsg_container_serialize().

After calling nmsg_container_serialize() on an NMSG container object, it must be freed by calling nmsg_container_destroy(), as container objects are not reusable.

Returns: Opaque pointer that is NULL on failure or non-NULL on success.

Parameters

[in] bufsz Maximum serialized container length requested by the caller. (This limit cannot be satisfied in all cases, however.)

◆ nmsg_container_destroy()

void nmsg_container_destroy ( nmsg_container_t * c )

Deallocate the resources associated with an nmsg_container_t object.

Parameters

[in] c Pointer to an nmsg_container_t object.

◆ nmsg_container_set_sequence()

void nmsg_container_set_sequence	(	nmsg_container_t	c,
		bool	do_sequence
	)

Enable or disable NMSG container sequence tracking.

If called, this function must be called prior to calling to nmsg_container_add(). By default, NMSG container sequence tracking is disabled on newly created container objects.

Parameters

[in] io Pointer to an nmsg_container_t object.

◆ nmsg_container_add()

nmsg_res nmsg_container_add	(	nmsg_container_t	c,
		nmsg_message_t	msg
	)

Add an NMSG message object to an NMSG container object.

Ownership of the message object remains with the caller. The caller is still responsible for calling nmsg_message_destroy() on the message object.

Returns: nmsg_res_success; nmsg_res_memfail; nmsg_res_container_full The message could not be added to the container object because the container object already contains messages and because adding the supplied message would result in a serialized container larger than the maximum serialized container length requested in the corresponding call to nmsg_container_init().; nmsg_res_container_overfull The message was added to a previously empty container object, but serializing the container would now result in a serialized length larger than the limit requested in the corresponding call to nmsg_container_init().

◆ nmsg_container_serialize()

nmsg_res nmsg_container_serialize	(	nmsg_container_t	c,
		uint8_t **	pbuf,
		size_t *	buf_len,
		bool	do_header,
		bool	do_zlib,
		uint32_t	sequence,
		uint64_t	sequence_id
	)

Serialize an NMSG container object, allocating memory as needed and returning a free()able buffer containing the serialized data.

Parameters

[in]	c	Pointer to an nmsg_container_t object.
[out]	pbuf	Pointer to where a pointer to the serialized buffer will be stored.
[out]	buf_len	Pointer to where the length in bytes of the serialized buffer will be stored.
[in]	do_header	Whether to write the fixed-length NMSG header to the beginning of the buffer.
[in]	do_zlib	Whether to compress the variable-length part of the serialized NMSG container with zlib.
[in]	sequence	The sequence number of this container. This parameter is only used if nmsg_container_set_sequence() was used to enable sequence tracking on this container, and is ignored otherwise. The sequence number should start at 0 and increment by 1 for each additional container in a sequence of containers.
[in]	sequence_id	A randomized ID number identifying the sequence number space that the 'sequence' parameter exists in. This ID number is used by NMSG consumers to disambiguate multiple disparate sequences of NMSG containers when consuming a multiplexed stream from multiple sources. This ID number should be generated by a cryptographically secure PRNG such as the one provided by nmsg_random_init() to minimize the possibility of collisions.

◆ nmsg_container_deserialize()

nmsg_res nmsg_container_deserialize	(	const uint8_t *	buf,
		size_t	buf_len,
		nmsg_message_t **	msgarray,
		size_t *	n_msg
	)

Deserialize a collection of NMSG messages contained in a buffer containing a serialized NMSG container.

The serialized NMSG container must contain the fixed-length NMSG header followed by the variable-length part of the NMSG container.

Parameters

[in]	buf	Buffer containing the serialized NMSG container.
[in]	buf_len	Length in bytes of the serialized NMSG container.
[out]	msgarray	Pointer to where an array of NMSG message objects will be stored. The individual NMSG message objects in this array must be destroyed by the caller with nmsg_message_destroy(), and the array itself must be destroyed by the caller with free().
[out]	n_msg	Pointer to where the number of elements in the NMSG message object array will be stored.