msgmod.h File Reference

Message modules. More...

Go to the source code of this file.

Macros
#define	NMSG_MSGMOD_FIELD_REPEATED   0x01
	field is repeated
#define	NMSG_MSGMOD_FIELD_REQUIRED   0x02
	field is required
#define	NMSG_MSGMOD_FIELD_HIDDEN   0x04
	hide field from the message API
#define	NMSG_MSGMOD_FIELD_NOPRINT   0x08
	don't print the field
#define	NMSG_MSGMOD_FIELD_FORMAT_RAW   0x10
	treat format return value as is

Enumerations
enum	nmsg_msgmod_field_type {   nmsg_msgmod_ft_enum ,   nmsg_msgmod_ft_bytes ,   nmsg_msgmod_ft_string ,   nmsg_msgmod_ft_mlstring ,   nmsg_msgmod_ft_ip ,   nmsg_msgmod_ft_uint16 ,   nmsg_msgmod_ft_uint32 ,   nmsg_msgmod_ft_uint64 ,   nmsg_msgmod_ft_int16 ,   nmsg_msgmod_ft_int32 ,   nmsg_msgmod_ft_int64 ,   nmsg_msgmod_ft_double ,   nmsg_msgmod_ft_bool }
	Enum mapping protocol buffer schema types to nmsg-specific types for "transparent" modules. More...

Functions
nmsg_res	nmsg_msgmod_init (nmsg_msgmod_t mod, void **clos)
	Initialize a message module.
nmsg_res	nmsg_msgmod_fini (nmsg_msgmod_t mod, void **clos)
	Finalize a mesage module.
nmsg_res	nmsg_msgmod_pres_to_payload (nmsg_msgmod_t mod, void *clos, const char *pres)
	Convert a presentation format line to an NMSG payload.
nmsg_res	nmsg_msgmod_pres_to_payload_finalize (nmsg_msgmod_t mod, void *clos, uint8_t **pbuf, size_t *sz)
	After a call to nmsg_msgmod_pres_to_payload() returns nmsg_res_pbuf_ready, this function will return the serialized payload.
nmsg_res	nmsg_msgmod_ipdg_to_payload (nmsg_msgmod_t mod, void *clos, const struct nmsg_ipdg *dg, uint8_t **pbuf, size_t *sz)
	Convert an IP datagram to an NMSG payload.
nmsg_res	nmsg_msgmod_pkt_to_payload (struct nmsg_msgmod *mod, void *clos, nmsg_pcap_t pcap, nmsg_message_t *m)
	Read a raw packet and optionally convert it to an NMSG payload.
nmsg_msgmod_t	nmsg_msgmod_lookup (unsigned vid, unsigned msgtype)
	Determine which nmsg_msgmod is responsible for a given vid/msgtype tuple, if any.
nmsg_msgmod_t	nmsg_msgmod_lookup_byname (const char *vname, const char *mname)
	Determine which nmsg_msgmod is responsible for a given vid/msgtype tuple, if any.
unsigned	nmsg_msgmod_mname_to_msgtype (unsigned vid, const char *mname)
	Convert the human-readable name of a message type to a message type ID.
const char *	nmsg_msgmod_msgtype_to_mname (unsigned vid, unsigned msgtype)
	Convert a vendor ID / message type ID tuple to the human-readable form of the message type.
const char *	nmsg_msgmod_vid_to_vname (unsigned vid)
	Convert a numeric vendor ID to its human-readable name.
unsigned	nmsg_msgmod_vname_to_vid (const char *vname)
	Convert a human-readable vendor name to its numeric ID.
unsigned	nmsg_msgmod_get_max_vid (void)
	Return the maximum vendor ID.
unsigned	nmsg_msgmod_get_max_msgtype (unsigned vid)
	Return the maximum message type registered to a vendor ID.

Detailed Description

Message modules.

Message modules extend nmsg by allowing new message types to be implemented in dynamically loaded plugins. Msgmods identify the types of messages they can handle by registering a vendor ID number and a per-vendor message type number with the msgmod loader. Functions for creating and interpreting NMSG payloads must be provided.

Msgmods are dynamically loaded shared objects that must provide either a symbol called nmsg_msgmod_ctx of type nmsg_msgmod or a symbol called nmsg_msgmod_ctx_array which will be interpreted as an array of pointers to objects of type struct nmsg_msgmod. If an array is used, the array must be terminated by a NULL pointer.

The first field of the nmsg_msgmod structure is the version of the API between libnmsg and the extension module; module developers should use this header file for the struct nmsg_msgmod definition and assign this field the value NMSG_MSGMOD_VERSION.

Modules must be reentrant, as exported message handling functions may be called from multiple threads simultaneously. An opaque pointer may be returned by the module initialization function; this pointer will be provided to module functions that require state and will be provided to the module finalization function for deallocation.

If a message schema is restricted in a certain way, a C stub consisting of data definitions only can be used to interface with libnmsg. This is called a "transparent module". Transparent modules are implemented using the Protobuf-C compiler.

For an example of a transparent module, see the base/email message type in the nmsg distribution. The file nmsg/base/email.proto is compiled with the Protobuf-C compiler into the files email.pb-c.c and email.pb-c.h. The file email.c provides the C stub to interface with the msgmod interface, which is compiled into a shared object and installed into the nmsg module directory.

MP:

• nmsg_msgmod_init() returns an opaque pointer which is used to differentiate threads if a message module is not stateless.

Definition in file msgmod.h.

Macro Definition Documentation

NMSG_MSGMOD_FIELD_REPEATED

#define NMSG_MSGMOD_FIELD_REPEATED   0x01

field is repeated

Definition at line 122 of file msgmod.h.

NMSG_MSGMOD_FIELD_REQUIRED

#define NMSG_MSGMOD_FIELD_REQUIRED   0x02

field is required

Definition at line 123 of file msgmod.h.

NMSG_MSGMOD_FIELD_HIDDEN

#define NMSG_MSGMOD_FIELD_HIDDEN   0x04

hide field from the message API

Definition at line 124 of file msgmod.h.

NMSG_MSGMOD_FIELD_NOPRINT

#define NMSG_MSGMOD_FIELD_NOPRINT   0x08

don't print the field

Definition at line 125 of file msgmod.h.

NMSG_MSGMOD_FIELD_FORMAT_RAW

#define NMSG_MSGMOD_FIELD_FORMAT_RAW   0x10

treat format return value as is

Definition at line 126 of file msgmod.h.

Enumeration Type Documentation

nmsg_msgmod_field_type

enum nmsg_msgmod_field_type

Enum mapping protocol buffer schema types to nmsg-specific types for "transparent" modules.

Protocol buffers provide basic data types on which transparent message modules can build more meaningful types.

Enumerator
nmsg_msgmod_ft_enum	Protobuf enum.
nmsg_msgmod_ft_bytes	Protobuf byte array.
nmsg_msgmod_ft_string	Protobuf byte array. String should not contain newlines.
nmsg_msgmod_ft_mlstring	Protobuf byte array. String can contain newlines.
nmsg_msgmod_ft_ip	Protobuf byte array. Length must be 4 for IPv4 addresses or 16 for IPv6 addresses.
nmsg_msgmod_ft_uint16	Protobuf uint32.
nmsg_msgmod_ft_uint32	Protobuf uint32.
nmsg_msgmod_ft_uint64	Protobuf uint64.
nmsg_msgmod_ft_int16	Protobuf int32.
nmsg_msgmod_ft_int32	Protobuf int32.
nmsg_msgmod_ft_int64	Protobuf int64.
nmsg_msgmod_ft_double	Protobuf double.
nmsg_msgmod_ft_bool	Protobuf bool.

Definition at line 72 of file msgmod.h.

Function Documentation

nmsg_msgmod_init()

nmsg_res nmsg_msgmod_init	(	nmsg_msgmod_t	mod,
		void **	clos
	)

Initialize a message module.

Parameters

[in]	mod	Initialized msgmod.
[out]	clos	Opaque pointer specific to this instantiation of the module. This pointer must be supplied to nmsg_msgmod functions taking a 'clos' parameter.

Returns

nmsg_res_success

nmsg_res_failure

nmsg_res_memfail

nmsg_res_notimpl

nmsg_msgmod_fini()

nmsg_res nmsg_msgmod_fini	(	nmsg_msgmod_t	mod,
		void **	clos
	)

Finalize a mesage module.

Parameters

[in]	mod	Initialized msgmod.
[in]	clos	Opaque pointer returned by the module initialization function.

Returns

nmsg_res_success

nmsg_res_failure

nmsg_res_notimpl

nmsg_msgmod_pres_to_payload()

nmsg_res nmsg_msgmod_pres_to_payload	(	nmsg_msgmod_t	mod,
		void *	clos,
		const char *	pres
	)

Convert a presentation format line to an NMSG payload.

Since the presentation format stream is line-delimited, not every line will necessarily result in a serialized message.

When nmsg_res_pbuf_ready is returned, the nmsg_msgmod_pres_to_payload_finalize() function should be used to obtain the serialized payload.

Msgmods are not required to implement a function to convert presentation form data to payloads, in which case nmsg_res_notimpl will be returned.

Parameters

[in]	mod	Initialized msgmod.
[in]	clos	Opaque pointer returned by the module initialization function.
[in]	pres	Line of presentation form input of the type handled by 'mod'.

Returns

nmsg_res_success

nmsg_res_failure

nmsg_res_memfail

nmsg_res_notimpl

nmsg_res_parse_error

nmsg_res_pbuf_ready

nmsg_msgmod_pres_to_payload_finalize()

nmsg_res nmsg_msgmod_pres_to_payload_finalize	(	nmsg_msgmod_t	mod,
		void *	clos,
		uint8_t **	pbuf,
		size_t *	sz
	)

After a call to nmsg_msgmod_pres_to_payload() returns nmsg_res_pbuf_ready, this function will return the serialized payload.

The caller is responsible for freeing the payload returned.

Parameters

[in]	mod	Initialized msgmod.
[in]	clos	Opaque pointer returned by the module initialization function.
[out]	pbuf	Serialized payload.
[out]	sz	Length of the serialized payload.

Returns

nmsg_res_success

nmsg_res_failure

nmsg_res_memfail

nmsg_res_notimpl

nmsg_msgmod_ipdg_to_payload()

nmsg_res nmsg_msgmod_ipdg_to_payload	(	nmsg_msgmod_t	mod,
		void *	clos,
		const struct nmsg_ipdg *	dg,
		uint8_t **	pbuf,
		size_t *	sz
	)

Convert an IP datagram to an NMSG payload.

Msgmods are not required to implement a function to convert IP datagrams to payloads, in which case nmsg_res_notimpl will be returned.

Parameters

[in]	mod	Initialized msgmod.
[in]	clos	Opaque pointer returned by the module initialization function.
[in]	dg	Filled nmsg_ipdg structure.
[out]	pbuf	Serialized payload.
[out]	sz	Length of the serialized payload.

Returns

nmsg_res_parse_error

nmsg_res_pbuf_ready

nmsg_res_notimpl

nmsg_msgmod_pkt_to_payload()

nmsg_res nmsg_msgmod_pkt_to_payload	(	struct nmsg_msgmod *	mod,
		void *	clos,
		nmsg_pcap_t	pcap,
		nmsg_message_t *	m
	)

Read a raw packet and optionally convert it to an NMSG payload.

Msgmods are not required to implement a function to convert raw packets to payloads, in which case nmsg_res_notimpl will be returned.

A message will only be consumable if the return value is nmsg_res_success.

Parameters

[in]	mod	Initialized msgmod.
[in]	clos	Opaque pointer returned by the module initialization function.
[in]	pcap	Pcap input to read packets from.
[out]	m	Location to store payload.

Returns

nmsg_res_success

nmsg_res_again

nmsg_res_notimpl

nmsg_msgmod_lookup()

nmsg_msgmod_t nmsg_msgmod_lookup	(	unsigned	vid,
		unsigned	msgtype
	)

Determine which nmsg_msgmod is responsible for a given vid/msgtype tuple, if any.

Parameters

[in]	vid	Numeric vendor ID.
[in]	msgtype	Numeric message type.

Returns

The nmsg_msgmod responsible for handling the given vid/msgtype tuple, if such a module has been loaded into the set, or NULL otherwise.

nmsg_msgmod_lookup_byname()

nmsg_msgmod_t nmsg_msgmod_lookup_byname	(	const char *	vname,
		const char *	mname
	)

Determine which nmsg_msgmod is responsible for a given vid/msgtype tuple, if any.

This function looks up the vid and msgtype by name.

Parameters

[in]	vname	Vendor name.
[in]	mname	Message type name.

Returns

The nmsg_msgmod responsible for handling the given vid/msgtype tuple, if such a module has been loaded into the set, or NULL otherwise.

nmsg_msgmod_mname_to_msgtype()

unsigned nmsg_msgmod_mname_to_msgtype	(	unsigned	vid,
		const char *	mname
	)

Convert the human-readable name of a message type to a message type ID.

Parameters

[in]	vid	Numeric vendor ID.
[in]	mname	Message type name.

Returns

A numeric message type ID. By convention, 0 is used to indicate an unknown message type.

nmsg_msgmod_msgtype_to_mname()

const char * nmsg_msgmod_msgtype_to_mname	(	unsigned	vid,
		unsigned	msgtype
	)

Convert a vendor ID / message type ID tuple to the human-readable form of the message type.

Parameters

[in]	vid	Numeric vendor ID.
[in]	msgtype	Numeric message type.

Returns

A human-readable message type name. NULL is returned if the vendor ID or message type is unknown.

nmsg_msgmod_vid_to_vname()

const char * nmsg_msgmod_vid_to_vname

(

unsigned

vid

)

Convert a numeric vendor ID to its human-readable name.

Parameters

[in]

vid

Numeric vendor ID.

Returns

A human-readable vendor name. NULL is returned if the vendor ID is unknown.

nmsg_msgmod_vname_to_vid()

unsigned nmsg_msgmod_vname_to_vid

(

const char *

vname

)

Convert a human-readable vendor name to its numeric ID.

Parameters

[in]

vname

Vendor name.

Returns

A numeric vendor ID. By convention, 0 is used to indicate an unknown vendor ID.

nmsg_msgmod_get_max_msgtype()

unsigned nmsg_msgmod_get_max_msgtype

(

unsigned

vid

)

Return the maximum message type registered to a vendor ID.

Parameters

[in]

vid

Numeric vendor ID.