Before Creating Custom SAFs
Before creating custom SAFs, you must understand about the SAF interface and parameters used in Sun Java System Web Server. Also, this section provides information on the future compatibility of custom SAFs. The following topics are covered in this section:
Future Compatibility Issues
To keep your custom plug-ins upgradable, do the following:
- Make sure plug-in users know how to edit the configuration files, such as magnus.conf and obj.conf manually. The plug-in installation software should not be used to edit these configuration files.
- Keep the source code so you can recompile the plug-in.
SAF Interface
All SAFs whether custom or built-in have the same C interface regardless of the request-handling step for which they are written. SAFs are small functions intended for a specific purpose within a specific request-response step. SAFs receive parameters from the directive that invokes them in the obj.conf file, from the server, and from previous SAFs.
The C interface for a SAF is:
int function(pblock *pb, Session *sn, Request *rq);
The next section discusses the parameters in detail.
The SAF returns a result code that indicates whether and how it succeeded. The server uses the result code from each function to determine how to proceed with processing the request. For more information on the result codes, see Result Codes.
SAF Parameters
This section discusses the SAF parameters in detail.
pb (Parameter Block) Parameter
The pb parameter is a pointer to a pblock data structure that contains values specified by the directive that invokes the SAF. A pblock data structure contains a series of name-value pairs.
For example, a directive that invokes the basic-nsca function might look like the following:
AuthTrans fn=basic-ncsa auth-type=basic dbm=users.db
In this case, the pb parameter passed to basic-ncsa contains name-value pairs that correspond to auth-type=basic and dbm=users.db.
NSAPI provides a set of functions for working with pblock data structures. For example, pblock_findval() returns the value for a given name in a pblock. For information on working with parameter blocks, see Parameter Block Manipulation Routines.
sn (Session) Parameter
The sn parameter is a pointer to a Session data structure. This parameter contains variables related to an entire session, that is, the time between the opening and closing of the TCP/IP connection between the client and the server. The same sn pointer is passed to each SAF called within each request for an entire session. For a list of important fields, see Session Data Structure.
rq (Request) Parameter
The rq parameter is a pointer to a Request data structure. This parameter contains variables related to the current request, such as the request headers, URI, and local file system path. The same Request pointer is passed to each SAF called in the request-response process for an HTTP request. For a list of important fields, see Request Data Structure.
Result Codes
Upon completion, a SAF returns a result code. The result code indicates what the server should do next.
The result codes are:
- REQ_PROCEED — Indicates that the SAF achieved its objective. For some request-response steps (AuthTrans, NameTrans, Service, and Error), this code tells the server to proceed to the next request-response step, skipping any other SAFs in the current step. For the other request-response steps (Input, Output, Route, PathCheck, ObjectType, and AddLog), the server proceeds to the next SAF in the current step.
- REQ_NOACTION — Indicates that the SAF took no action. The server continues with the next SAF in the current server step.
- REQ_ABORTED — Indicates that an error occurred and an HTTP response should be sent to the client to indicate the cause of the error. A SAF returning REQ_ABORTED should also set the HTTP response status code. If the server finds an Error directive matching the status code or reason phrase, the server executes the SAF specified. If not, the server sends a default HTTP response with the status code and reason phrase, in addition to a short HTML page reflecting the status code and reason phrase for the user. The server then goes to the first AddLog directive.
- REQ_EXIT — Indicates the connection to the client was lost. This code should be returned when the SAF fails in reading or writing to the client. The server then goes to the first AddLog directive.
Sign up or Log in to add a comment or watch this page.