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.