This section discusses the SAF parameters in detail. The parameters are:
pb (parameter block) -- contains the parameters from the directive that invokes the SAF in the obj.conf file.
sn (session) -- contains information relating to a single TCP/IP session.
rq (request) -- contains information relating to the current request.
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:
AuthTrans fn=basic-ncsa auth-type=basic dbm=/sun/server61/userdb/rs |
In this case, the pb parameter passed to basic-ncsa contains name-value pairs that correspond to auth-type=basic and dbm=/Sun/WebServer61/server1/userdb/rs.
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. See Parameter Block Manipulation Routines working with parameter blocks.
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. The following list describes the most important fields in this data structure (seeChapter 7, NSAPI Function Reference NSAPI routines for manipulating the session data structure).
Pointer to a pblock containing information about the client such as its IP address, DNS name, or certificate. If the client does not have a DNS name or if it cannot be found, it will be set to -none.
Platform-independent client socket descriptor. You will pass this to the routines for reading from and writing to the client.
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.
The following list describes the most important fields in this data structure (see Chapter 7, NSAPI Function Reference for information about NSAPI routines for manipulating the request data structure).
Pointer to a pblock containing the server’s “working” variables. This includes anything not specifically found in the following three pblocks. The contents of this pblock vary depending on the specific request and the type of SAF. For example, an AuthTrans SAF may insert an auth-user parameter into rq->vars which can be used subsequently by a PathCheck SAF.
Pointer to a pblock containing elements of the HTTP request. This includes the HTTP method (GET, POST, and so on), the URI, the protocol (normally HTTP/1.0), and the query string. This pblock does not normally change throughout the request-response process.
Pointer to a pblock containing all of the request headers (such as User-Agent, If-Modified-Since, and so on) received from the client in the HTTP request. See Chapter 12, Hypertext Transfer Protocol for more information about request headers. This pblock does not normally change throughout the request-response process.
Pointer to a pblock containing the response headers (such as Server, Date, content-type, Content-Length, and so on) to be sent to the client in the HTTP response. See Chapter 12, Hypertext Transfer Protocol
The rq parameter is the primary mechanism for passing along information throughout the request-response process. On input to a SAF, rq contains whatever values were inserted or modified by previously executed SAFs. On output, rq contains any modifications or additional information inserted by the SAF. Some SAFs depend on the existence of specific information provided at an earlier step in the process. For example, a PathCheck SAF retrieves values in rq->vars that were previously inserted by an AuthTrans SAF.