Writing the Source Code

Write your custom filter methods using NSAPI functions. For a summary of the NSAPI functions specific to filter development, seeOverview of NSAPI Functions for Filter Development and Filter Methods for the filter method prototypes.

The filter must be created by a call to filter_create. Typically, each plug-in defines an nsapi_module_init function that is used to call filter_create and perform any other initialization tasks. For more information, see nsapi_module_init() Function and filter_create() Function.

Filter methods are invoked whenever the server or an SAF calls certain NSAPI functions such as net_write or filter_insert. As a result, filter methods can be invoked from any thread and should only block using NSAPI functions. For example, crit_enter and net_read. If a filter method blocks using other functions, for example, the Windows WaitForMultipleObjects and ReadFile functions, the server could hang. Also, shared objects that define filters should be loaded with the NativeThread="no" flag, as described in Loading and Initializing the Filter.

If a filter method must block using a non-NSAPI function, KernelThreads 1 should be set in magnus.conf. For more information about KernelThreads, see the description in the chapter Syntax and Use of magnus.conf in the Sun Java System Web Server 7.0 Update 2 Administrator’s Configuration File Reference.

Keep the following in mind when writing your filter:

• Write thread-safe code.

• IO should only be performed using the NSAPI functions documented in File I/O.

• Thread synchronization should only be performed using NSAPI functions documented in Threads.

• Blocking might affect performance.

• Carefully check and handle all errors.

For examples of custom filters, see Chapter 4, Examples of Custom SAFs and Filters.