NameTrans() Example

The ntrans.c file in the samples/nsapi subdirectory of the server root directory contains source code for two example NameTrans functions:

• explicit_pathinfo— Enables the use of explicit extra path information in a URL.

• https_redirect — Redirects the URL if the client is a particular version of Netscape Navigator.

This section discusses the first example. The second example is found in ntrans.c.

A NameTrans function is used primarily to convert the logical URL in ppath in rq->vars to a physical path name. However, the example discussed here, explicit_pathinfo, does not translate the URL into a physical path name. It changes the value of the requested URL. See the second example, https_redirect, in ntrans.c for an example of a NameTrans function that converts the value of ppath in rq->vars from a URL to a physical path name.

The explicit_pathinfo example enables URLs to explicitly include extra path information for use by a CGI program. The extra path information is delimited from the main URL by a specified separator, such as a comma. For example:

http://server-name/cgi/marketing,/jan/releases/hardware

In this case, the URL of the requested resource, a CGI program is http://server-name/cgi/marketing. The extra path information to give to the CGI program is /jan/releases/hardware.

When choosing a separator, be sure to pick a character that is never used as part of a real URL.

The explicit_pathinfo function reads the URL, strips out everything following the comma, and puts the string in the path-info field of the vars field in the request object (rq->vars). CGI programs can access this information through the PATH_INFO environment variable.

One side effect of explicit_pathinfo is that the SCRIPT_NAME CGI environment variable has the separator character appended to the end.

NameTrans directives usually return REQ_PROCEED when they change the path, so that the server does not process any more NameTrans directives. However, in this case name translation needs to continue after the path info is extracted, because the URL to a physical path name has not yet been translated.

Installing the NameTrans Example

To install the function on the Web Server, add the following Init directive to magnus.conf to load the compiled function:

Init fn=load-modules 
     shlib="path" 
     funcs=explicit-pathinfo

Inside the default object in obj.conf, add the following NameTrans directive:

NameTrans fn=explicit-pathinfo 
          separator=","

This NameTrans directive should appear before other NameTrans directives in the default object.

The source code for this example is in the ntrans.c file in the install-dir/smaples/nsapi/directory.