fltmod.h File Reference

Loading and calling external message filter modules. More...

Go to the source code of this file.

Functions
nmsg_fltmod_t	nmsg_fltmod_init (const char *name, const void *param, const size_t len_param)
	Initialize a filter module with the given parameters.
void	nmsg_fltmod_destroy (nmsg_fltmod_t *fltmod)
	Destroy a filter module.
nmsg_res	nmsg_fltmod_thread_init (nmsg_fltmod_t fltmod, void **thr_data)
	Initialize thread-specific data for the filter module.
nmsg_res	nmsg_fltmod_thread_fini (nmsg_fltmod_t fltmod, void *thr_data)
	Release any thread-specific resources acquired by nmsg_fltmod_thread_init().
nmsg_res	nmsg_fltmod_filter_message (nmsg_fltmod_t fltmod, nmsg_message_t *msg, void *thr_data, nmsg_filter_message_verdict *vres)
	Filter a message object and return the filter verdict.

Detailed Description

Loading and calling external message filter modules.

This file defines the interface for loading and calling filter modules. For the interface that developers of message filter modules must implement, see nmsg/fltmod_plugin.h.

Message filter modules allow a message filtering function to be implemented externally in a dynamically loaded plugin.

A filter module must first be loaded with nmsg_fltmod_init(). If this succeeds, nmsg_fltmod_thread_init() must be called by each thread that wants to perform filtering with this module, even if the caller is single-threaded. The 'thr_data' value returned by nmsg_fltmod_thread_init() must be provided as the 'thr_data' parameter to nmsg_fltmod_filter_message().

Filter functions may alter or replace the message object.

Each thread that calls nmsg_fltmod_thread_init() must clean up by calling nmsg_fltmod_thread_fini(), and after each thread has cleaned up, the module itself may be cleaned up by calling nmsg_fltmod_destroy().

Definition in file fltmod.h.

Function Documentation

nmsg_fltmod_init()

nmsg_fltmod_t nmsg_fltmod_init	(	const char *	name,
		const void *	param,
		const size_t	len_param
	)

Initialize a filter module with the given parameters.

Calls the module's 'module_init' function.

Parameters

name	The name of the filter module, which is used to construct the filesystem path to the shared object containing the filter module. This may either be a real, complete filesystem path (absolute or relative) that begins with "/" or "./", or it may be a short "convenience" name that will be expanded to a real filesystem path. For example, the short name "sample" might be expanded to a long name like "/usr/lib/nmsg/nmsg_flt1_sample.so".
param	Pointer to a value that will be passed to the 'module_init' function. Specifies module-specific configuration.
len_param	Length of the 'param' value. Passed to the 'module_init' function.

Returns

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

nmsg_fltmod_destroy()

void nmsg_fltmod_destroy

(

nmsg_fltmod_t *

fltmod

)

Destroy a filter module.

Calls the module's 'module_fini' function. All calls to nmsg_fltmod_thread_fini() must complete before calling this function.

Parameters

[in]

fltmod

Initialized fltmod.

nmsg_fltmod_thread_init()

nmsg_res nmsg_fltmod_thread_init	(	nmsg_fltmod_t	fltmod,
		void **	thr_data
	)

Initialize thread-specific data for the filter module.

Must be called by a processing thread before calling nmsg_fltmod_filter_message(). Calls the module's 'thread_init' function.

Each thread that calls nmsg_fltmod_thread_init() must perform a corresponding call to nmsg_fltmod_thread_fini() before nmsg_fltmod_destroy() can be called.

Parameters

	fltmod	Initialized fltmod.
[out]	thr_data	Opaque data pointer specific to the calling thread. This pointer must be supplied in subsequent calls to nmsg_fltmod_filter_message() or nmsg_fltmod_thread_fini().

Returns

nmsg_res_success If the thread data was successfully initialized.

Any other result may be returned by the module's 'thread_init' function to indicate an error.

nmsg_fltmod_thread_fini()

nmsg_res nmsg_fltmod_thread_fini	(	nmsg_fltmod_t	fltmod,
		void *	thr_data
	)

Release any thread-specific resources acquired by nmsg_fltmod_thread_init().

Calls the module's 'thread_fini' function.

Parameters

fltmod	Initialized fltmod.
thr_data	Opaque data pointer originally returned by nmsg_fltmod_thread_init().

Returns

nmsg_res_success If the thread data was successfully released.

Any other result may be returned by the module's 'thread_fini' function to indicate an error.

nmsg_fltmod_filter_message()

nmsg_res nmsg_fltmod_filter_message	(	nmsg_fltmod_t	fltmod,
		nmsg_message_t *	msg,
		void *	thr_data,
		nmsg_filter_message_verdict *	vres
	)

Filter a message object and return the filter verdict.

Calls the module's 'filter_message' function.

The thread that calls this function must have first called nmsg_fltmod_thread_init(), and the 'thr_data' value returned by that function must be passed as the 'thr_data' parameter to this function.

Parameters

	fltmod	Initialized fltmod.
[in,out]	msg	The NMSG message object to be filtered. The filter function may alter the message object, or it may replace it with a new message object.
	thr_data	Opaque data pointer originally returned by nmsg_fltmod_thread_init().
[out]	vres	The filter verdict.

See also

nmsg_filter_message_verdict for the possible verdict results and meanings.

Returns

nmsg_res_success The filtering completed and returned a verdict in 'vres'.

Any other result may be returned to indicate a fatal error.