ch26.htm

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

supposed to locate a <TT><FONT FACE="Courier">filesystem</FONT></TT>
object for the path supplied. MIME type checks and similar functionality
are handled here. If no objects can be matched to the path in
question, this function returns an error. The <TT><FONT FACE="Courier">path</FONT></TT>
variable is the only one passed to <TT><FONT FACE="Courier">ObjectType</FONT></TT>
functions, like <TT><FONT FACE="Courier">PathCheck</FONT></TT>,
and returns other than <TT><FONT FACE="Courier">REQ_ABORTED</FONT></TT>
are considered a success.
<H4>Service</H4>
<P>
Service functions are the methods that the server uses to reply
to the client's initial request. Usually, the response is automatically
generated based on the type of file being sent back, its location,
or the authorization of the client for the request in question.
Server-Side Includes are parsed before being sent in this stage
of execution, whereas other files just go on their merry way.
<P>
Because Service functions have to take the initiative for sending
the information back to the client, they need to initialize the
response process with the following function call:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">int protocol_start_response(Session *sn,
Request *rq);</FONT></TT>
</BLOCKQUOTE>
<P>
Return codes for the Service class functions can be any of the
following:
<UL>
<LI><TT><FONT FACE="Courier">REQ_PROCEED</FONT></TT>: A response
was sent to the client with no problems.
<LI><TT><FONT FACE="Courier">REQ_NOACTION</FONT></TT>: A Service
function did nothing; the server should execute one of the subsequent
Service directives.
<LI><TT><FONT FACE="Courier">REQ_ABORTED</FONT></TT>: Something
bad has happened, and the server should direct an error to the
client.
<LI><TT><FONT FACE="Courier">REQ_EXIT</FONT></TT>: The Session
should be closed.
</UL>
<H4>General Functions</H4>
<P>
You can use many different functions. The current printed list
is 61 pages, including details. They range from the mundane <TT><FONT FACE="Courier">MALLOC</FONT></TT>
(a cross-platform substitute for the <TT><FONT FACE="Courier">malloc()</FONT></TT>
function in C) to the following fun function (which checks for
URIs containing <TT><FONT FACE="Courier">../</FONT></TT> or <TT><FONT FACE="Courier">//</FONT></TT>
and returns <TT><FONT FACE="Courier">1</FONT></TT> if they do
or <TT><FONT FACE="Courier">0</FONT></TT> if they don't):
<BLOCKQUOTE>
<TT><FONT FACE="Courier">int util_uri_is_evil(char *t);</FONT></TT>
</BLOCKQUOTE>
<P>
Whatever task you want to perform, you can choose from literally
dozens of functions, because you are at the base level of the
server itself-anything that it does, you can do as well. Most
of the functions that you will need for your server will likely
involve reading data from the client, such as <TT><FONT FACE="Courier">pblock_findval()</FONT></TT>
for grabbing the request method, or sending back messages, such
as the <TT><FONT FACE="Courier">protocol_status()</FONT></TT>
for sending server error codes to the client.
<P>
The complete list is available as part of the NSAPI Development
White Papers and Technical Notes, all of which you can find at
<TT><FONT FACE="Courier"><A HREF="http://help.netscape.com">http://help.netscape.com</A></FONT></TT>.
In addition, developers who are part of the Netscape Developer's
program can obtain further information through the Developer's
Technical Library. For further details, visit <TT><FONT FACE="Courier"><A HREF="http://developer.netscape.com">http://developer.netscape.com</A></FONT></TT>
to see what's available to the general public and what's available
to registered developers.
<H4>Error Reporting</H4>
<P>
Reporting when problems occur is important. As I just mentioned,
the <TT><FONT FACE="Courier">protocol_status()</FONT></TT> function
enables you to send back information to the client in the form
of a traditional server error code. The syntax for the function
is as follows:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">void protocol_status(Session *sn, Request
*rq, int n, char *r);</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">Session</FONT></TT> and <TT><FONT FACE="Courier">Request</FONT></TT>
structures establish which user session and for which request
the error is being generated, to be sure it goes to the right
place. To specify which error you want to send back, you can use
the <TT><FONT FACE="Courier">r</FONT></TT> string to enter your
own specific reason that the process encountered an error, and
the <TT><FONT FACE="Courier">n</FONT></TT> int to specify one
of the available error codes listed in Table 26.5. If you do not
specify a string in <TT><FONT FACE="Courier">r</FONT></TT>, the
string sent to the client defaults to <TT><FONT FACE="Courier">Reason
Unknown</FONT></TT>.<BR>
<P>
<CENTER><B>Table 26.5. Acceptable server error codes.</B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><CENTER><I>Value</I></CENTER></TD><TD WIDTH=282><CENTER><I>Error Code</I></CENTER>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>200</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_OK</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>204</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_NO_RESPONSE</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>302</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_REDIRECT</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>304</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_NOT_MODIFED</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>400</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_BAD_REQUEST</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>401</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_UNAUTHORIZED</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>403</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_FORBIDDEN</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>404</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_NOT_FOUND</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>407</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_PROXY_UNAUTHORIZED</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>500</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_SERVER_ERROR</FONT></TT>
</TD></TR>
<TR><TD WIDTH60><TT><FONT FACE="Courier"><CENTER>501</FONT></TT></TD>
<TD WIDTH=282><TT><FONT FACE="Courier">PROTOCOL_NOT_IMPLEMENTED</FONT></TT>
</TD></TR>
</TABLE></CENTER>
<P>
<H2><A NAME="ImplementationConsiderations"><FONT SIZE=5 COLOR=#FF0000>Implementation
Considerations</FONT></A></H2>
<P>
When you're ready to take the plunge into developing NSAPI functions,
or you're at least looking at them seriously, you should be aware
of a couple of points that will affect both how easy it will be
to develop your solution and where you can use that solution.
I describe these points in the following sections.
<H3><A NAME="CrossPlatformCapabilities">Cross-Platform Capabilities</A>
</H3>
<P>
Who said, &quot;You can't take it with you&quot;? One of the great
things about the NSAPI is that it's cross-platform. Currently,
it is supported with Netscape products on several UNIX platforms
as well as Windows NT, and that list is bound to grow with time.
Because the internal function calls remain exactly the same from
platform to platform, all you need to worry about is the C code
that does the processing for your particular functions.
<H3><A NAME="InformationalResources">Informational Resources</A>
</H3>
<P>
A growing amount of information is available on the NSAPI, but
it is still in the early stages of development. You can obtain
the best resources available through the Netscape Developer's
program, called DevEdge, or through taking one of the Netscape
training courses on the NSAPI, which were started in the second
quarter of 1996. In public newsgroups, you also can find a number
of people making use of the NSAPI, as it encompasses a wide range
of programming topics. Secured newsgroups on Netscape's site,
for registered developers, have a high turnout rate for questions
and answers, and they provide the added benefit of serving as
a link to Netscape support personnel and advanced developers.
<P>
A growing number of developers are also beginning to offer commercial
services for functions such as helping you determine how you might
move a CGI function into NSAPI functionality or designing server
extensions from the ground up.
<H3><A NAME="ProgrammingKnowledge">Programming Knowledge</A></H3>
<P>
API programming is much easier to approach if you're already a
C programmer. If you are, you're well on your way to taking advantage
of all the power that API has to offer. If you're not a C programmer,
however, or you work with a group with limited time for developing
constantly changing functions, you may want to consider how you
would go about making NSAPI functions and whether they're worth
the time and effort. CGI programming still maintains one significant
advantage over API programming-it's easy to do, in any language.
If all your development experience is in Perl, you may not be
willing to invest the considerable time and frustration it will
take to learn C and become fluent enough in it to code advanced
and robust functions. For many people, this decision will be the
biggest obstacle to developing their functions and one of the
factors that will limit API development impact on the general
server marketplace.
<P>
With all the resources available and with training under your
belt, you might begin to wonder if API programming is a good direction
to be going in. After all, programming these functions is very
specific to servers that support the NSAPI standard, and this
programming is somewhat involved. Is it worth all the effort?
The answer to this question depends on whom you ask, but the majority
opinion is that this type of programming is definitely an area
in which you should become well versed. CGI will probably never
go away. Its quick and dirty, easily implemented data processing
functions are always needed, and it's just way too much fun. Corporate-level
solutions, however, are increasingly demanding and increasingly
standards oriented.
<H3><A NAME="Debugging">Debugging</A></H3>
<P>
To debug a built-in server function, you must rely heavily on
your faith in your code because some possible symptoms can occur
due to an errant return from your code or a slight error in placing
data within a <TT><FONT FACE="Courier">pblock</FONT></TT>. One
of the best considerations is to include a logging function within
your function so that a look at the system's error logs can at
least help you pinpoint if your function is doing anything and
what data it has.
<P>
Here is one relatively common pitfall to avoid when calling NSAPI
functions through references in an HTML page. When they're being
referenced in a form element like this
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;FORM METHOD=&quot;POST&quot; ACTION=&quot;/cgi-bin/nsapi/blah.useaction&quot;&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
you must have a file called blah.useaction in <TT><FONT FACE="Courier">/cgi-bin/nsapi</FONT></TT>.
The file doesn't need to have anything in it (it can be a shopping
list or a doghouse blueprint), but the file itself needs to exist
because the server first checks the validity of the file by using
the <TT><FONT FACE="Courier">PathCheck</FONT></TT> class. If the
server doesn't see a file there, it fails and doesn't do what
you want it to do.
<H2><A NAME="TheFutureoftheNSAPI"><FONT SIZE=5 COLOR=#FF0000>The
Future of the NSAPI</FONT></A></H2>
<P>
Standards are a big issue when it comes to the Internet. All companies
want their technology to be the one that everyone else adopts
because money rides on being the leader. To this point, Netscape
has dominated the commercial sector in developing Internet standards,
or at least close enough to it that they might as well be the
leader. By proposing the NSAPI as a standard, the folks at Netscape
have positioned themselves to try to take the lead in server extensions,
just as they have in creating demand for the HTML tags that they've
adopted ahead of scheduled standards implementation.
<P>
The NSAPI is not alone in the race for standardization, however.
The Internet Server API (ISAPI), created by Microsoft and Process
Software (<A HREF="ch25.htm" >see Chapter 25</A> for more details
on ISAPI), is generating its own band of followers. In addition,
other entries into the fray exist as well, either existing as
something similar to NSAPI or ISAPI or as something completely
different. In the face of competition from two industry giants,
though, how can standardization of other entries succeed when
they aren't part of either larger camp's proposal?
<P>
Would it be possible to meet somewhere in the middle? Not easily,
and not likely. The NSAPI is heavily tied to the inner workings
of the server itself, relying on the obj.conf and magnus.conf
files, whereas the ISAPI standard goes more along the line of
Microsoft's traditional DLL additions with message hooks.
<P>
Who has the advantage? Again, the answer to this question depends
on whom you ask. Independent research agencies have reported conflicting
information about who's in the lead and which implementation of
the API functions is better suited for standardization. The real
advantage, however, currently lies in the Netscape camp because
of cross-platform capabilities. Microsoft's push is currently
for NT as a substitute server platform for UNIX, but with the
number of UNIX boxes already in use, a large and stubborn group
of the more advanced developers doesn't want to switch platforms
and server software just to take advantage of the API functions.
<P>
I'm not saying that the battle for who's in the lead is over,
by any means. Microsoft has never been shy about pursuing its
goals for market share, and if they feel that they're at a disadvantage,
they'll fight even harder to become top dog. For the moment, however,
Netscape maintains the edge that may well determine what direction
the more serious developers go in.
<P>
Is all this competition good news for you, as an individual? Sure.
It means that more powerful functions will surely be developed
for a whole range of Web servers. If you're a developer, you've
got a new marketplace to play in. If you're a user, many of the
tasks that you perform on the Web could become faster and more
powerful. No matter from which angle you look at this competition,
it's a win-win situation for everyone.
<H2><A NAME="Summary"><FONT SIZE=5 COLOR=#FF0000>Summary</FONT></A>
</H2>
<P>
The Netscape Server API is a powerful tool for customizing your
Web server and making it jump through the hoops you need it to.
NSAPI is not a replacement for CGI because people will always
have a need for the role CGI plays. But NSAPI can perform the
same functions, be called in the same manner, and do it all with
less work for your server. These benefits are balanced by its
being harder for developers to get up to speed and create stable
functions. After you're familiar with the way NSAPI works and
have had the chance to experiment, you'll understand why it's
a great tool to have around.
<P>
<HR WIDTH="100%"></P>

<CENTER><P><A HREF="ch25.htm"><IMG SRC="pc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="#CONTENTS"><IMG SRC="cc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="index.htm"><IMG SRC="hb.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="ch27.htm"><IMG 
SRC="nc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A></P></CENTER>

<P>
<HR WIDTH="100%"></P>

</BODY>
</HTML>