The HttpPostFile function is similar to the
HttpPutFile function in that it can be used to upload the
contents of a local file to a server. However, instead of using the
PUT command, the POST command is used to send the file data to a
script that is executed on the server. This method has the
advantage of not requiring any special configuration settings on
the server, however it does require that the script be able to
process multipart/form-data as defined in RFC 2388.
To support uploading files from a form on a webpage, the FILE
input type is used along with the action that specifies the script
that will accept the file data and process it. For example, the
HTML code could look like this:
<form action="/cgi-bin/upload.cgi" method="post" enctype="multipart/form-data">
<input type="file" name="datafile" size="20">
<input type="submit">
</form>
In this example, the script /cgi-bin/upload.cgi is responsible
for processing the file data that is posted by the client, and the
form field name "datafile" is used. The user can select a file, and
when the Submit button is clicked, the file data is posted to the
script. To simulate this using the HttpPostFile function,
the lpszFileName parameter should be set to the name of the
local file that will be posted to the server. The
lpszResource parameter should be the name of the script, in
this case "/cgi-bin/upload.cgi". The lpszFieldName parameter
should be specified as the string "datafile" to match the name of
the field used by the form.
Note that the HttpPostFile function always submits the
file contents as multipart/form-data with the content type set to
application/octet-stream. The script that accepts the posted data
must be able to parse the multipart header block and correctly
process 8-bit data. If the script assumes that the data will be
posted using a specific encoding type such as base64 then the file
data may not be accepted or may be corrupted by the script.
This function will cause the current thread to block until the
file transfer completes, a timeout occurs or the transfer is
canceled. During the transfer, the HTTP_EVENT_PROGRESS event will
be periodically fired, enabling the application to update any user
interface controls. Event notification must be enabled, either by
calling HttpEnableEvents, or by registering a callback
function using the HttpRegisterEvent function.
To determine the current status of a file transfer while it is
in progress, use the HttpGetTransferStatus function.