Developing Plug-Ins

WorkgroupMail has the ability to add software plug-ins which can perform processing on incoming and outgoing messages before they are sent or received. This powerful feature makes it possible for you to tailor WorkgroupMail for a particular need. Plug-ins may be written in Visual C++ or in Visual Basic or in any language that supports COM and/or automation. Visual Basic is the preferred method and this section describes the process of writing such an application using Visual Basic as an example.

 

Whenever a message is sent or received, a certain method (or function) in your plug-in code will be called, passing you the name of a file which contains the message in its entirety in MIME format.  You may do anything within this function, including deleting this file, moving it to another user, or mailing it externally. What you return from this function determines whether or not WorkgroupMail sends the message to the message quarantine.

 

When your plug-in is imported into the WorkgroupMail administrator, it will be visible as an entry in the left-hand list. When a user double clicks on the plug-in entry, another function will be called in your program, enabling you to show whatever user interface you wish. This may be anything from a message box, to a multi-page property sheet to an entire application.

 

Getting Started

A good starting point is to use the sample Visual Basic plug-in that you can download from http://www.workgroupmail.com/sample_plugin.zip . This is a Visual Basic project containing all the necessary functions to work with the WorkgroupMail engine and the WorkgroupMail Administrator.

Once you have downloaded the sample, load it into Visual Basic. You will see four functions defined. These are described in the next section:

 

The Programmatic Interface

There are four functions that provide the link between WorkgroupMail, the WorkgroupMail administrator and your plug-in program. These are as follows:

 

EditProperties()

Syntax: EditProperties( )

This function is called whenever the plug-in entry is double clicked in the WorkgroupMail administrator or the Properties context menu of the plug-in entry is selected. This function takes no arguments and returns nothing back to the caller.

Ideally, this function should create a modal dialog box or property sheet, allowing the user to change any settings associated with the plug-in.

 

DefaultName()

Syntax: DefaultName( ) As String

This function is called by the WorkgroupMail Administrator in order to query the name of the plug-in. The plug-in name will be used to display the plug-in in the left hand window in the WorkgroupMail Administrator.

So, for example, you might return a typical DefaultName string as follows:

DefaultName = "Sample Plug-in"

 

GetProperties()

Syntax: GetProperties() As String

This function is used to display the properties (or settings) associated with the plug-in, in the right hand window of the WorkgroupMail Administrator when the user clicks on the plug-in entry in the left-hand window.

The string that you return from this function represents all the properties and values of the plug-in. The format of the string is as follows:

Property 1 & Value 1 & Property 2 & Value 2….

So, for example, you might return a typical property string as follows:

GetProperties = "Name&Sample Plug-in&Folder&" & "c:\temp" & "&Date&" & "12/4/01"

 

ProcessMessageFile()

Syntax: ProcessMessageFile(sFilename As String, bReceived As Integer, ByRef sDescription As String ) As Long

This function is called by the WorkgroupMail engine to determine whether or not a particular message should be quarantined.

The ProcessMessageFile() should do the following:

·         Parse the file, sFilename, and look at whether the message is incoming or outgoing (bReceived) to determine whether this plug-in should quarantine or not.

·         If the message is quarantined remember to assign a reason string to the sDescription parameter.

·         Return one of the following values to determine how the message is treated by the engine:

 

Return Value	Action
1	Do not quarantine the message. Don't pass this message to any further plug-ins and don't permit the message to be sent or received.
2	Quarantine the message. Don't pass this message to any further plug-ins and don't permit the message to be sent or received.
3	Do not quarantine the message. Pass this message to any further plug-ins for processing. Permit this message to be sent and received unless another plug-in throws a problem.
4	Log an event to indicate a problem with the plug-in. Pass this message to any further plug-ins for processing. Permit this message to be sent and received unless another plug-in throws a problem.

 

Importing the Plug-in

To import the plug-in, select Edit | Plug-in Manager from the menu of the WorkgroupMail administrator. In the Plug-in Manager dialog box, press the Add button. The Import Plug-in wizard is shown. In the first page of the Import Plug-in Wizard, enter the location of the plug-in DLL. In the next page, enter the progid of the plug-in, which in the case of the sample plug-in is sampleplugin.engine . Press Finish to complete the import.