PostFile Method  
 

Post the contents of the specified file to a script executed on the server.

Syntax

object.PostFile( LocalFile, [Resource], [FieldName], [Options] )

Parameters

LocalFile
A string that specifies the file on the local system that will be transferred to the server. The file pathing and name conventions must be that of the local host.
Resource
A string that specifies the resource that the data will be posted to on the server. Typically this is the name of an executable script. This is an optional argument; if it is omitted, the value of the Resource property will be used. It is also permissible to specify a complete URL and the file will be uploaded to that location.
FieldName
An optional string argument that specifies the form field name that the script expects. If this argument is omitted or is an empty string, a default field name of "File1" is used. This is an optional argument; if it is omitted, the value of the Resource property will be used. It is also permissible to specify a complete URL and the file will be downloaded from that location.
Options
An optional numeric value which specifies one or more options. This argument is reserved for future use and the application should either omit this argument, or specify a value of zero.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

Remarks

The PostFile method posts the contents of a file to a script that is executed on the server. 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 OnProgress event will fire periodically, enabling the application to update any user interface objects such as a progress bar.

This 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 LocalFile argument should be set to the name of the local file that will be posted to the server. The Resource argument should be the name of the script, in this case "/cgi-bin/upload.cgi". The FieldName argument should be specified as the string "datafile" to match the name of the field used by the form.

Note that the PostFile 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.

See Also

Resource Property, URL Property, GetFile Method, PutFile Method, PutMultipleFiles Method, OnProgress Event