The upload_cgi application uses the GetEnvironmentVariable function
to read the environment variables from the Web server. GetEnvironmentVariable
takes three parameters: a string that contains the name of the environment
variable name, a buffer that contains the value of the environment variable, and
the size of the buffer.
The upload_cgi application calls the GetStdHandle function to get a handle
to the Standard In or Standard Out functions. GetStdHandle takes one parameter
that specifies the type of handle to be returned. A parameter value of
STD_INPUT_HANDLE causes the function to return a handle for Standard In, and a
parameter value of STD_OUTPUT_HANDLE causes the function to return a value
for Standard Out.
The Win32 API's ReadFile and WriteFile functions are similar, and each
takes five parameters. The first parameter is a handle to the file. To use
Standard In or Standard Out, this handle must be the one that GetStdHandle
returns. The second parameter is a buffer that contains the data for the read or
write operation. The third parameter is the number of bytes to read or write. In
the fourth parameter, the function returns the number of bytes actually read or
written. Finally, the fifth parameter designates whether overlapped I/O is to be
used. The upload_cgi application doesn't use overlapped I/O, so the
program sets this parameter to null.
The upload_cgi program starts after the Web Server receives the posted
data. Unlike most VB programs that begin by displaying a form (or window), the
non-graphical upload_cgi program begins by executing the Main subroutine, which
Listing 2 presents.
At callout A in Listing 2, you can see that the first subroutine Main calls
is the InitCGIVariables subroutine. InitCGIVariables simply calls the
GetCGIenvVar subroutine to retrieve each environment variable that the
Web server sends. Inside GetCGIenvVar is the Win32 API GetEnvironmentVariable
function. This function returns information about the browser, the server, and
the client's IP address, as well as other session information.
At B in Listing 2, the upload_cgi application calls the SendHeader
function. The SendHeader function begins building the HTML results form to be
sent back to the user when the file upload has completed.
At C in Listing 2, you can see where the upload_cgi program calls the
GetStandardInData subroutine, which reads from Standard In, using the Win32 API
ReadFile function. GetStandardInData, shown in Listing 3, reads the
data file that the user's browser sends.
GetStandardInData first calls the Win32 API GetStdHandle function to get a
handle for Standard In. Next, the subroutine uses a Do loop to read the data.
Within the loop, the VB String function makes sure that the gsBuff variable's
buffer is large enough to hold the data read from Standard In. Then,
GetStandardInData calls the ReadFile function using the handle that GetStdHandle
returned. The subroutine then reads the data stream from Standard In into a
buffer. GetStandardInData compares the string's size to the CGI_Content_Length
environment variable to determine when it has received all the information from
Standard In.
When GetStandardInData finishes, the Main subroutine resumes; at D in
Listing 2, Main parses the data that the browser posted. The browser sends files
in multipart format, and Main looks at the CGI_Content_Type environment variable
to determine the multipart boundary.
The example in Screen 2 shows what the CGI_Content_Type and CGI_Content_
Length environment variables might look like. When surrounded with the MIME
boundaries, the upload file looks like the example in Figure 1.
Because the file is encoded with the traditional MIME headers and
footers, handling the string the Web server receives can be a little messy. The
form the browser submits also sends the filename, including the full path of the
file on the client machine. All the VB program needs to do is strip the path
from the filename and write out the contents of the file in binary mode using
the correct filename.
At E in Listing 2, you can see where the upload_cgi program checks for the
target output directory and then writes the file to the Web server in binary
mode. The file is now available to any applications that need it. (On a security
note, don't place the uploaded files in a CGI directory or a public HTML
directory without first assessing the security risk.) After the upload has
completed, the Main subroutine sends a successful completion message to the
browser, with all the environment variables the subroutine used.
What Goes Up Must Come Down
You can underestimate the task of downloading a file on the Web because all
you have to do is make the file available in a public directory on a Web server,
and anyone with a browser can download the file. But the task isn't always that
easy. The Web server earmarks many file types for special MIME handling, even if
you simply want to download a file and save it on disk. Also, you may not want
to store your files on a public directory on a Web server. Even if you use
authentication, you may not want to use the Web server's access control list
(ACL) to decide whether a user has access to download a particular file.
Instead, you might want to use a smart Web application--an application that
determines access rights based on a set of events, such as whether the user has
filled out a questionnaire or entered valid credit card information. You can
easily handle HTTP downloads by using a CGI routine to send a file to a Web
browser. The upload_cgi program includes an example CGI download routine: the
DownloadFile subroutine shown in Listing 4.
Register
