The PostFile method is similar to the PutFile method
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 PostFile method, 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 PostFile method 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 method 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 EnableEvents, or by registering a callback function
using the RegisterEvent method.
To determine the current status of a file transfer while it is in
progress, use the GetTransferStatus method.