Plugin Extensions to Post.Office Filters

Please see text links at bottom of page for navigation

Plugin Extensions to Post.Office Filters

1 - Post.Office Plugins - Overview

Post.Office email filters support the multi-faceted filtering of incoming email messages. Using Post.Office filters, email messages containing text or graphics that are deemed unwanted are either discarded or transferred to alternate mail address(es).

Up until now, Post.Office filter construction has been limited to specifying the logical summation of a series of static strings that conditionally match parts of an email address, header or body.

This mechanism has been improved to support the automatic inclusion of user software modules that extend this static process with a dynamic plugin software facility.

The plugin extension provides for the end user construction of software that can be conditionally called as an extended element of a standard Post.Office filter.

2 - Plugin Construction

A Post.Office plugin is built by constructing three routines; a routine called for initialization when the plugin is loaded, a routine called when a plugin is unloaded, and a message filtering routine called when each message is received.

When called, a message filtering routine is passed a data structure defining the filter, a pointer to the content of a message and a data length indication. By examining the data, the plugin determines whether the message is acceptable for delivery returning a zero indication if the message is acceptable or a positive indication if the message is unacceptable.

3 - Example Plugin

The text below contains an example plugin.

 #include <plugin.h>

		PLUGINMODULE tst_plugin =
		{
			0,0,
			"my_tst_plugin",
			tst_plugin_init,
			tst_plugin_term,
			tst_plugin_call
		};

The PLUGINMODULE data structure holds the elements of a Post.Office plugin together. The first two data structure elements are place holder fields and always set to zero. The third field contains the internal name of the plugin (e.g. "my_tst_plugin"). This name is used as a part of a Post.Office filter specification to decide which plugin to call when the segment of the filter containing the name is called. The next element contains the name of the routine that is called when the plugin is loaded (e.g. tst_plugin_init). The next element is called when the plugin is unloaded (tst_plugin_term). The last element - tst_plugin_call - is called when an email message filter is executed containing the name - "tst_plugin" - referenced in a Post.Office filter.

The empty routine shown below - tst_plugin_init - is called when the plugin is loaded. It is passed a pointer to the PLUGINMODULE declared above. The plugin initialization routine is used to allocate and initialize plugin operations.

A plugin developer is encouraged to over allocate PLUGINMODULE data structure adding fields at the end of an instance of the PLUGINMODULE definition to provide for local plugin module data storage.

	void tst_plugin_init( PLUGINMODULE *pm )
	{
	}

The tst_plugin_term routine is called when the plugin is unloaded. It is passed the same PLUGINMODULE pointer passed to the initialization routine.

	void tst_plugin_term( PLUGINMODULE *pm )
	{
	}

The tst_plugin_call routine is called when an email filter containing the name of the plugin - "my_tst_plugin" - is executed. It is passed the PLUGINMODULE data structure, the address of the beginning of data to be investigated and a length indication - len - indicating how many bytes pointed to by the "base" parameter are valid.

	int tst_plugin_call( PLUGINMODULE *pm,const char *base,int len )
	{
		int should_filter;
		if( should_filter )
			return( 1 );		// do filter
			return( 0 );		// dont filter
	}

The plugin returns a positive value if the plugin wants the Post.Office filter to treat the message as a unacceptable for delivery. The plugin returns a zero value if the message is acceptable and delivery processing should proceed normally.

A plugin filter may be used as an element of a Post.Office source or destination address filter or as an element of a Post.Office body filter. To select a plugin as a filter element, the filter type drop down list is selected and scrolled to a plugin selection. Then the name of the plugin (e.g. my_tst_plugin) is typed into the text box next to the plugin list designation. Finally, any Boolean selections from the far right most drop down list may be selected to logically relate the filter element to other elements.

Plugin filter element specifications are available for email source address, email destination address and email body segments of a filter. Plugin filter element specifications are not available for email header segments of a message.

When a plugin is used as an element of an address filter, the plugin "call" routine is executed multiple times for each message. It is called with the source and destination IP addresses as well as the source host name that sent the message. A plugin call routine is called once when it is a part of Post.Office email message body filter.

4 - Building a Plugin

A plugin is built with the /usr/local/post.office/plugins/Makefile. It produces a file with a dynamically loadable file named with a .so suffix.

There is an important convention in the naming of a plugin file (e.g. tst_plugin.so) and the name of the PLUGINMODULE symbol name:

PLUGINMODULE tst_plugin

The convention is that the basename of a plugin file name is the used to lookup the PLUGINMODULE symbol when the plugin is loaded. If this naming convention is not followed, the plugin cannot be initialized and will not be found as part of a Post.Office filter.

When construction of a plugin .so file is complete, it should be moved to the /usr/local/post.office/plugins directory. To incorporate a plugin into Post.Office operation, the post.office application must be restarted.