Writing the Source Code

Write your custom filter methods using NSAPI functions. For a summary of the NSAPI functions specific to filter development, see Overview of NSAPI Functions for Filter Development. For a summary of general purpose NSAPI functions, see Chapter 4, NSAPI Function Reference Each filter method must be implemented as a separate function. See 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. See nsapi_module_init and filter_create for more information.

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 might 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 Chapter 3, Syntax and Use of the magnus.conf File, in Sun Java System Web Proxy Server 4.0.11 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 and Network I/O.

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

• Blocking can affect performance.

• Carefully check and handle all errors.

For examples of custom filters, see server_root/plugins/nsapi/examples and also Chapter 3, Examples of Custom SAFs and Filters