The ntrans.c file in the samples/nsapi subdirectory of the server root directory contains source code for two example NameTrans functions:
explicit_pathinfo
This example allows the use of explicit extra path information in a URL.
https_redirect
This example redirects the URL if the client is a particular version of Netscape Navigator.
This section discusses the first example. Look at the source code in ntrans.c for the second example.
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 allows 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 (which would be a CGI program) is http://server-name/cgi/marketing, and 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 the real URL.
The explicit_pathinfo function reads the URL, strips out everything following the comma, and puts it 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 tacked onto 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 we want name translation to continue after we have extracted the path info, since we have not yet translated the URL to a physical path name.
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.