To accomplish each of the request response steps, a set of server application functions are used in each step. These functions take the client's request and the server's configuration variables as input and return a response to the server as output.

Server application functions belong to a particular class that corresponds to the directive they're called with in the configuration files. The functions appear after the directive type in obj.conf. You use the format:

directive fn="yourfunction" value="v1" … value="vn"

directive is the directive the function belongs to (for example, AuthTrans). You can then send any number of optional values to your function as arguments you specify in obj.conf. For example, you could create a NameTrans function called myfunc1 that takes a URL path as a value and maps it to a hard-coded path specified in your function. The entry in obj.conf might look like this:

NameTrans fn="myfunc1" path="/special/docs"

The response can tell the server to do the following (REQ stands for request):

There is an additional class of application function, called initialization functions, that run when the server starts. They perform static data initialization for the various server modules. Server application functions and the custom functions you create work with a single directive class.

---

Note: Before you can use any of your custom server application functions, you must tell the server to load the functions. You do this in magnus.conf. The full process is described later in this chapter.

---

The pb_param structure is used to manage the name=value pairs for each client request. The pb_entry

structure creates linked lists of pb_param structures.

The pblock is the hash table that holds these pb_entry structures. Its contents are transparent to most code.

#include “base/pblock.h”

typedef struct {
    char *name,*value;
} pb_param;

struct pb_entry {
    pb_param *param;
    struct pb_entry *next;
};

typedef struct {
    int hsize;
    struct pb_entry **ht;
} pblock;

All server application functions (regardless of class) are described by the following prototype:

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

pb is the parameter block with the parameters given by the site administrator for this function invocation. This parameter should be considered read-only, and any data modification should be performed on copies of the data. Doing otherwise is unsafe in threaded server architectures, and will yield unpredictable results in multiprocess server architectures.

When adding, removing, editing, and creating name=value pairs, you use the following functions. This list might seem overwhelming, but you'll use only a handful of these functions in your custom application functions. For a more detailed look, see the code in the header file /base/pblock.h.

FUNCTION

pb_param *param_create(char *name, char *value);

The param_create function creates a parameter with the given name and value. If name and value aren't NULL, they are copied and placed into the new pb_param structure.

FUNCTION

int param_free(pb_param *pp);

The param_free function frees a given parameter if it's non-NULL, and it returns 1 if pp was non-NULL and returns 0 if pp was NULL. This is also useful for error checking before using pblock_remove.

FUNCTION

pblock *pblock_create(int n);

The pblock_create function creates a new pblock with a hash table of size n. It returns the newly allocated pblock.

FUNCTION

void pblock_free(pblock *pb);

The pblock_free function frees the given pblock and any entries inside it. If you want to save anything in a pblock, remove its entities with pblock_remove first and then save the pointers you get.

FUNCTION

pblock *pblock_find(char *name, pblock *pb);

The pblock_find function finds the name=value entry with the given name in pblock pb. If it's successful, it returns the param block. If not, it returns NULL. You then use pblock_findval to get the actual value in the name=value pair.

---

Note: This function is actually a macro that calls a separate function with a hard-coded third parameter.

---

FUNCTION

char *pblock_findval(char *name, pblock *pb);

The pblock_findval function finds the name=value entry with the given name in pblock pb and returns its value; otherwise, it returns NULL.

FUNCTION

pblock *pblock_remove(char *name, pblock *pb);

The pblock_remove function behaves exactly like pblock_find, but it removes the given entry from pb.

This function is actually a macro that calls a separate function with a hard-coded third parameter.

FUNCTION

pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);

The pblock_nvinsert function creates a new parameter with the given name and value and inserts it into pblock pb. The name and value in the parameter are also newly allocated. Returns the pb_param it allocated (in case you need it).

FUNCTION

void pblock_pinsert(pb_param *pp, pblock *pb);

The pblock_pinsert function inserts a pb_param into a pblock.

FUNCTION

int pblock_str2pblock(char *str, pblock *pb);

The pblock_str2pblock function scans the given string str for parameter pairs in the format name=value or name="value". Any backslash (“\”) must be followed by a literal character. If string values are found with no unescaped equal (“=”) signs (no name=), it assumes the names 1, 2, 3, and so on depending on the string positions (zero doesn't count). For example, if it finds "some" "strings" "together", the function treats the strings as if they appeared in the name=value pairs as 1="some" 2="strings" 3="together".

This function returns the number of parameters added to the table, or it returns -1 if it encounters an error.

FUNCTION

char *pblock_pblock2str(pblock *pb, char *str);

The pblock_pblock2str function places all of the parameters in the given pblock into the given string (NULL if it needs creation). It will re-allocate more space for the string. Each parameter is separated by a space and of the form name=”value”

A session is the time between the opening and the closing of the connection between the client and the server. The Session data structure holds variables that apply session wide, regardless of the requests being sent, as shown in the following code.

#include “base/session.h”

typedef struct {
    /* Information about the remote client */
    pblock *client;

    /* The socket descriptor to the remote client */
    SYS_NETFD csd;
    /* The input buffer for that socket descriptor */
    netbuf *inbuf;

   /* Raw socket information about the remote */
   /* client (for internal use) */
    struct in_addr iaddr;
} Session;

The client parameter block used in the previous Session structure contains two entries:

With HTTP there is only one request per session. The following structure contains the variables that apply to the request in that session (for example, the variables include the client's HTTP headers):

#include “frame/req.h”

typedef struct {
    /* Server working variables */
    pblock *vars;

    /* The method, URI, and protocol revision of this request */
    pblock *reqpb;
    /* Protocol specific headers */
    int loadhdrs;
    pblock *headers;

    /* Server's response headers */
    pblock *srvhdrs;

    /* The object set constructed to fulfill this request */
    httpd_objset *os;

    /* The stat last returned by request_stat_path */
    char *statpath;
    struct stat *finfo;
} Request;

vars

are the server's working variables. The set of active variables is different depending on which step of the request the server is processing, as discussed in “Conditions for Each Function Class”.

reqpb contains the request parameters that are sent by the client:

If more than one header has the same name, then they are concatenated with commas as follows:

			Name: value1, value2

The parameter block is keyed on the fully lowercase version of the name string without the colon. Application functions should not access this pblock directly, but instead use the function request_header, which finds the named header depending on the requesting protocol.

FUNCTION

#include “frame/req.h”
int request_header(char *name, char **value, Session *sn, Request *rq);

Name should be the lowercase header name string to look for, and value is a pointer to your char * that should contain the header. If no header with the given name was sent, value is set to NULL.

The server might not load headers until the first header is requested. This increases performance when talking to certain NCSA products. This option is not currently active.

If this option is active, the function can return REQ_ABORTED. If it does, your function should return REQ_ABORTED. On success, this returns REQ_PROCEED.

---

Caution: Currently, it's safe to access the pblock instead of using this function, but this behavior should not be relied upon.

---

The srvhdrs pblock in the Sessions structure is the set of HTTP headers for the server to send back. This pblock can be modified by any function.

The last three entries in the Session request structure should be considered transparent to application code because they are used by the server's base code.

After the server has a path for the file it intends to return, application functions should use the following call to obtain stat() information about the file:

#include “frame/req.h”

/*
 * request_stat_path tries to stat path. If path is NULL, it will look in
 * the rq->vars pblock for “path”. If the stat is successful, it returns the
 * stat structure. If not, returns NULL and copies an error message into err. 
 * If a previous call to this function was successful, and path is the same,
 * the function will simply return the previously found value.
 *
 * Application functions should not free this structure.
 */

struct stat *request_stat_path(char *path, char *err, Request *rq);

Using this function avoids multiple, unnecessary calls to stat().

When your custom application function is done working with the name=value pairs, it must return a status code that tells the server how to proceed with the request. The following integer return codes are available to server application functions:

When problems occur, the server application functions should set server status codes that give the client an idea of what went wrong. The function should also log an error in the server error log file.

There are two interfaces for reporting errors: setting a response code and reporting an error.

Setting a Response Status Code

The protocol_status function sets the status to the code and reason string. If the reason is NULL, the server attempts to match a string with the given status code (see Table 2-2). If it can't find a string, it uses “Because I felt like it.”

#include “frame/protocol.h”
void protocol_status(Session *sn, Request *rq, int n, char\ *r);

Generally, protocol_status will be called with a NULL reason string, and one of the following status codes defined in protocol.h. (If no status is set, the default is PROTOCOL_SERVER_ERROR.)

When errors occur, it's customary to report them in the server's error log file. To do this, your custom functions should call log_error. This logs an error and then returns to tell you if the log was recorded successfully (a return value of 0 means success, -1 means failure).

#include “frame/log.h”

/*
 * log_error formats the arguments with the printf() style fmt.  
 * Returns whether the log was successful.
 * It also records the current date.
 * sn and rq are optional parameters. If specified, information
 * about the client is reported.
 */
int log_error(int degree, char *func, Session *sn, Request *rq, char *fmt, ...);

You can give log_error any printf() style string to describe the error. If an error occurs after a system call, use the following function to translate an error number to an error string:

#include “base/file.h”

char *system_errmsg(SYS_FILE fd);

---

Note: The fd parameter is vestigial under IRIX and might need to be changed for other operating systems.

---

Authorization is split into two steps. First, the authorization data sent by the client (if any) is decoded and verified against internal databases. If the data is valid, it should be stored into the Request->vars pblock. In the second step, this data is compared against the required authorization for the requested path (performed in a PathCheck class function).

There is no reason that both of these steps could not be performed in one AuthTrans or one PathCheck directive; however, the steps are split for flexibility and for supporting the HTTP SSL protocol.

There are no variables active in the Request->vars pblock upon entry to an AuthTrans function. Upon successful translation and function exit, the following variables are customarily set:

Of course, the flexibility of the pblock structure lets AuthTrans functions define their own custom variables that can later be retrieved by the PathCheck function that implements the second step.

Upon return, the AuthTrans function should return REQ_ABORTED if the request is to be aborted, REQ_NOACTION if the translation was unsuccessful, or REQ_PROCEED if successful.

NameTrans class functions are used to translate a virtual path sent by the client into a physical path as used by the server.

The following variables are active in the Request->vars pblock for NameTrans functions:

Upon return, the REQ return codes have the following meaning:

PathCheck class functions are used to verify that a given path is safe to return to a given client. This class of functions performs various system-specific URL filtering and screening actions, authorization checks, access control, searches for CGI extra path information, and other functions.

The system only defines one variable for PathCheck functions in Request->vars: path is the path resulting from the execution of all NameTrans directives. Any variables that have been created by previous NameTrans or AuthTrans directives are also active.

On return, a code other than REQ_ABORTED is considered a success.

ObjectType functions take the path resulting from the previous directives and locate a filesystem object for the path. If none exists and none of the PathCheck directives have looked yet, the current ObjectType routines return an error to the client.

ObjectType directives receive no special variables aside from path in Request->vars and the variables defined by the previous directives. Upon return, a code other than REQ_ABORTED indicates success.

The server's base functionality library provides mechanisms for typing files natively to the host's operating system. Under most systems, this consists of filename extension recognition code.

Service functions send the server's reply to the client. The function is generally selected by the directory the file resides in or the type of the file being sent. Most files are simply mapped into memory and sent to the client. Some types of documents run as system programs and others are parsed before being sent to the client.

Service directives receive no special variables aside from path in Request->vars and the variables defined by the previous directives.

The REQ return codes are defined for Service class functions as follows:

The Service class functions need to start the protocol-specific response process for the server. They do this through the following function:

int protocol_start_response(Session *sn, Request *rq);

If this function returns REQ_NOACTION, then the body response should be skipped and the application function should return successfully. Otherwise, this function returns REQ_PROCEED.

If cross platform considerations are not required, then operating-system specific I/O calls can be made by Service functions.