cgic.html

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

  fprintf(cgiOut, "<select name=\"colors\">\n");
  fprintf(cgiOut, "<option value=\"Red\">Red\n");
  fprintf(cgiOut, "<option value=\"Green\">Green\n");
  fprintf(cgiOut, "<option value=\"Blue\">Blue\n");
  fprintf(cgiOut, "</select>\n");
  fprintf(cgiOut, "<br>\n");
  fprintf(cgiOut, "Multiple-SELECT\n");
  fprintf(cgiOut, "<br>\n");
  fprintf(cgiOut, "<select name=\"flavors\" multiple>\n");
  fprintf(cgiOut, "<option value=\"pistachio\">Pistachio\n");
  fprintf(cgiOut, "<option value=\"walnut\">Walnut\n");
  fprintf(cgiOut, "<option value=\"creme\">Creme\n");
  fprintf(cgiOut, "</select>\n");
  fprintf(cgiOut, "<p>Exclusive Radio Button Group: Age of "
    "Truck in Years\n");
  fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
    "value=\"1\">1\n");
  fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
    "value=\"2\">2\n");
  fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
    "value=\"3\" checked>3\n");
  fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
    "value=\"4\">4\n");
  fprintf(cgiOut, "<p>Nonexclusive Checkbox Group: "
    "Voting for Zero through Four Candidates\n");
  fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
    "value=\"A\">A\n");
  fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
    "value=\"B\">B\n");
  fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
    "value=\"C\">C\n");
  fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
    "value=\"D\">D\n");
  fprintf(cgiOut, "<p>File Upload:\n");
  fprintf(cgiOut, "<input type=\"file\" name=\"file\" "
    "value=\"\"> (Select A Local File)\n");
  fprintf(cgiOut, "<p>\n");
  fprintf(cgiOut, "<p>Set a Cookie<p>\n");
  fprintf(cgiOut, "<input name=\"cname\" "
    "value=\"\"> Cookie Name\n");
  fprintf(cgiOut, "<input name=\"cvalue\" "
    "value=\"\"> Cookie Value<p>\n");
  fprintf(cgiOut, "<input type=\"submit\" "
    "name=\"testcgic\" value=\"Submit Request\">\n");
  fprintf(cgiOut, "<input type=\"reset\" "
    "value=\"Reset Request\">\n");
  fprintf(cgiOut, "<p>Save the CGI Environment<p>\n");
  fprintf(cgiOut, "Pressing this button will submit the form, then "
    "save the CGI environment so that it can be replayed later "
    "by calling cgiReadEnvironment (in a debugger, for "
    "instance).<p>\n");
  fprintf(cgiOut, "<input type=\"submit\" name=\"saveenvironment\" "
    "value=\"Save Environment\">\n");
  fprintf(cgiOut, "</form>\n");
}
</pre>
Note the use of <code>enctype="multipart/form-data"</code> in the
<code>FORM</code> tag. This is absolutely required if the form
will contain file upload fields, as in the above example. Most
browsers will not even attempt file uploads without the
presence of this attribute.
<h4>Examining CGI environment variables</h4>
The CGI standard specifies a number of environment variables
which are set by the server. However, servers are somewhat
unpredictable as to whether these variables will be null or
point to empty strings when an environment variable is not set.
Also, in order to allow the programmer to restore saved
CGI environments, the cgic library needs have a way of insulating
the programmer from the actual environment variables.
<p>
Instead of calling getenv() to determine the value of a
variable such as HTTP_USER_AGENT (the browser software being used),
always use the
<a href="#variables">cgic copies of the environment variables</a>,
which are always valid C strings (they are never null, although
they may point to an empty string). For instance, the cgic
variable containing the name of the browser software is
<a href="#cgiUserAgent">cgiUserAgent</a>. The referring URL appears
in the variable <a href="#cgiReferrer">cgiReferrer</a>.
<h3><a name="images">How can I generate images from my cgic application?</a></h3>
cgic can be used in conjunction with the
<a href="http://www.boutell.com/gd/">gd graphics library</a>, which
can produce GIF images on the fly.
<p>
The following short sample program hints at the possibilities:
<pre>
#include "cgic.h"
#include "gd.h"

char *colors[] = {
  "red", "green", "blue"
};

#define colorsTotal 3

int cgiMain() {
  int colorChosen;
  gdImagePtr im;
  int r, g, b;
  /* Use gd to create an image */
  im = gdImageCreate(64, 64);
  r = gdImageColorAllocate(im, 255, 0, 0);  
  g = gdImageColorAllocate(im, 0, 255, 0);  
  b = gdImageColorAllocate(im, 0, 0, 255);  
  /* Now use cgic to find out what color the user requested */
  <a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("color", 3, &amp;colorChosen, 0);  
  /* Now fill with the desired color */
  switch(colorChosen) {
    case 0:
    gdImageFill(im, 32, 32, r);
    break;
    case 1:
    gdImageFill(im, 32, 32, g);
    break;
    case 2:
    gdImageFill(im, 32, 32, b);
    break;
  }  
  /* Now output the image. Note the content type! */
  cgiHeaderContentType("image/gif");
  /* Send the image to cgiOut */
  gdImageGif(im, cgiOut);
  /* Free the gd image */
  gdImageDestroy(im);
  return 0;
}
</pre>
Note that this program would need to be linked with both cgic.o
and libgd.a. Often programs of this type respond to one
cgiPathInfo value or set of form fields by returning an HTML page 
with an inline image reference that, in turn, generates a GIF image.
<h3><a name="debug">Debugging CGI applications: using capture</a></h3>
Debugging CGI applications can be a painful task. Since CGI applications
run in a special environment created by the web server, it is difficult
to execute them in a debugger. However, the cgic library provides a way 
of capturing "live" CGI environments to a file, and also provides a way
to reload saved environments. 
<p>
The provided program 'capture.c' can be used to capture CGI
environments. Just change the first line of the cgiMain() function
of capture.c to save the CGI environment to a filename appropriate
on your system and type 'make capture'. Then place capture in your
cgi directory and set the form action or other link you want to test
to point to it. When the form submission or other link takes place,
capture will write the CGI environment active at that time to
the filename you specified in the source. The
<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> function can then 
be invoked on the same filename at the beginning of the cgiMain() function 
of the application you want to test in order to restore the captured 
environment.  You can then execute your program in the debugger of your choice,
and it should perform exactly as it would have performed had
it been launched by the actual web server, including file uploads,
cookies and all other phenomena within the purview of cgic.
<p>
<strong>Important:</strong> Make sure you specify the full path, as the
current working directory of a CGI script may not be what you
think it is!
<p>
<strong>Even More Important:</strong> If you call getenv() yourself
in your code, instead of using the provided <a href="#variables">
cgic copies of the CGI environment variables</a>, you will
<em>not</em> get the values you expect when running with
a saved CGI environment. Always use the cgic variables instead
of calling getenv().
<h3><a name="functions">cgic function reference</a></h3>
<dl>
<br><dt><strong><a name="cgiFormString">cgiFormResultType cgiFormString(
  char *name, char *result, int max)</a>
</strong><br><dd>cgiFormString attempts to retrieve the string sent for the
  specified input field. The text will be copied into
  the buffer specified by result, up to but not
  exceeding max-1 bytes; a terminating null is then
  added to complete the string. Regardless of the newline
  format submitted by the browser, cgiFormString always
  encodes each newline as a single line feed (ascii decimal 10); as
  a result the final string may be slightly shorter than indicated
  by a call to <a href="#cgiFormStringSpaceNeeded">
  cgiFormStringSpaceNeeded</a> but will never be longer.
  cgiFormString returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was 
  successfully retrieved, 
  <a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
  retrieved but was truncated to fit the buffer,
  cgiFormEmpty if the string was 
  retrieved but was empty, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no 
  such input field was submitted. In the last case, 
  an empty string is copied to result. 
<br><br><dt><strong><a name="cgiFormStringNoNewlines">
cgiFormResultType cgiFormStringNoNewlines(
  char *name, char *result, int max)</a>
</strong><br><dd>
cgiFormStringNoNewlines() is exactly equivalent to <a href="#cgiFormString">
  cgiFormString()</a>, except
  that any carriage returns or line feeds that occur in the input
  will be stripped out. The use of this function is recommended
  for single-line text input fields, as some browsers will submit
  carriage returns and line feeds when they should not. 
<br><br><dt><strong><a name="cgiFormStringSpaceNeeded">
cgiFormResultType cgiFormStringSpaceNeeded(
  char *name, int *length)</a>
</strong><br><dd>
cgiFormStringSpaceNeeded() is used to determine the length of the input text 
  buffer needed to receive the contents of the specified input field. 
  This is useful if the programmer wishes to allocate sufficient memory 
  for input of arbitrary length. The actual length of the string 
  retrieved by a subsequent call to cgiFormString() may be slightly shorter
  but will never be longer than *result. On success, cgiFormStringSpaceNeeded() 
  sets the value pointed to by length to the number of bytes of data, 
  including the terminating null, and returns <a href="#cgiFormSuccess">cgiFormSuccess</a>. If no 
  value was submitted for the specified field, cgiFormStringSpaceNeeded sets 
  the value pointed to by length to 1 and returns <a href="#cgiFormNotFound">cgiFormNotFound</a>. 1 is
  set to ensure space for an empty string (a single null
  character) if cgiFormString is called despite the return value.

<br><br><dt><strong><a name="cgiFormStringMultiple">cgiFormResultType cgiFormStringMultiple(
  char *name, char ***ptrToStringArray)</a>
</strong><br><dd>cgiFormStringMultiple is useful in the unusual case in which several
  input elements in the form have the same name and, for whatever
  reason, the programmer does not wish to use the checkbox, radio 
  button and selection menu functions provided below. This is
  occasionally needed if the programmer cannot know 
  in advance what values might appear in a multiple-selection list
  or group of checkboxes on a form. The value pointed to
  by result will be set to a pointer to an array of strings; the last
  entry in the array will be a null pointer.  This array is allocated 
  by the CGI library. Important: when done working with the array,
  you must call cgiStringArrayFree() with the array pointer as the 
  argument.  cgiFormStringMultiple() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if at least
  one occurrence of the name is found, <a href="#cgiFormNotFound">cgiFormNotFound</a>
  if no occurrences are found, or cgiFormMemory if not enough
  memory is available to allocate the array to be returned.
  In all cases except the last, ptrToStringArray is set to point to a 
  valid array of strings, with the last element in the array being a 
  null pointer; in the out-of-memory case ptrToStringArray is set to 
  a null pointer.

<br><br><dt><strong><a name="cgiFormEntries">cgiFormResultType cgiFormEntries(
  char ***ptrToStringArray)</a>
</strong><br><dd>cgiFormEntries is useful when the programmer cannot know the names
  of all relevant form fields in advance. The value pointed to
  by result will be set to a pointer to an array of strings; the last
  entry in the array will be a null pointer.  This array is allocated 
  by the CGI library. Important: when done working with the array,
  you must call cgiStringArrayFree() with the array pointer as the 
  argument. cgiFormEntries() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> except in the event of an out of memory error.
  On success, ptrToStringArray is set to point to a 
  valid array of strings, with the last element in the array being a 
  null pointer; in the out-of-memory case ptrToStringArray is set to 
  a null pointer, and 
  <a href="#cgiFormOutOfMemory">cgiFormOutOfMemory</a> is returned.

<br><br><dt><strong><a name="cgiStringArrayFree">void cgiStringArrayFree(char **stringArray)
</a>
</strong><br><dd>
cgiStringArrayFree() is used to free the memory associated with
  a string array created by 
  <a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>,
  <a href="#cgiFormEntries">cgiFormEntries()</a>, or
  <a href="#cgiFormCookies">cgiFormCookies()</a>.
<br><br><dt><strong><a name="cgiFormInteger">cgiFormResultType cgiFormInteger(
  char *name, int *result, int defaultV)</a>
</strong><br><dd>cgiFormInteger() attempts to retrieve the integer sent for the
  specified input field. The value pointed to by result
  will be set to the value submitted. cgiFormInteger() returns 
  cgiFormSuccess if the value was successfully retrieved,
  cgiFormEmpty if the value submitted is an empty string,
  cgiFormBadType if the value submitted is not an integer,
  and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted. 
  In the last three cases, the value pointed to by result
  is set to the specified default.
<br><br><dt><strong><a name="cgiFormIntegerBounded">
cgiFormResultType cgiFormIntegerBounded(
  char *name, int *result, int min, int max, int defaultV)</a>
</strong><br><dd>cgiFormIntegerBounded() attempts to retrieve the integer sent for the
  specified input field, and constrains the result to be within
  the specified bounds. The value pointed to by result
  will be set to the value submitted. cgiFormIntegerBounded() returns 
  cgiFormSuccess if the value was