EZTwainX - Uploading with control built-in methods

See also: getting started, methods, deployment, uploading

This page explains how to upload images in an EZTwainX control to a web server, using built-in methods of the EZTwainX control.

Uploading this way is only suitable for synchronous uploads, where the server requires no or minimal authentication, and there are no proxies between client workstation and server.

Methods
UploadToURL (added 1.46)
UploadSeparatelyToURL (added 1.47)
UploadExtraField (added 1.48)
UploadShowProgress (added 1.55)
UploadAddCookie (added 1.57)
UploadAddHeader (added 1.64.02)

Properties
UploadResponse (added 1.46)

History
Release 1.46b1 - EZTwainX can emulate the submission via HTTP-POST of a multipart form (per RFC 1867) containing a file.
Release 1.47 added multiple-file upload with UploadSeparatelyToURL
Release 1.48 added the ability to specify the name and value of additional fields in the imaginary form being submitted
Release 1.49 added support for secure encrypted uploads using SSL and HTTPS.

Upload Theory & Practice
RFC 1867 is the upload format and HTTP-POST is the protocol commonly used by a browser when the user submits a form containing a control of type input=file. In other words, EZTwainX emulates a browser submitting a form like this:

<form name="form1" method="post" action="upload.php" enctype="multipart/form-data">
File to upload:
<input type="file" name="file"><br>
<input type="submit" name="Submit" value="Submit">
</form>

which looks like this:

File to upload:

Suppose the form above appears (as it does) on the page www.dosadi.com/eztx/upload.htm
If the user selects a file c:\temp\userform1.jpg in the form above and clicks the submit button, a block of data which includes the name and contents of the file c:\temp\userform1.jpg, is formatted and posted to http://www.dosadi.com/eztx/upload.php.

This operation can be emulated by EZTwainX with the following call:

eztwainx.UploadToURL("http://www.dosadi.com/eztx/upload.php", "userform1.jpg", "file")

The first parameter is the full URL of the script on the server that will receive and handle the upload. The second is the 'filename' to tell the server, and the third is the field-name. In a <FORM>, the fieldname is the name assigned to the file-select control.

Note that the extension on the filename determines the format of the uploaded file: .jpg generates a JPEG-compressed file, .pdf generates a PDF, and so on.

Important: EZTwainX does not create or upload an actual on-disk file called userform1.jpg - it uploads the current image or images held in the control, and pretends to the server that they come from a file or files on disk. The named files need not exist on the PC, if they exist they are not accessed, and if they do not exist they are not created. However, with some file formats invisible temporary files are created in the Windows temp folder.

After UploadToURL returns, the property UploadResponse contains the text sent back by the server in response to the upload. The server script determines this response. With manually-submitted forms, the response is generally a web page, or a redirect to a page reporting the result of the upload.

Example Server-side Scripts
Used to receive and dispose of uploaded files:
PHP Upload Script

Additional Fields
Often there is additional data that needs to be sent to the server along with the file. You have the option of attaching this information to the URL and parsing it in your server-side script, but the traditional method is to add controls to the form: Their values are then automatically included in the HTTP-POST data, and these additional items are generally easy to access in the server script. Consider this form:

<form name="form1" method="post" action="upload.php" enctype="multipart/form-data">
Vendor ID: <input type="text" name="vendor"><br>
File to upload:
<input type="file" name="file"><br>
<input type="submit" name="Submit" value="Submit">
</form>

Vendor ID:
File to upload:

To emulate this form being submitted, with our usual filename of userform1.jpg and the Vendor ID set to "Metallic Metals, Inc.", you would use code like this:

eztwainx.UploadExtraField("vendor", "Metallic Metals, Inc.")
eztwainx.UploadToURL("http://www.dosadi.com/eztx/upload.php", "userform1.jpg", "file")

Note that the call to UploadExtraField precedes the actual upload. There is a limit in EZTwainX 1.49 of 32 extra fields - contact Dosadi Supportsend e-mail if this limit is a problem for you.