Write nmsg containers to output streams. More...

Enumerations
enum	nmsg_output_type { nmsg_output_type_stream , nmsg_output_type_pres , nmsg_output_type_callback , nmsg_output_type_json }
	An enum identifying the underlying implementation of an nmsg_output_t object. More...

Functions
nmsg_output_t	nmsg_output_open_file (int fd, size_t bufsz)
	Initialize a new byte-stream nmsg output.

nmsg_output_t	nmsg_output_open_sock (int fd, size_t bufsz)
	Initialize a new datagram socket nmsg output.

nmsg_output_t	nmsg_output_open_zmq (void *s, size_t bufsz)
	Initialize a new ZMQ socket NMSG output.

nmsg_output_t	nmsg_output_open_zmq_endpoint (void zmq_ctx, const char ep, size_t bufsz)
	Create an ZMQ socket and initialize a new NMSG stream output from it.

nmsg_output_t	nmsg_output_open_pres (int fd)
	Initialize a new presentation format (ASCII lines) nmsg output.

nmsg_output_t	nmsg_output_open_json (int fd)
	Initialize a new JSON format nmsg output.

nmsg_output_t	nmsg_output_open_callback (nmsg_cb_message cb, void *user)
	Initialize a new nmsg output closure.

nmsg_res	nmsg_output_flush (nmsg_output_t output)
	Flush an nmsg_output_t object.

nmsg_res	nmsg_output_write (nmsg_output_t output, nmsg_message_t msg)
	Write an nmsg message to an nmsg_output_t object.

nmsg_res	nmsg_output_close (nmsg_output_t *output)
	Close an nmsg_output_t object.

void	nmsg_output_set_buffered (nmsg_output_t output, bool buffered)
	Make an nmsg_output_t socket output buffered or unbuffered.

void	nmsg_output_set_filter_msgtype (nmsg_output_t output, unsigned vid, unsigned msgtype)
	Filter an nmsg_output_t for a given vendor ID / message type.

nmsg_res	nmsg_output_set_filter_msgtype_byname (nmsg_output_t output, const char vname, const char mname)
	Filter an nmsg_output_t for a given vendor ID / message type.

void	nmsg_output_set_rate (nmsg_output_t output, nmsg_rate_t rate)
	Limit the payload output rate.

void	nmsg_output_set_endline (nmsg_output_t output, const char *endline)
	Set the line continuation string for presentation format output.

void	nmsg_output_set_source (nmsg_output_t output, unsigned source)
	Set the 'source' field on all output NMSG payloads.

void	nmsg_output_set_operator (nmsg_output_t output, unsigned operator_)
	Set the 'operator' field on all output NMSG payloads.

void	nmsg_output_set_group (nmsg_output_t output, unsigned group)
	Set the 'group' field on all output NMSG payloads.

void	nmsg_output_set_zlibout (nmsg_output_t output, bool zlibout)
	Enable or disable zlib compression of output NMSG containers.

Detailed Description

Write nmsg containers to output streams.

Nmsg payloads can be buffered and written to a file descriptor, or converted to presentation format and written to a file descriptor.

MP:

Clients must ensure synchronized access when writing to an nmsg_output_t object.

Reliability:

Clients must not touch the underlying file descriptor.

Definition in file output.h.

Enumeration Type Documentation

◆ nmsg_output_type

enum nmsg_output_type

An enum identifying the underlying implementation of an nmsg_output_t object.

This is used for nmsg_io's close event notification.

Definition at line 38 of file output.h.

Function Documentation

◆ nmsg_output_open_file()

nmsg_output_t nmsg_output_open_file	(	int	fd,
		size_t	bufsz
	)

Initialize a new byte-stream nmsg output.

For efficiency reasons, files should probably be opened with a bufsz of NMSG_WBUFSZ_MAX.

Parameters

[in]	fd	Writable file descriptor.
[in]	bufsz	Value between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.

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

◆ nmsg_output_open_sock()

nmsg_output_t nmsg_output_open_sock	(	int	fd,
		size_t	bufsz
	)

Initialize a new datagram socket nmsg output.

For UDP sockets which are physically transported over an Ethernet, NMSG_WBUFSZ_ETHER or NMSG_WBUFSZ_JUMBO (for jumbo frame Ethernets) should be used for bufsz.

Parameters

[in]	fd	Writable datagram socket.
[in]	bufsz	Value between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.

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

◆ nmsg_output_open_zmq()

nmsg_output_t nmsg_output_open_zmq	(	void *	s,
		size_t	bufsz
	)

Initialize a new ZMQ socket NMSG output.

Parameters

[in]	s	ZMQ output socket.
[in]	bufsz	Value between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.

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

◆ nmsg_output_open_zmq_endpoint()

nmsg_output_t nmsg_output_open_zmq_endpoint	(	void *	zmq_ctx,
		const char *	ep,
		size_t	bufsz
	)

Create an ZMQ socket and initialize a new NMSG stream output from it.

This function is a wrapper for nmsg_output_open_zmq(). Instead of taking an already initialized ZMQ socket object, it takes an endpoint argument like zmq_connect() and zmq_bind() do which is a string containing a "transport://address" specification and initializes a ZMQ socket object. However, this endpoint string will be munged in order to support additional functionality:

The caller may select between a bound or connected ZMQ socket by appending ",accept" or ",connect" to the endpoint argument. (If not given, this function behaves as if ",connect" was passed.) That is, ",accept" uses zmq_bind() to obtain a ZMQ endpoint, and ",connect" uses zmq_connect().

The caller may additionally select between a PUB socket or a PUSH socket by appending ",pubsub" or ",pushpull". (If not given, this function behaves as if ",pubsub" was passed.)

See also: nmsg_input_open_zmq_endpoint()

Parameters

[in]	zmq_ctx	ZMQ context object.
[in]	ep	ZMQ endpoint (with nmsg-specific extensions)
[in]	bufsz	Value between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.

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

◆ nmsg_output_open_pres()

nmsg_output_t nmsg_output_open_pres ( int fd )

Initialize a new presentation format (ASCII lines) nmsg output.

Parameters

[in] fd Writable file descriptor.

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

◆ nmsg_output_open_json()

nmsg_output_t nmsg_output_open_json ( int fd )

Initialize a new JSON format nmsg output.

JSON outputs write payloads as JSON dictionaries with keys:

time: the payload timestamp
vname: the vendor name, or "(unknown)" if not known
mname: the message type name, or "(unknown)" if not known
source: the payload source id as a hexadecimal string, if present
group: the payload group name or number, if present
operator: the payload operator name or number, if present
message: a dictionary containing a key-value pari for each message field

Values of repeated fields are represented as lists.

Message modules can provide optional formatting and parsing methods for fields. If a field has no formatter or parser, the following default formats are used:

Numeric types: JSON number
Boolean: JSON bool
IP address: string representation of the IP address.
Enumerated types: a string with the value name if known, integer otherwise.
Byte sequences: a string with the base64 encoding of the sequence.
Strings: JSON strings, with invalid UTF-8 sequences replaced with U+FFFD.

Parameters

[in] fd Writable file descriptor.

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

◆ nmsg_output_open_callback()

nmsg_output_t nmsg_output_open_callback	(	nmsg_cb_message	cb,
		void *	user
	)

Initialize a new nmsg output closure.

This allows a user-provided callback to function as an nmsg output, for instance to participate in an nmsg_io loop. The callback is responsible for disposing of each nmsg message.

Parameters

[in]	cb	Non-NULL function pointer that will be called once for each payload.
[in]	user	Optionally NULL pointer which will be passed to the callback.

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

◆ nmsg_output_flush()

nmsg_res nmsg_output_flush ( nmsg_output_t output )

Flush an nmsg_output_t object.

This function writes out any messages in the output buffer.

This function is only implemented for byte-stream and datagram socket nmsg outputs.

Parameters

[in] output nmsg_output_t object.

Returns: nmsg_res_success; nmsg_res_failure

◆ nmsg_output_write()

nmsg_res nmsg_output_write	(	nmsg_output_t	output,
		nmsg_message_t	msg
	)

Write an nmsg message to an nmsg_output_t object.

nmsg_output_write() does not deallocate the nmsg message object. Callers should call nmsg_message_destroy() when finished with a message object.

Parameters

[in]	output	nmsg_output_t object.
[in]	msg	nmsg message to be serialized and written to 'output'.

Returns: nmsg_res_success; nmsg_res_failure

◆ nmsg_output_close()

nmsg_res nmsg_output_close ( nmsg_output_t * output )

Close an nmsg_output_t object.

Parameters

[in] output Pointer to an nmsg_output_t object.

Returns: nmsg_res_success

◆ nmsg_output_set_buffered()

void nmsg_output_set_buffered	(	nmsg_output_t	output,
		bool	buffered
	)

Make an nmsg_output_t socket output buffered or unbuffered.

By default, file and socket nmsg_output_t outputs are buffered. Extremely low volume output streams should probably be unbuffered to reduce latency.

Parameters

[in]	output	Socket nmsg_output_t object.
[in]	buffered	True (buffered) or false (unbuffered).

◆ nmsg_output_set_filter_msgtype()

void nmsg_output_set_filter_msgtype	(	nmsg_output_t	output,
		unsigned	vid,
		unsigned	msgtype
	)

Filter an nmsg_output_t for a given vendor ID / message type.

NMSG messages whose vid and msgtype fields do not match the filter will not be output and will instead be silently discarded.

Calling this function with vid=0 and msgtype=0 will disable the filter.

Parameters

[in]	output	nmsg_output_t object.
[in]	vid	Vendor ID.
[in]	msgtype	Message type.

◆ nmsg_output_set_filter_msgtype_byname()

nmsg_res nmsg_output_set_filter_msgtype_byname	(	nmsg_output_t	output,
		const char *	vname,
		const char *	mname
	)

Filter an nmsg_output_t for a given vendor ID / message type.

Parameters

[in]	output	nmsg_output_t object.
[in]	vname	Vendor ID name.
[in]	mname	Message type name.

◆ nmsg_output_set_rate()

void nmsg_output_set_rate	(	nmsg_output_t	output,
		nmsg_rate_t	rate
	)

Limit the payload output rate.

The caller of nmsg_output_set_rate() is responsible for reclaiming unused nmsg_rate_t objects with nmsg_rate_destroy().

Parameters

[in]	output	nmsg_output_t object.
[in]	rate	nmsg_rate_t object or NULL to disable rate limiting.

◆ nmsg_output_set_endline()

void nmsg_output_set_endline	(	nmsg_output_t	output,
		const char *	endline
	)

Set the line continuation string for presentation format output.

The default is "\n".

Parameters

[in]	output	nmsg_output_t object.
[in]	endline	End-of-line character string.

◆ nmsg_output_set_source()

void nmsg_output_set_source	(	nmsg_output_t	output,
		unsigned	source
	)

Set the 'source' field on all output NMSG payloads.

This has no effect on non-NMSG outputs.

The source ID must be positive.

Parameters

[in]	output	NMSG stream nmsg_output_t object.
[in]	source	Source ID.

◆ nmsg_output_set_operator()

void nmsg_output_set_operator	(	nmsg_output_t	output,
		unsigned	operator_
	)

Set the 'operator' field on all output NMSG payloads.

This has no effect on non-NMSG outputs.

The operator ID must be positive.

Parameters

[in]	output	NMSG stream nmsg_output_t object.
[in]	operator_	Operator ID.

◆ nmsg_output_set_group()

void nmsg_output_set_group	(	nmsg_output_t	output,
		unsigned	group
	)

Set the 'group' field on all output NMSG payloads.

This has no effect on non-NMSG outputs.

The group ID must be positive.

Parameters

[in]	output	NMSG stream nmsg_output_t object.
[in]	group	Group ID.

◆ nmsg_output_set_zlibout()

void nmsg_output_set_zlibout	(	nmsg_output_t	output,
		bool	zlibout
	)

Enable or disable zlib compression of output NMSG containers.

Parameters

[in]	output	nmsg_output_t object.
[in]	zlibout	True (zlib enabled) or false (zlib disabled).

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ nmsg_output_type

Function Documentation

◆ nmsg_output_open_file()

◆ nmsg_output_open_sock()

◆ nmsg_output_open_zmq()

◆ nmsg_output_open_zmq_endpoint()

◆ nmsg_output_open_pres()

◆ nmsg_output_open_json()

◆ nmsg_output_open_callback()

◆ nmsg_output_flush()

◆ nmsg_output_write()

◆ nmsg_output_close()

◆ nmsg_output_set_buffered()

◆ nmsg_output_set_filter_msgtype()

◆ nmsg_output_set_filter_msgtype_byname()

◆ nmsg_output_set_rate()

◆ nmsg_output_set_endline()

◆ nmsg_output_set_source()

◆ nmsg_output_set_operator()

◆ nmsg_output_set_group()

◆ nmsg_output_set_zlibout()