Introducing the Messaging Server Plug-in API

When the message is accepted, the plug-in API creates a Message structure that points to the file that contains the entire message, including the header and body information.

The header of the message is made up of fields in name:value pair format that include all envelope information, such as sender, recipients, sender and per-recipient extensions, and so on.

The body of the message refers to the lines of text that make up the content of the message.

The Message structure is passed into the plug-in through the main plug-in function, which must be based on the pFunc function prototype.

The control data accessed by the Messaging Server Plug-in API is specific to Netscape Messaging Server. Control data is internal to the Messaging Server. It is made up of the SMTP envelope combined with connection data gathered during the accept sequence of Messaging Server.

The control data for a message is passed into the plug-in through the plug-in initialization function, which must be based on the pInitFunc function prototype. Once loaded, the control data is maintained in memory until the plug-in entry point returns to the server. When this happens, the message is written automatically to the disk.

If several entry points for a single plug-in entry stage are cascaded, the server waits to write the control data until after all the entry points return. The server writes the entry points in the order in which they appear in the configuration file. See "The Plug-in Configuration File."

Messaging Server 4.0 is multithreaded. In general, make sure that your plug-in code is thread-safe.

If possible, avoid using global variables in your Messaging Server plug-ins. If you use globals, make sure that they are synchronized to avoid multiple calls to the plug-in. For example, they could be encapsulated in a class that synchronizes access to the globals.

Plug-ins for 4.x servers should handle restartable system calls, such as signals.

[Top]

The Plug-in Configuration File

The Messaging Server plug-in configuration file, plugins.cfg, contains configuration information for all installed server plug-ins. In the configuration file, each plug-in is listed on its own line, in the order in which the plug-ins were installed in Messaging Server. This is the order in which the plug-ins will execute as well.

When the plug-in is initialized, Messaging Server passes this configuration information to the plug-in's pblock structure.

Plug-in configuration information has this format:

stage <pluginPath> funcs=<function>[,function] init=<function>
                  <optionParam>[<optionParam>]

<optionParam>=<param-name>=<param-value>

The parameters have the following descriptions:

`stage`	The stage in message processing, or entry point, at which the plug-in is called, either: `PostSmtpAccept`: immediately after the message is received off the wire) `PreSmtpDeliver`: just before the message is handed off to another host For more information, see "How Messaging Server Plug-ins Work."
`pluginPath`	Complete file path to the binary (executable) file of the plug-in library. For more information, see "Building the Plug-in."
`funcs`	The plug-in's functions in a comma-separated list. When the plug-in runs, Messaging Server calls the functions as they occur in this list. The documentation you supply with your plug-in should describe the contents of this field.
`init`	The plug-in's initialization function.
`optionParam`	One or more options that supply additional plug-in functionality, listed in a set of comma-separated name:value pairs. When the plug-in runs, Messaging Server passes it this optional information. For example, you could use this option to set a path to a temporary file or configuration file. To get the value part of one of these pairs, you use the `pblock_findval` function. The documentation you supply with your plug-in should describe the contents of this field.

For example, a plug-in configuration file could call the plug-in libxlate.so at the PostSmtpAccept stage of message processing to decode the message, and at the PreSmtpDeliver to encode it, with these lines:

PostSmtpAccept /foo/bar/libxlate.so funcs=decode-euc init=decode-init

PreSmtpDeliver /foo/bar/libxlate.so funcs=encode-iso init=encode-init 
                                    no-xlate-domains="*.kr"

In the first line of the example, the plug-in acts at the PostSmtpAccept message processing stage, and gives the full path to its library file, libxlate.so. The funcs list implements the plug-in function decode-euc. The init list implements the plug-in's initialization function, decode-init.

In the second line of the example, the plug-in acts at the PreSmtpDeliver processing stage and gives the full path its library file, libxlate.so. The funcs list implements the plug-in function encode-iso. The init list implements the plug-in's initialization function, encode-init. This line sets a single option, directing the plug-in not to encode messages from the top-level domain .kr.

For more information about the configuration file, including its location in Messaging Server, see Chapter 7, "Working With SMTP Plug-Ins," in the Messaging Server 4.0 Administration Guide.

[Top]

Building the Plug-in

The dynamically loadable executable code that implements the functionality of your plug-in is the shared object (called a shared library on some platforms). The shared object is passed as the pluginPath parameter in the plug-in configuration file, plugins.cfg. For more information about this code, see "The Plug-in Configuration File."

A shared object or plug-in is configured to run at a particular stage of message processing, or entry point. The possible entry points are PostSmtpAccept and PreSmtpDeliver. For more information about entry points, see "How Messaging Server Plug-ins Work."

A message goes through the shared object when it enters the processing stage for which the object is configured. For example, all outbound messages go through any plug-in configured with the PreSmtpDeliver entry point. Messaging Server calls the shared object and waits for a return before calling it again.

You can write a makefile to build your plug-in. The example in this section shows the makefile that builds the sample code in this guide, which you can find in Chapter 4, "Messaging Server Sample Plug-in." Running makefile with the sample code file, sample.c, results in a shared object named sample.o.

NOTE: You can download a zip file, msplugin.zip, that contains the sample plug-in file sample.c and makefile. §

# Sample Makefile for Netscape Messaging Server Plug-in

# Name of the plug-in to build

TARGET=sample

# Use one of the following

SHARED_SUFFIX=so

# Use one of the following

CC=gcc -fPIC -I../include -shared

#CC=cc -KPIC -I../include -G

# Use one of the following

FLAGS = -DXP_UNIX

#FLAGS = -DXP_WIN32

# Use zero or more of the following

#FLAGS += -D_DEBUG

all: $(TARGET).$(SHARED_SUFFIX)

$(TARGET).$(SHARED_SUFFIX): $(TARGET).c ../include/msg4plugins.h

        $(CC) $(FLAGS) -o $(TARGET).$(SHARED_SUFFIX) $(TARGET).c

sample.o

clean:

        rm -f $(TARGET).$(SHARED_SUFFIX)

[Top] [Building the Plug-in]

Installing the Plug-in

When you write a plug-in, you are responsible for writing an installation routine that installs it, along with any additional files it requires, in Messaging Server. You can make the process easier by providing some documentation to help the user install your plug-in.

For information about plug-ins in Messaging Server, see Chapter 7, "Working With SMTP Plug-Ins," in the Messaging Server 4.0 Administration Guide. This chapter describes installing, configuring, deactivating, and deinstalling plug-ins.

[Top]

Table of Contents | Previous | Next | Index

Last Updated: 11/19/98 10:23:53

[an error occurred while processing this directive]

Chapter 1 Introducing the Messaging Server Plug-in API

How You Can Use Messaging Server Plug-ins

How Messaging Server Plug-ins Work

The Plug-in Configuration File

Building the Plug-in

Installing the Plug-in

Chapter 1
Introducing the Messaging Server Plug-in API