cgic.html

基于嵌入式Linux的WEB_CGI开发例程

cgic is distributed via the web in two forms: as a Windows-compatible
.ZIP file, and as a gzipped tar file. Most users of Windows and
related operating systems have access to 'unzip' or 'pkunzip'. All modern Unix 
systems come with 'gunzip' and 'tar' as standard equipment, and gzip/gunzip
is not difficult to find if yours does not. Versions
of these programs for other operating systems are widely
available if you do not already have them.
<p>
<strong>Important:</strong> to use cgic, you will need an ANSI-standard
C compiler. Under Unix, just obtain and use gcc. Most Unix systems have
standardiszed on gcc. Users of Windows operating systems should not have
ANSI C-related problems as all of the popular compilers follow the ANSI 
standard.
<p>
<strong>Note for Windows Programmers:</strong> you must use a modern
32-bit compiler. Visual C++ 2.0 or higher, Borland C++ and the
mingw32 gcc compiler are all appropriate, as is cygwin. Do 
<strong>NOT</strong> use an ancient 16-bit DOS executable compiler, please.
<blockquote>
<h4>What Operating System Does Your WEB SERVER Run?</h4>
Remember, the computer on your desk is usually NOT your web server.
Compiling a Windows console executable will not give you a CGI program that
can be installed on a Linux-based server. 
</blockquote>
Your web browser should inquire whether to save the file to disk
when you select one of the links below. Under Unix and compatible
operating systems, save it, then issue the following
commands to unpack it:
<pre>
gunzip cgic205.tar.gz
tar -xf cgic205.tar
</pre>
This should produce the subdirectory 'cgic205', which will contain
the complete cgic distribution for version 2.05, including a copy of this 
documentation in the file cgic.html.
<p>
Under Windows and compatible operating systems, save it,
open a console ("DOS") window, and issue the following commands to unpack it:
<pre>
unzip /d cgic205.zip
</pre>
Or use the unzip utility of your choice.
<p>
This command also produces the subdirectory 'cgic205', which will contain
the complete cgic distribution for version 2.0, including a copy of this 
documentation in the file cgic.html.
<p>
cgic is available via the web from www.boutell.com:
<ul>
<li><a href="http://www.boutell.com/cgic/cgic205.tar.gz">Obtain cgic: gzipped tar file</a>
<li><a href="http://www.boutell.com/cgic/cgic205.zip">Obtain cgic: .ZIP file</a>
</ul>
<h3><a name="build">Building cgic: a sample application</a></h3>
The sample application 'cgictest.c' is provided as part of the
cgic distribution. This CGI program displays an input form, 
accepts a submission, and then displays what was submitted.
In the process essentially all of cgic's features are tested.
<p>
On a Unix system, you can build cgictest simply by typing
'make cgictest.cgi'. cgic.c and cgictest.c will be compiled and linked
together to produce the cgictest application. Under non-Unix
operating systems, you will need to create and compile an appropriate
project containing the files cgic.c and cgictest.c. 
<p>
<strong>IMPORTANT:</strong> after compiling cgictest.cgi, you will
need to place it in a location on your server system which is
designated by your server administrator as an appropriate location
for CGI scripts. Some servers are configured to recognize any
file ending in .cgi as a CGI program when it is found in any
subdirectory of the server's web space, but this is not always
the case! The right locations for CGI
programs vary greatly from one server to another. Resolving
this issue is between you, your web server administrator,
and your web server documentation. Before submitting a bug
report for cgic, make certain that the CGI example programs
which came with your server <em>do</em> work for you. Otherwise
it is very likely that you have a server configuration problem.
<p>
Once you have moved cgictest.cgi (or cgictest.exe, under Windows)
to an appropriate cgi directory,
use the web browser of your choice to access the URL at which
you have installed it 
(for instance, <code>www.mysite.com/cgi-bin/cgictest.cgi</code>).
Fill out the various fields in any manner you wish, then
select the SUBMIT button.
<p>
If all goes well, cgictest.cgi will respond with a page which
indicates the various settings you submitted. If not,
please reread the section above regarding the correct location in
which to install your CGI program on your web server.
<h3><a name="nocompile">What to do if it won't compile</a></h3>
<ul>
<li><strong>Are you using Visual C++ or Borland C++? Did you forget to add
cgic.c to your project?</strong>
<li><strong>Make sure you are using an ANSI C or C++ compiler.</strong>
(All of the Windows compilers are ANSI C compliant.)
</ul>
If none of the above proves effective, please see the
section regarding <a href="#support">support</a>.
<h3><a name="howto">How to write a cgic application</a></h3>
<em>Note: </em> All cgic applications must be linked to the cgic.c module
itself. How to do this depends on your operating system; under Unix,
just use the provided Makefile as an example.
<p>
Since all CGI applications must perform certain initial
tasks, such as parsing form data and examining
environment variables, the cgic library provides its
own main() function. When you write applications that
use cgic, you will begin your own programs by writing
a cgiMain() function, which cgic will invoke when
the initial cgi work has been successfully completed. Your
program must also be sure to #include the file cgic.h.
<p>
<strong>Important:</strong> if you write your own main()
function, your program will not link properly. Your own
code should begin with cgiMain(). The library
provides main() for you. (Those who prefer different behavior
can easily modify cgic.c.)
<p>
Consider the cgiMain function of cgictest.c:
<p>
<PRE>
int cgiMain() {
#ifdef DEBUG
  LoadEnvironment();
#endif /* DEBUG */
  /* Load a previously saved CGI scenario if that button
    has been pressed. */
  if (cgiFormSubmitClicked("loadenvironment") == cgiFormSuccess) {
    LoadEnvironment();
  }
  /* Set any new cookie requested. Must be done *before*
    outputting the content type. */
  CookieSet();
  /* Send the content type, letting the browser know this is HTML */
  cgiHeaderContentType("text/html");
  /* Top of the page */
  fprintf(cgiOut, "&lt;HTML&gt;&lt;HEAD&gt;\n");
  fprintf(cgiOut, "&lt;TITLE&gt;cgic test&lt;/TITLE&gt;&lt;/HEAD&gt;\n");
  fprintf(cgiOut, "&lt;BODY&gt;&lt;H1&gt;cgic test&lt;/H1&gt;\n");
  /* If a submit button has already been clicked, act on the 
    submission of the form. */
  if ((cgiFormSubmitClicked("testcgic") == cgiFormSuccess) ||
    cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess)
  {
    HandleSubmit();
    fprintf(cgiOut, "&lt;hr&gt;\n");
  }
  /* Now show the form */
  ShowForm();
  /* Finish up the page */
  fprintf(cgiOut, "&lt;/BODY&gt;&lt;/HTML&gt;\n");
  return 0;
}
</PRE>
Note the DEBUG #ifdef. If DEBUG is defined at compile time, either by
inserting the line "#define DEBUG 1" into the program or by setting
it in the Makefile or other development environment, then the
LoadEnvironment function is invoked. This function calls 
<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> 
to restore a captured CGI environment for debugging purposes. See
also the discussion of the <a href="#debug">capture</a> program, which is
provided for use in CGI debugging. Because this is a test program,
the <a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a> function is
also called to check for the use of a button that requests the reloading
of a saved CGI environment. A completed CGI program typically would
never allow the end user to make that decision.
<h4>Setting Cookies</h4>
Next, one of the cgiHeader functions should be called.
This particular program demonstrates many features, including
the setting of cookies. If the programmer wishes to set a cookie,
the cookie-setting function must be called
first, before other headers are output. This is done by the
CookieSet() function of cgictest.c:
<pre>
void CookieSet()
{
  char cname[1024];
  char cvalue[1024];
  /* Must set cookies BEFORE calling 
    cgiHeaderContentType */
  cgiFormString("cname", cname, sizeof(cname));  
  cgiFormString("cvalue", cvalue, sizeof(cvalue));  
  if (strlen(cname)) {
    /* Cookie lives for one day (or until 
      browser chooses to get rid of it, which 
      may be immediately), and applies only to 
      this script on this site. */  
    cgiHeaderCookieSetString(cname, cvalue,
      86400, cgiScriptName, cgiServerName);
  }
}
</pre>
Since this is a test program, the <a href="#cgiFormString">cgiFormString</a> 
function is used to fetch the name and value from the form previously filled
in by the user. Normally, cookie names and values are chosen to meet the
needs of the programmer and provide a means of identifying the same
user again later.
<p>
The <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
function sets the cookie by requesting that the web browser store it.
<strong>There is never any guarantee that this will happen!</strong>
Many browsers reject cookies completely; others do not necessarily keep
them as long as requested or return them with their values intact.
Always code defensively when using cookies.
<p>
The cname and cvalue parameters are of course the namd and value for
the cookie. The third argument is the time, in seconds, that the
cookie should "live" on the browser side before it expires; in this
case it has been set to 86,400 seconds, which is exactly one day. 
<strong>The browser may or may not respect this setting, as with everything
else about cookies.</strong>
<p>
The fourth argument identifies the "path" within the web site for which
the cookie is considered valid. A cookie that should be sent back
for every access to the site should be set with a path of <code>/</code>.
In this case the cookie is relevant only to the CGI program itself, so
<code><a href="#cgiScriptName">cgiScriptName</a></code> (the URL of the CGI program, not including the
domain name) is sent. Similarly, a cookie can be considered relevant
to a single web site or to an entire domain, such as 
<code>www.boutell.com</code> or the entire <code>.boutell.com</code>
domain. In this case, the current site on which the program is running
is the only relevant site, so <code><a href="#cgiServerName">cgiServerName</a></code> is used
as the domain.
<h4>Outputting the Content Type Header</h4>
Next, <a href="#cgiHeaderContentType">cgiHeaderContentType()</a> is 
called to indicate the MIME type of the document being output, in this case 
"text/html" (a normal HTML document). A few other common MIME types are
"image/gif", "image/jpeg" and "audio/wav". 
<p>
Note that <a href="#cgiHeaderStatus">cgiHeaderStatus()</a> or 
<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> could have
been invoked instead to output an error code or redirect the
request to a different URL. Only one of the cgiHeader functions
should be called in a single execution of the program.
<p>
<strong>Important:</strong> one of the cgiHeader functions,
usually <a href="#cgiHeaderContentType">cgiHeaderContentType()</a>, 
<em>must</em> be invoked before outputting any other
response to the user. Otherwise, the result will not be a valid
document and the browser's behavior will be unpredictable.
You may, of course, output your own ContentType and other
header information to <a href="#cgiOut">cgiOut</a> if you prefer. The cgiHeader functions
are provided as a convenience.
<h4>Handling Form Submissions</h4>
Like many CGI programs, cgictest makes decisions about the way it
should behave based on whether various submit buttons have been clicked.
When either the testcgic or saveenvironment button is present, cgictest
invokes the HandleSubmit function, which invokes additional functions to
handle various parts of the form:
<pre>
void HandleSubmit()
{
  Name();
  Address();
  Hungry();
  Temperature();
  Frogs();
  Color();
  Flavors();
  NonExButtons();
  RadioButtons();
  File();
  Entries();
  Cookies();
  /* The saveenvironment button, in addition to submitting 
    the form, also saves the resulting CGI scenario to 
    disk for later replay with the 'load saved environment' 
    button. */
  if (cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess) {
    SaveEnvironment();
  }
}
</pre>
<h4>Handling Text Input</h4>
The Name() function of cgictest is shown below, in its simplest
possible form:
<PRE>
void Name() {
        char name[81];