dsyslog module api guide
6/5/2008 Jeff Katz

1 Kinds of Modules

	dsyslog has four different kind of modules: 
		condition modules, filter modules, source modules, and output modules. 
	
	Condition modules allow dsyslog to change its behavior based on certain
	conditions, for instance multiple, duplicate messages or messages from
	a certain source. 

	Filter modules allow dsyslog to change the output messages based on certain
	filters, such as a regex, or to drop certain logs completely.

	Source modules define data sources that dsyslog will draw log data from, in
	addition to the standard /dev/log and /proc/kmsg sources, modules exist to
	pull data from udp sockets. 

	Output modules define data destinations that dsyslog will log data to. This
	will generally be either some form of flatfile, or database, or perhaps a tcp
	or udp socket. 

2 dsyslog Best Practices

	You will notice that dsyslog makes good use of the glib libraries. Users 
	wishing to extend dsyslog should become familiar with these libraries and use 
	them where appropriate. 

	The _ENTER and _LEAVE macros are very important, and should be included in 
	each function for debugging purposes. If your module needs to report an error,
	it should use the _ERROR macro. 
	
3 Module Apis

	All modules are required to have the initialization and finishing functions.
	These are typed as follows:
	
		void _modinit(void)
		void _modfini(void)
		
	Typically, modules will register their hooks in the initialization function
	and unregister them in the finishing function, but additional allocation and
	deallocation can be performed in these functions. 
	
	3.1 Condition Modules
	
		Condition modules will manage hooks with the following two functions:
	
			dsyslog_cond_type_register(gchar *, (*dsyslog_cond_eval_t)
				(dsyslog_event_t *event, dsyslog_cond_t *cond))
			dsyslog_cond_type_unregister(gchar *)
		
		The former takes arguments of a hook name and a functor to the handling
		function with signature:
		
			static gboolean
			cond_handler(dsyslog_event_t *event, dsyslog_cond_t *cond)
			
		Whereas the latter just requires the hook name to unregister it.
		
	3.2 Filter Modules
	
		Filter modules will manage hooks with the following two functions:
		
			dsyslog_filter_type_register(gchar *, (*dsyslog_filter_handler_t)
				(dsyslog_event_t *event, dsyslog_filter_t *filter))
			dsyslog_filter_type_unregister(gchar *)
		
		These functions work much the same as the ones for the condition modules.
		The handling signature is as follows:
		
			static gboolean
			filter_handler(dsyslog_event_t *event, dsyslog_filter_t *filter)

	3.3 Source Modules
	
		Source modules will manage hooks with the following two functions:
		
			dsyslog_source_register(gchar *, (*dsyslog_source_constructor_t)
				(dsyslog_source_t *src))
			dsyslog_source_unregister(gchar *)
			
		Note that there is no event attached to source modules. The handler
		signature for source models is as follows:
		
			static void dsyslog_source_new(dsyslog_source_t *src)
		
	3.4 Output Modules.
	
		Output modules will manage hooks with the following two functions:
		
			dsyslog_output_type_register(gchar *, (*dsyslog_output_handler_t)
				(dsyslog_event_t *event, dsyslog_output_t *output))
			dsyslog_output_type_unregister(gchar *)
			
		The handler signature for the output handler is as follows:
		
			static void output_handler(dsyslog_event_t *event, 
				dsyslog_output_t *output)