SAF Parameters

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.

pb (parameter block)

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.

The following example shows a directive that invokes the basic-nsca function:

AuthTrans fn=basic-ncsa auth-type=basic dbm=/<Install_Root>
	/<Instance_Directory>/userdb/rs

In this case, the pb parameter passed to basic-ncsa contains name-value pairs that correspond to auth-type=basic and dbm=/<Install_Root>/<Instance_Directory>/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, for a summary of the most commonly used functions for working with parameter blocks.

sn (session)

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 see Chapter 4, NSAPI Function Reference for information about NSAPI routines for manipulating the session data structure.

• sn->client

  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 the name cannot be found, it will be set to -none.

• sn->csd

  Platform-independent client socket descriptor. This value is passed to the routines for reading from and writing to the client.

rq (request)

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 4, NSAPI Function Reference for information about NSAPI routines for manipulating the request data structure.

• rq->vars

  Pointer to a pblock containing the server’s working variables. This pblock includes anything not specifically found in the other three pblocks. The contents of this pblock vary depending on the specific request and the type of SAF. For example, an AuthTrans SAF might insert an auth-user parameter into rq->vars that can be used subsequently by a PathCheck SAF.

• rq->reqpb

  Pointer to a pblock containing elements of the HTTP request. This pblock 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.

  ---

  Note –

  While obtaining the query string associated with a request, the query string is stored in reqpb pblock of the request structure only if the request URL is relative. If the request URL is absolute, the query string is not separated.

  ---

• rq->headers

  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 8, Hypertext Transfer Protocol for more information about request headers. This pblock does not normally change throughout the request-response process.

• rq->srvhdrs

  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 8, Hypertext Transfer Protocol for more information about response headers.

The rq parameter is the primary mechanism for passing information throughout the request-response process. On input to a SAF, rq contains the values that 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.