Tutorial: Upload to Capture Handler

# Automatic scanned document upload

For scanned documents automatic upload is triggered after scan completes. All scanned images that was'n discarded during scan are combined into multipage tiff file on the local scanning service side, downloaded by the browser and then sent to the WebCaptureRequestHandler.

Preffered way to handle scanned images

Automatic upload allows quickly setup small scanning application without writing additional code for upload and images storage infrastructure. This works well for small scans, but breaks on big documents or high-resolution images, because of memory allocation issues - such scans produces quite big multipage file and usually 32bit browser or 32bit Web Scanning Service can't handle such allocations.

Preferred way to handling uploaded images is to configure scanning options deliverables settings to save each scanned image to encrypted local file in a desired format and discard image itself right in the onImageAcquired handler. After that, images data could be requested and uploaded to the server asynchronously while scanner will be unblocked right after scan.

Overriding Automatic Upload

Application is able to override or disable automatic file upload and optionally reuse existing upload code to handle individual single-page images.

Upload handler is retrieved using public API method which returns upload handler and getting called before each new scan request.

Atalasoft.Controls.Capture.UploadToCaptureServer.getUploadCallback

The default upload callback itself have is available using following API

Atalasoft.Controls.Capture.UploadToCaptureServer.uploadToServer

To disable automatic upload application could override upload handler factory to return null instead of actual upload handler.

Atalasoft.Controls.Capture.UploadToCaptureServer.getUploadCallback = function() { return null; };

Upload Options

The following are the supported properties of the uploadOptions object that can be included in the parameters to Atalasoft.Controls.Capture.WebScanning.initialize.

Keep in mind that an upload is submitted to the server as a POST of a MIME message, per RFC2046 "Multipurpose Internet Mail Extensions." The uploaded file is included as a form-data part with name="file".

formData object

Default value: null

Each 'own' property of the formData object is inserted in uploads as a form-data part, with its name and value. On the server, if you override the HandleUpload method, each property of the formData object will be available in the context.Request.Form dictionary. Numbers are converted to strings, strings are sent unquoted. Objects and arrays are sent (as strings) in JSON format. Unicode characters are handled correctly in both names and values.
```
      Atalasoft.Controls.Capture.UploadToCaptureServer.initialize({
          uploadOptions: {
            formData: {
              application: 'Doc-U-droid 9000',
              operator: '',
              pages: [1, 3, 7]
          }
        }
      });
```
On the server those properties are available as
```
  string app = context.Request.Form["application"];
  string oper = context.Request.Form["operator"];
  string pages = context.Request.Form["pages"];
```
extraParts array of strings

Default value: undefined This optional parameter is a list of additional parts to be inserted in the multipart body of each upload. Each string must conform to the rules in RFC2046 for a body-part. This option is retrieved from the uploadOptions object at the beginning of each upload, so its contents at that moment are included in the subsequent upload.

Note The order of strings in the array is not necessarily preserved in the upload.

  Atalasoft.Controls.Capture.UploadToCaptureServer.initialize({
       uploadOptions: {
             // an upload initiated now will include the 'application' field
             // above, in the multipart MIME message sent to the server.
             extraParts: [
                 'Content-Disposition: form-data; name="application"\n'+
                 '\n'+
                 'Doc-U-droid 9000'
             ]
        }
   });