nmsg  0.9.0
Enumerations | Functions
output.h File Reference

Write nmsg containers to output streams. More...

Go to the source code of this file.

Enumerations

enum  nmsg_output_type {
  nmsg_output_type_stream,
  nmsg_output_type_pres,
  nmsg_output_type_callback
}
 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. More...
 
nmsg_output_t nmsg_output_open_sock (int fd, size_t bufsz)
 Initialize a new datagram socket nmsg output. More...
 
nmsg_output_t nmsg_output_open_xs (void *s, size_t bufsz)
 Initialize a new XS socket NMSG output. More...
 
nmsg_output_t nmsg_output_open_xs_endpoint (void *xs_ctx, const char *ep, size_t bufsz)
 Create an XS socket and initialize a new NMSG stream output from it. More...
 
nmsg_output_t nmsg_output_open_pres (int fd)
 Initialize a new presentation format (ASCII lines) nmsg output. More...
 
nmsg_output_t nmsg_output_open_callback (nmsg_cb_message cb, void *user)
 Initialize a new nmsg output closure. More...
 
nmsg_res nmsg_output_flush (nmsg_output_t output)
 Flush an nmsg_output_t object. More...
 
nmsg_res nmsg_output_write (nmsg_output_t output, nmsg_message_t msg)
 Write an nmsg message to an nmsg_output_t object. More...
 
nmsg_res nmsg_output_close (nmsg_output_t *output)
 Close an nmsg_output_t object. More...
 
void nmsg_output_set_buffered (nmsg_output_t output, bool buffered)
 Make an nmsg_output_t socket output buffered or unbuffered. More...
 
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. More...
 
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. More...
 
void nmsg_output_set_rate (nmsg_output_t output, nmsg_rate_t rate)
 Limit the payload output rate. More...
 
void nmsg_output_set_endline (nmsg_output_t output, const char *endline)
 Set the line continuation string for presentation format output. More...
 
void nmsg_output_set_source (nmsg_output_t output, unsigned source)
 Set the 'source' field on all output NMSG payloads. More...
 
void nmsg_output_set_operator (nmsg_output_t output, unsigned operator_)
 Set the 'operator' field on all output NMSG payloads. More...
 
void nmsg_output_set_group (nmsg_output_t output, unsigned group)
 Set the 'group' field on all output NMSG payloads. More...
 
void nmsg_output_set_zlibout (nmsg_output_t output, bool zlibout)
 Enable or disable zlib compression of output NMSG containers. More...
 

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:

Reliability:

Definition in file output.h.

Enumeration Type Documentation

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 40 of file output.h.

Function Documentation

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]fdWritable file descriptor.
[in]bufszValue between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.

Definition at line 30 of file output.c.

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]fdWritable datagram socket.
[in]bufszValue between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.

Definition at line 35 of file output.c.

nmsg_output_t nmsg_output_open_xs ( void *  s,
size_t  bufsz 
)

Initialize a new XS socket NMSG output.

Parameters
[in]sXS output socket.
[in]bufszValue between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.
nmsg_output_t nmsg_output_open_xs_endpoint ( void *  xs_ctx,
const char *  ep,
size_t  bufsz 
)

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

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

The caller may select between a bound or connected XS 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 xs_bind() to obtain a XS endpoint, and ",connect" uses xs_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_xs_endpoint()
Parameters
[in]xs_ctxXS context object.
[in]epXS endpoint (with nmsg-specific extensions)
[in]bufszValue between NMSG_WBUFSZ_MIN and NMSG_WBUFSZ_MAX.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.
nmsg_output_t nmsg_output_open_pres ( int  fd)

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

Parameters
[in]fdWritable file descriptor.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.

Definition at line 62 of file output.c.

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]cbNon-NULL function pointer that will be called once for each payload.
[in]userOptionally NULL pointer which will be passed to the callback.
Returns
Opaque pointer that is NULL on failure or non-NULL on success.

Definition at line 89 of file output.c.

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]outputnmsg_output_t object.
Returns
nmsg_res_success
nmsg_res_failure

Definition at line 110 of file output.c.

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]outputnmsg_output_t object.
[in]msgnmsg message to be serialized and written to 'output'.
Returns
nmsg_res_success
nmsg_res_failure

Definition at line 115 of file output.c.

nmsg_res nmsg_output_close ( nmsg_output_t *  output)

Close an nmsg_output_t object.

Parameters
[in]outputPointer to an nmsg_output_t object.
Returns
nmsg_res_success

Definition at line 134 of file output.c.

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]outputSocket nmsg_output_t object.
[in]bufferedTrue (buffered) or false (unbuffered).

Definition at line 173 of file output.c.

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]outputnmsg_output_t object.
[in]vidVendor ID.
[in]msgtypeMessage type.

Definition at line 182 of file output.c.

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]outputnmsg_output_t object.
[in]vnameVendor ID name.
[in]mnameMessage type name.

Definition at line 193 of file output.c.

void nmsg_output_set_rate ( nmsg_output_t  output,
nmsg_rate_t  rate 
)

Limit the payload output rate.

Parameters
[in]outputnmsg_output_t object.
[in]ratenmsg_rate_t object or NULL to disable rate limiting.

Definition at line 214 of file output.c.

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]outputnmsg_output_t object.
[in]endlineEnd-of-line character string.

Definition at line 230 of file output.c.

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]outputNMSG stream nmsg_output_t object.
[in]sourceSource ID.

Definition at line 239 of file output.c.

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]outputNMSG stream nmsg_output_t object.
[in]operator_Operator ID.

Definition at line 245 of file output.c.

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]outputNMSG stream nmsg_output_t object.
[in]groupGroup ID.

Definition at line 251 of file output.c.

void nmsg_output_set_zlibout ( nmsg_output_t  output,
bool  zlibout 
)

Enable or disable zlib compression of output NMSG containers.

Parameters
[in]outputnmsg_output_t object.
[in]zliboutTrue (zlib enabled) or false (zlib disabled).

Definition at line 223 of file output.c.