ch26.htm

CGI programming is the hottest stuff to look out for in this book

</TD></TR>
<TR><TD WIDTH=188>Response to Request</TD><TD WIDTH=402>Generate appropriate feedback
</TD></TR>
<TR><TD WIDTH=188>Logging of Transaction</TD><TD WIDTH=402>Save information about the transaction to logging files
</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="ServerApplicationFunctions">Server Application Functions</A>
</H3>
<P>
To get from the beginning to the end of the whole Request/Response
process, each one of these steps has its own internal server functions,
called <I>server application functions</I>. These internal functions,
which are known to the server, help it do its job. These functions
can be separated into classes, called <I>function classes</I>,
to best describe what each internal function relates to and to
help with organizing the design process. Each function class relates
to one or more of the processes that take place when the server
answers a client's call for data. Though Netscape's breakdown
of the HTTP Request/Response process has six steps, only five
classes are used because one serves double duty. Table 26.2 lists
these classes in order of execution and tells to which of the
six steps shown in Table 26.1 they map.<BR>
<P>
<CENTER><B>Table 26.2. NSAPI function classes.<BR>
</B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><CENTER><I>Class</I></CENTER></TD><TD WIDTH=401><CENTER><I>Function</I></CENTER>
</TD></TR>
<TR><TD WIDTH=118><TT><FONT FACE="Courier">AuthTrans</FONT></TT>
</TD><TD WIDTH=401>Performs Authorization Translation</TD></TR>
<TR><TD WIDTH=118><TT><FONT FACE="Courier">NameTrans</FONT></TT>
</TD><TD WIDTH=401>Performs Name Translation</TD></TR>
<TR><TD WIDTH=118><TT><FONT FACE="Courier">PathCheck</FONT></TT>
</TD><TD WIDTH=401>Performs Path Checks</TD></TR>
<TR><TD WIDTH=118><TT><FONT FACE="Courier">ObjectType</FONT></TT>
</TD><TD WIDTH=401>Performs Object Type Check</TD></TR>
<TR><TD WIDTH=118><TT><FONT FACE="Courier">Service</FONT></TT>
</TD><TD WIDTH=401>Performs Response to Request and Logging of Transaction
</TD></TR>
</TABLE></CENTER>
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD><BLOCKQUOTE>
For more detailed information on each of these functions, including what types of response codes and errors they can generate, see &quot;Functions, Variables, and Their Responses&quot; later in this chapter.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="ControllingFunctionUse">Controlling Function Use</A>
</H3>
<P>
At every step along the way, the server needs to know what functions
take priority and what additional functions are available. Although
the function classes have their own special order of working,
control within each class of function is administered by the server's
configuration files. To make use of your own function, you need
to know how to define the function in these configuration files
and what the configuration files themselves are.
<H4>Function Declaration</H4>
<P>
All server application functions, regardless of what they do,
get referenced in the same way. They let the server know what
function class they belong to, what the name of the function is,
and which values need to be passed to the function itself. An
example of this kind of function declaration is as follows:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">class fn=functionname value1=data1 ..
valueN=dataN</FONT></TT>
</BLOCKQUOTE>
<P>
You may also see <TT><FONT FACE="Courier">directive</FONT></TT>
substituted for <TT><FONT FACE="Courier">class</FONT></TT>. You
say potato, they say potato.
<H4>Configuration: UNIX</H4>
<P>
When you configure a UNIX-based Netscape server to use a function,
you do so through the use of two files: magnus.conf and obj.conf.
<P>
<B><FONT SIZE=4>magnus.conf</FONT></B>
<P>
The magnus.conf file is the server's master controller. It contains
the instructions and directives that the server has to take into
account when it first starts up. The magnus.conf file sets up,
for example, the server's name, port number, and what functions
to load into memory. When you develop an NSAPI function, magnus.conf
is the starting point for making sure that your function is available
for use. You specify that you want the server, on initialization,
to load the module that you've created which holds your function.
You also give it any aliases that might be used for your function,
as in the following example:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Init fn=load-module shlib=/usr/me/mymodule.so
funcs=myfunction</FONT></TT>
</BLOCKQUOTE>
<P>
<TT><FONT FACE="Courier">Init</FONT></TT> specifies that this
process is to be performed upon initialization. Next, you instruct
the server to use its default <TT><FONT FACE="Courier">load-modules</FONT></TT>
function to load your module, and you provide the full path to
that module within the <TT><FONT FACE="Courier">shlib</FONT></TT>
(shared library) parameter. The <TT><FONT FACE="Courier">mymodule.so</FONT></TT>
file is a shared object, which I discuss in the &quot;Functions
and Features&quot; section. Finally, you provide the alias (or
aliases) for your function so that you can reference it later.
<P>
<B><FONT SIZE=4>obj.conf</FONT></B>
<P>
When the server is running, obj.conf is in command. All requests
that come to the server get analyzed through the order and method
specified in obj.conf to determine what should happen. The breakdown
order of the HTTP Request/Response process that you examined in
Table 26.1 occurs here. Your particular function is specified
somewhere in the obj.conf, depending on what class of function
it is and what you want it to do, and the server goes through
each function in class order and then function order to see what
should happen.
<P>
One example of this process is a function supplied by Netscape;
it takes a URL path as a value and then maps that value to a hard-coded
path on your system. Essentially, it creates a symbolic path link.
This function's entry in the obj.conf file follows the basic function
declaration:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NameTrans fn=makepath path=/usr/mine/stuff</FONT></TT>
</BLOCKQUOTE>
<P>
Here the function is in the <TT><FONT FACE="Courier">NameTrans</FONT></TT>
function class, because it should occur as the server is mapping
file locations. The function itself is called <TT><FONT FACE="Courier">makepath</FONT></TT>;
it accepts only one value, a hard-coded path.
<H4>Configuration: NT</H4>
<P>
Windows NT relies on a different mechanism for controlling server
processes, but the basic premise is still the same. Different
sections in the Windows NT registry correspond to the purposes
of the magnus.conf and obj.conf files, so you just make the entries
there instead.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Caution</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
Be extremely careful when doing anything to the Windows NT registry. Whereas messing up an obj.conf or a magnus.conf file would only create problems for your server, the NT registry controls all actions on your system. You could ruin your whole week if you 
accidentally delete or modify something. Before you modify anything, make a backup copy of the registry for safekeeping, or make a system disk that can restore your current configuration.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
You modify the Windows NT registry by running the regedt32.exe
program. You should look for the <TT><FONT FACE="Courier">HKEY_LOCAL_MAchINE\Software\Netscape\Httpd-80</FONT></TT>
section. Remember, this is your entire system configuration, so
be careful!
<P>
<B><FONT SIZE=4>StartUp Key</FONT></B>
<P>
Under the <TT><FONT FACE="Courier">Httpd-80</FONT></TT> section
is <TT><FONT FACE="Courier">CurrentVersion\StartUp</FONT></TT>,
which controls the startup processes of the Netscape server. This
controls what functions are loaded into memory when the Netscape
server runs as an NT service. To add your own entry, you create
a new key in the StartUp folder by choosing Edit | Add Key and
then entering <TT><FONT FACE="Courier">InitFunction01</FONT></TT>
(or <TT><FONT FACE="Courier">InitFunction02</FONT></TT> if <TT><FONT FACE="Courier">InitFunction01</FONT></TT>
is already there) in the Key Name value, leaving the Class entry
blank for now. You then add values to the key, as shown here:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">fn: load-modules<BR>
shlib: c:\netscape\stuff\mymodule.dll<BR>
funcs: myfunction</FONT></TT>
</BLOCKQUOTE>
<P>
Here you're specifying that the server use its own <TT><FONT FACE="Courier">load-modules</FONT></TT>
function to place the shared library (<TT><FONT FACE="Courier">shlib</FONT></TT>)
of <TT><FONT FACE="Courier">c:\netscape\stuff\mymodule.dll</FONT></TT>
into memory. Files with a .dll extension are Windows Dynamic Linked
Libraries (DLLs), which allow their functions to be shared by
other processes on the system. You're also telling the server
that the alias for this particular function is <TT><FONT FACE="Courier">myfunction</FONT></TT>.
<P>
<B><FONT SIZE=4>Directive Keys</FONT></B>
<P>
To convince the server that your function should be called, now
that you've specified that it should be loaded, you need to determine
where your function fits into the general scheme of things. To
start with, go into the <TT><FONT FACE="Courier">CurrentVersion\Objects</FONT></TT>
registry folder and check through the objects listed to see which
one of them has the <TT><FONT FACE="Courier">name: default</FONT></TT>
value.
<P>
Next, you need to look under that object, in its directive keys,
to find the Directive (class) under which your application falls.
If your function is supposed to take place as a logging request,
for example, you should see if you can find a directive key with
a value of <TT><FONT FACE="Courier">Directive: Addlog</FONT></TT>.
If one doesn't exist, you can add it.
<P>
After you find (or create, which is less likely) the directive
key your function should be part of, you need to add a new function
underneath that Directive folder. This time, you just specify
the function and any necessary values. A simple case would be
just the function itself, as shown here:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">fn: myfunction</FONT></TT>
</BLOCKQUOTE>
<P>
Here you're just saying, &quot;When you run through this group
of functions, be sure to call <TT><FONT FACE="Courier">myfunction</FONT></TT>
as well!&quot;
<H4>Initializing the Server</H4>
<P>
After you make any changes, regardless of which platform you make
them on, you need to shut down the server and restart so that
it loads the new functions. Sending the server a Restart signal
isn't enough because the signal is not going to cause the server
to load the new functions specified in either magnus.conf or the
StartUp registry key. Make sure that you completely shut down
the server and then start it back up again.
<P>
One thing to keep in mind is that certain modules may need to
be explicitly instructed to stop what they're doing before the
server starts up again; otherwise, you could end up with two instances
of a process running, wasting space and even causing conflicts.
To clean up those processes, you can use the <U>atrestart()</U>
function, defined as
<BLOCKQUOTE>
<TT><FONT FACE="Courier">void magnus atrestart(void (*fn) (void
*), void *data)</FONT></TT>
</BLOCKQUOTE>
<P>
This is called by the server during restart, not during termination,
with the data pointer being passed in as the argument for the
function call.
<H2><A NAME="FunctionsandFeatures"><FONT SIZE=5 COLOR=#FF0000>Functions
and Features</FONT></A></H2>
<P>
To create an NSAPI function, you need to know what it's built
of-what data structures and general functions are necessary and
available to make your idea for a function become reality.
<H3><A NAME="ServerApplicationFunctionPrototype">Server Application
Function Prototype</A></H3>
<P>
Just as all server application functions are defined the same
way in the configuration files for how they're accessed, all the
functions are defined the same way in your actual code. This ensures
that they are compatible with the other processes the server is
performing and that they can access the server's data in a timely
manner. The prototype that follows is Netscape's required definition
for each function:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">int function(pblock *pb, Session *sn,
Request *rq);</FONT></TT>
</BLOCKQUOTE>
<H4>Response Codes</H4>
<P>
To determine the outcome of the function, the integer return from
the function must correspond to the available response code, as
listed in Table 26.3.<BR>
<P>
<CENTER><B>Table 26.3. Acceptable server application function
response codes.</B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><CENTER><I>Code</I></CENTER></TD><TD WIDTH=60><CENTER><I>Value</I></CENTER>
</TD><TD WIDTH=393><CENTER><I>Definition</I></CENTER></TD></TR>
<TR><TD WIDTH=138><TT><FONT FACE="Courier">REQ_PROCEED</FONT></TT>
</TD><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>0</FONT></TT></TD>
<TD WIDTH=393>The function has performed its task; proceed with the remainder of the request.
</TD></TR>
<TR><TD WIDTH=138><TT><FONT FACE="Courier">REQ_ABORTED</FONT></TT>
</TD><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>-1</FONT></TT></TD>
<TD WIDTH=393>An error occurred; the entire request should be aborted at this point.
</TD></TR>
<TR><TD WIDTH=138><TT><FONT FACE="Courier">REQ_NOACTION</FONT></TT>
</TD><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>-2</FONT></TT></TD>
<TD WIDTH=393>The function didn't accomplish what it wanted to do, but the request should proceed.
</TD></TR>
<TR><TD WIDTH=138><TT><FONT FACE="Courier">REQ_EXIT</FONT></TT>
</TD><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>-3</FONT></TT></TD>
<TD WIDTH=393>Close the session and exit.</TD></TR>
</TABLE></CENTER>
<P>
<P>
Depending on the class of function, different interpretations
for the returns are available, as you learn in the section &quot;Functions,
Variables, and Their Responses.&quot;
<H3><A NAME="ParameterBlocks">Parameter Blocks</A></H3>
<P>
The parameter block (<TT><FONT FACE="Courier">pblock</FONT></TT>)
data structure is the amino acid of NSAPI functions. Because servers
deal with information based on <TT><FONT FACE="Courier">name=value</FONT></TT>
pairs, <TT><FONT FACE="Courier">pblock</FONT></TT> is a hash table
that is keyed on the name string, which then allows the function
to map names to values.
<P>
The data structures used when dealing with parameter blocks are
shown in Listing 26.1. The <TT><FONT FACE="Courier">name=value</FONT></TT>
pairs are stored in the <TT><FONT FACE="Courier">pb_param</FONT></TT>
structures, which are in turn used inside <TT><FONT FACE="Courier">pb_entry</FONT></TT>
to create linked lists of the <TT><FONT FACE="Courier">pb_param</FONT></TT>
structures. The hash table itself (<TT><FONT FACE="Courier">pblock</FONT></TT>)
is defined in Listing 26.2, though it is subject to change by
Netscape and is normally transparent to most functions.
<HR>