Write the Source Code

Write your custom SAFs using NSAPI functions. For a summary of some of the most commonly used NSAPI functions, see Overview of NSAPI C Functions. For information about available routines, see Chapter 4, NSAPI Function Reference

For examples of custom SAFs, see nsapi/examples/ in the server root directory, and also see Chapter 3, Examples of Custom SAFs and Filters

The signature for all SAFs is:

int function(pblock *pb, Session *sn, Request *rq);

For more details on the parameters, see SAF Parameters.

The Sun Java System Web Proxy Server runs as a multi-threaded single process. On UNIX platforms there are actually two processes (a parent and a child), for historical reasons. The parent process performs some initialization and forks the child process. The child process performs further initialization and handles all of the HTTP requests.

Keep the following in mind when writing your SAF:

• Write thread-safe code

• Blocking may affect performance

• Write small functions with parameters and configure them in obj.conf

• Carefully check and handle all errors (and log them so you can determine the source of problems and fix them)

If necessary, write an initialization function that performs initialization tasks required by your new SAFs. The initialization function has the same signature as other SAFs:

int function(pblock *pb, Session *sn, Request *rq);

SAFs expect to be able to obtain certain types of information from their parameters. In most cases, parameter block (pblock) data structures provide the fundamental storage mechanism for these parameters. A pblock maintains its data as a collection of name-value pairs. For a summary of the most commonly used functions for working with pblock structures, see Parameter Block Manipulation Routines.

When defining a SAF, you do not specifically state which directive it is written for. However, each SAF must be written for a specific directive (such as AuthTrans, Service, and so on). Each directive expects its SAFs to behave in particular ways, and your SAF must conform to the expectations of the directive for which it was written. For details of what each directive expects of its SAFs, see Required Behavior of SAFs for Each Directive.