cgic.html

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

for with a particular input field name. This works both for
<SELECT> tags with the MULTIPLE attribute and for 
groups of checkboxes with the same name. 
<P>
The first argument to <a href="#cgiFormStringMultiple">
cgiFormStringMultiple()</a> is the name of the input field or
group of input fields in question. The second argument should
be the address of a pointer to a pointer to a string, which
isn't as bad as it sounds. Consider the following simple call
of the function:
<PRE>
/* An array of strings; each C string is an array of characters */
char **responses; 

<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);
</PRE>
<em>"How do I know how many responses there are?"</em>
<p>
After the call, the last entry in the string array will be
a null pointer. Thus the simple loop:
<PRE>
int i = 0;
while (responses[i]) {
  /* Do something with the string responses[i] */
  i++;
}
</PRE>
can be used to walk through the array until the last
entry is encountered.
<p>
<strong>Important:</strong> the 
<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a> function
returns a pointer to <strong>allocated memory</strong>. Your code
should not modify the strings in the responses array or the responses
array itself; if modification is needed, the strings should be
copied. When your code is done examining the responses array,
you <strong>MUST</strong> call <a href="#cgiStringArrayFree">
cgiStringArrayFree()</a> with the array as an argument to free the memory 
associated with the array. Otherwise, the memory will not be available 
again until the program exists. <strong>Don't</strong> just call the 
free() function; if you do, the individual strings will not be freed.
<h4>Accessing Uploaded Files</h4>
CGIC provides functions to access files that have been uploaded
as part of a form submission. <strong>IMPORTANT: you MUST</strong> set
the <code>enctype</code> attribute of your <code>form</code> tag
to <code>multipart/form-data</code> for this feature to work! For an
example, see the <a href="#ShowForm">ShowForm</a> function of 
cgictest.c, examined below.
<p>
The <code>File</code> function of cgictest.c takes care of 
receiving uploaded files:
<pre>
void File()
{
  cgiFilePtr file;
  char name[1024];
  char contentType[1024];
  char buffer[1024];
  int size;
  int got;
  if (cgiFormFileName("file", name, sizeof(name)) != 
    cgiFormSuccess) 
  {
    printf("&lt;p&gt;No file was uploaded.&lt;p&gt;\n");
    return;
  } 
        fprintf(cgiOut, "The filename submitted was: ");
        cgiHtmlEscape(name);
        fprintf(cgiOut, "&lt;p&gt;\n");
        cgiFormFileSize("file", &size);
        fprintf(cgiOut, "The file size was: %d bytes&lt;p&gt;\n", size);
        cgiFormFileContentType("file", contentType, sizeof(contentType));
        fprintf(cgiOut, "The alleged content type of the file was: ");
        cgiHtmlEscape(contentType);
        fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Of course, this is only the claim the browser "
    "made when uploading the file. Much like the filename, "
    "it cannot be trusted.&lt;p&gt;\n");
  fprintf(cgiOut, "The file's contents are shown here:&lt;p&gt;\n");
  if (cgiFormFileOpen("file", &file) != cgiFormSuccess) {
    fprintf(cgiOut, "Could not open the file.&lt;p&gt;\n");
    return;
  }
  fprintf(cgiOut, "&lt;pre&gt;\n");
  while (cgiFormFileRead(file, buffer, sizeof(buffer), &got) ==
    cgiFormSuccess)
  {
    cgiHtmlEscapeData(buffer, got);
  }
  fprintf(cgiOut, "&lt;/pre&gt;\n");
  cgiFormFileClose(file);
}
</pre>
First, the File function checks to determine the filename that was
submitted by the user. <strong>VERY IMPORTANT: this filename may or
may not bear any relation to the real name of the file on the user's
computer, may be deliberately manipulated with malicious intent,</strong>
and should not be used for <strong>any</strong> purpose unless you have
determined that its content is safe for your intended use and will not,
at the very least, overwrite another file of importance to you, especially if
you intend to use it as a file name on the server side. The cgic library
itself does not use this file name for temporary storage.
<p>
If the <a href="#cgiFormFileName">cgiFormFileName</a> function does
not succeed, no file was uploaded.
<p>
Next, the <a href="#cgiFormFileSize">cgiFormFileSize</a> function is called
to determine the size of the uploaded file, in bytes.
<p>
The File function then proceeds to query the content type of the uploaded
file.  Files uploaded by the user have their own content type information, 
which may be useful in determining whether the file is an image, HTML document,
word processing document, or other type of file. However,
<strong>as with the filename and any other claim made by the browser,
this information should not be blindly trusted.</strong> The browser
may upload a file with the name <code>picture.jpg</code> and the
content type <code>image/jpeg</code>, but this does not guarantee that the
actual file will contain a valid JPEG image suitable for display.
<p>
The content type submitted by the browser can be queried using the
<a href="#cgiFormFileContentType">cgiFormFileContentType</a> function.
<p>
Of course, CGIC also provides access to the actual uploded file. 
First, the programmer calls <a href="#cgiFormFileOpen">cgiFormFileOpen</a>,
passing the address of a <code>cgiFilePtr</code> object. If this function
succeeds, the <code>cgiFilePtr</code> object becomes valid, and can be
used in subsequent calls to <a href="#cgiFormFileRead">cgiFormFileRead</a>.
Notice that the number of bytes read may be less than the number requested,
in particular on the last successful call before cgiFormFileRead begins
to return <code>cgiFormEOF</code>. When cgiFormFileRead no longer returns 
cgiFormSuccess, 
the programmer calls <a href="#cgiFormClose">cgiFormFileClose</a> to
release the <code>cgiFilePtr</code> object.
<p>
The uploaded file data may contain anything, including binary data,
null characters, and so on. The example program uses the 
<a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a> function to output the
data with any special characters that have meaning in HTML escaped.
Most programs will save the uploaded information to a server-side file or
database.
<h4>Fetching All Form Entries</h4>
From time to time, the programmer may not know the names of all
form fields in advance. In such situations it is convenient to
use the <a href="#cgiFormEntries">cgiFormEntries</a> function.
The Entries function of cgictest.c demonstrates the use of
cgiFormEntries:
<pre>
void Entries()
{
        char **array, **arrayStep;
        fprintf(cgiOut, "List of All Submitted Form Field Names:&lt;p&gt;\n");
        if (cgiFormEntries(&array) != cgiFormSuccess) {
                return;
        }
        arrayStep = array;
        fprintf(cgiOut, "&lt;ul&gt;\n");
        while (*arrayStep) {
                fprintf(cgiOut, "&lt;li&gt;");
                cgiHtmlEscape(*arrayStep);
                fprintf(cgiOut, "\n");
                arrayStep++;
        }
        fprintf(cgiOut, "&lt;/ul&gt;\n");
        cgiStringArrayFree(array);
}
</pre>
The cgiFormEntries function retrieves an array of form field names.
This array consists of pointers to strings, with a final null pointer
to mark the end of the list. The above code illustrates one way of
looping through the returned strings. Note the final call to
<a href="#cgiStringArrayFree">cgiStringArrayFree</a>, which is
essential in order to return the memory used to store the strings
and the string array.
<h4>Retrieving Cookies</h4>
The Cookies function of cgictest.c displays a list of all cookies
submitted by the browser with the current form submission, along
with their values:
<pre>
void Cookies()
{
  char **array, **arrayStep;
  char cname[1024], cvalue[1024];
  fprintf(cgiOut, "Cookies Submitted On This Call, With Values "
    "(Many Browsers NEVER Submit Cookies):&lt;p&gt;\n");
  if (cgiCookies(&array) != cgiFormSuccess) {
    return;
  }
  arrayStep = array;
  fprintf(cgiOut, "&lt;table border=1&gt;\n");
  fprintf(cgiOut, "&lt;tr&gt;&lt;th&gt;Cookie&lt;th&gt;Value&lt;/tr&gt;\n");
  while (*arrayStep) {
    char value[1024];
    fprintf(cgiOut, "&lt;tr&gt;");
    fprintf(cgiOut, "&lt;td&gt;");
    cgiHtmlEscape(*arrayStep);
    fprintf(cgiOut, "&lt;td&gt;");
    cgiCookieString(*arrayStep, value, sizeof(value));
    cgiHtmlEscape(value);
    fprintf(cgiOut, "\n");
    arrayStep++;
  }
  fprintf(cgiOut, "&lt;/table&gt;\n");
  cgiFormString("cname", cname, sizeof(cname));  
  cgiFormString("cvalue", cvalue, sizeof(cvalue));  
  if (strlen(cname)) {
    fprintf(cgiOut, "New Cookie Set On This Call:&lt;p&gt;\n");
    fprintf(cgiOut, "Name: ");  
    cgiHtmlEscape(cname);
    fprintf(cgiOut, "Value: ");  
    cgiHtmlEscape(cvalue);
    fprintf(cgiOut, "&lt;p&gt;\n");
    fprintf(cgiOut, "If your browser accepts cookies "
      "(many do not), this new cookie should appear "
      "in the above list the next time the form is "
      "submitted.&lt;p&gt;\n"); 
  }
  cgiStringArrayFree(array);
}
</pre>
<strong>VERY IMPORTANT: YOUR BROWSER MIGHT NOT SUBMIT COOKIES,
EVER, REGARDLESS OF WHAT VALUES YOU ENTER INTO THE TEST FORM.</strong>
Many, many browsers are configured not to accept or send cookies;
others are configured to send them as little as possible to meet the
bare minimum requirements for entry into popular sites. Users will often
refuse your cookies; make sure your code still works in that situation!
<p>
The above code uses the <a href="#cgiCookies">cgiCookies</a> function
to retrieve a list of all currently set cookies as a null-terminated
array of strings. The <a href="#cgiCookieString">cgiCookieString</a>
function is then used to fetch the value associated with each cookie;
this function works much like <a href="#cgiFormString">cgiFormString</a>,
discussed earlier. Note that a cookie set as a part of the current
form submission process does not appear on this list immediately, as
it has not yet been sent back by the browser. It should appear on
future submissions, provided that the browser chooses to accept
and resend the cookie at all.
<h4>Displaying a Form That Submits to the Current Program</h4>
CGI programmers often need to display HTML pages as part of the output
of CGI programs; these HTML pages often contain forms which should submit
fields back to the same program they came from. Provided that your
web server is well-configured, this can be done conveniently using
the cgiScriptName environment variable, as shown below. Here is the
source code of the ShowForm function of cgictest.c:
<pre>
void ShowForm()
{
  fprintf(cgiOut, "&lt;!-- 2.0: multipart/form-data is required 
    "for file uploads. --&gt;");
  fprintf(cgiOut, "&lt;form method=\"POST\" "
    "enctype=\"multipart/form-data\" ");
  fprintf(cgiOut, "  action=\"");
  cgiValueEscape(cgiScriptName);
  fprintf(cgiOut, "\"&gt;\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Text Field containing Plaintext\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "&lt;input type=\"text\" name=\"name\"&gt;Your Name\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Multiple-Line Text Field\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "&lt;textarea NAME=\"address\" ROWS=4 COLS=40&gt;\n");
  fprintf(cgiOut, "Default contents go here. \n");
  fprintf(cgiOut, "&lt;/textarea&gt;\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Checkbox\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"hungry\" checked&gt;Hungry\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Text Field containing a Numeric Value\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "&lt;input type=\"text\" name=\"temperature\" value=\"98.6\"&gt;\n");
  fprintf(cgiOut, "Blood Temperature (80.0-120.0)\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Text Field containing an Integer Value\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "&lt;input type=\"text\" name=\"frogs\" value=\"1\"&gt;\n");
  fprintf(cgiOut, "Frogs Eaten\n");
  fprintf(cgiOut, "&lt;p&gt;\n");
  fprintf(cgiOut, "Single-SELECT\n");
  fprintf(cgiOut, "&lt;br&gt;\n");