×
MENU
Table of contents

Output

Different ways to export data from the DWT buffer.

Upload

The most common usage of DWT is to scan documents and upload them to the server via HTTP and FTP . The library has a number of APIs to make this happen. Read on to learn more.

HTTP with Built-in APIs

For HTTP uploading, Dynamsoft recommends the method HTTPUpload() . Check out the following code snippet

/**
 * Upload the images specified by their indices in the specified file type.
 * @param indices Specify the images
 * @param type Specify the file type
 */
function upload(indices, type) {
    var protocol = Dynamsoft.Lib.detect.ssl ? "https://" : "http://",
        port = window.location.port === "" ? 80 : window.location.port,
        actionPage = "/upload.aspx";
    // path to the server-side script
    var url = protocol + window.location.hostname + ":" + port + actionPage;
    var fileName = "SampleFile" + getExtension(type);
    if (DWObject) {
        DWObject.HTTPUpload(
            url,
            indices,
            type,
            Dynamsoft.EnumDWT_UploadDataFormat.Binary,
            fileName,
            function() {
                console.log('Success');
            },
            function(errCode, errString, responseStr) {
                console.log(errString);
            }
        );
    }
}
/**
 * Return the extension string of the specified image type.
 * @param type The image type (number).
 */
function getExtension(type) {
    switch (type) {
        case 0:
            return ".bmp";
        case 1:
            return ".jpg";
        case 2:
        case 8:
            return ".tif";
        case 3:
            return ".png";
        case 4:
        case 7:
            return ".pdf";
        default:
            return ".unknown";
    }
}

Questions

Q: How is the upload done

A: DWT does the uploading in a few steps

  1. Grab the image(s) specified by indices ;
    • Encode the image(s) in the specified type which results in a binary file;
    • [Optional] Convert the file into a base64 string;
    • Create an HTTP Form and perform an asynchronous HTTP (Ajax) request to send the form to the specified url ;
    • Wait for the confirmation from the server.

The server-side script specified by url is very important, check out Server-side Scripting for more information.

Q: Is SSL supported

A: Yes, as shown in the following line, you just need to make sure the correct protocol is used

var protocol = Dynamsoft.Lib.detect.ssl ? "https://" : "http://"
Q: What file types are supported

A: As shown in the above function getExtension() , DWT supports BMP , JPG , TIF , PNG and PDF .

Q: Can I upload multiple images as one file

A: Yes, the file types TIF and PDF support multi-page. Make sure you use these two types when trying to upload multiple images as one file.

Q: Can I upload multiple images as separate files in one go

A: By design, the method HTTPUpload() only contains one file. But as it essentially sends an HTTP form to the server, you can attach multiple files in that form using the methods ConvertToBlob() and SetHTTPFormField() .

Check out the following snippet on how it is done. NOTE that the method HTTPUpload() only has 3 parameters as it doesn’t need to specify a file anymore.

/**
 * Upload the images specified by their indices in the specified file type as separate files.
 * @param indices Specify the images
 * @param type Specify the file type
 */
function uploadSeparateFiles(indices, type) {
    var protocol = Dynamsoft.Lib.detect.ssl ? "https://" : "http://",
        port = window.location.port === "" ? 80 : window.location.port,
        actionPage = "/upload.aspx";
    // path to the server-side script
    var url = protocol + window.location.hostname + ":" + port + actionPage;
    if (DWObject) {
        var done = 0,
            count = indices.length;
        var toBlob = function(index) {
            var fieldName = "SampleFile_" + index;
            var fileName = fieldName + getExtension(type);
            DWObject.ConvertToBlob(
                [index],
                type,
                function(result, _indices, type) {
                    DWObject.SetHTTPFormField(
                        fieldName,
                        result,
                        fileName
                    );
                    done++;
                    if (done === count) {
                        DWObject.HTTPUpload(
                            url,
                            function() {
                                console.log('Success');
                            },
                            function(errCode, errString, responseStr) {
                                console.log(errString);
                            }
                        );
                    } else {
                        toBlob(indices[done]);
                    }
                },
                function(errorCode, errorString) {
                    console.log(errorString);
                }
            );
        }
        toBlob(indices[done]);
    }
}
Q: Can I upload the file as a base64 string

A: Yes, the 4th parameter of the method HTTPUpload() is dataFormat and it has two allowed values which are Dynamsoft.EnumDWT_UploadDataFormat.Binary and Dynamsoft.EnumDWT_UploadDataFormat.Base64 . The code snippet uses the former but you can feel free to use the latter to upload the file as a base64 string.

Q: How to specify the images to upload

A: Use the 2nd parameter indices to specify the images by their indices. Note that even if you upload just one image, you still needs to supply an array with its index. For example: [0] .

Q: Can I change the header of the HTTP form

A: Yes, you can use the method SetHTTPHeader() to add or change the header(s). It’s recommended that you don’t change the default fields including, but not limited to, Accept , Connection , Cookie , etc.

Q: Can I change the fields of the HTTP form

A: Yes, you can use the method SetHTTPFormField() to add extra fields to the form. In a previous question, the method is used to add files to the form. But you can also use the method to add extra text information to the form as shown below

// Clear old fields before adding new ones
DWObject.ClearAllHTTPFormField();
DWObject.SetHTTPFormField("FileType", "Insurance Doc");
Q: Can I change the default field name of the file

A: Yes, you can use the API HttpFieldNameOfUploadedImage to change the default field name “RemoteFile”.

Q: Can I show my own upgrade progress bar

A: Yes, please check out customize the progress bar.

Q: How do I know whether the upload succeeded

A: Every HTTP upload method has two callbacks with signatures like this

onEmptyResponse: () => void,
onServerReturnedSomething: (
    errorCode: number,
    errorString: string,
    response: string) => void

The 1st callback onEmptyResponse is triggered when the server returns no response string. Generally, if errors occurred on the server, the server would return some information to indicate what went wrong. Therefore, if nothing is returned, you can treat it as a successful upload.

Of course, in your own server-side script to accept and process the HTTP Post request, you know whether the upload is successful and can make it more obvious by returning some custom information to indicate that. In this case, the 2nd callback onServerReturnedSomething will be triggered on purpose and you will need to read the argument response which contains what is returned by the server.

NOTE

When the callback onServerReturnedSomething is triggered, you will always get an errorCode and an errorString but you can choose to ignore them if it’s triggered on purpose.

DWT also provides an API called HTTPPostResponseString which contains response but can be read outside of the upload method.

Q: Can I limit the size of the uploaded file

A: Yes, you can set the limit (in bytes) using the API MaxUploadImageSize . After that, DWT will refuse to perform an upload should the size of the file exceeds the limit.

NOTE

The API MaxUploadImageSize doesn’t limit other fields of the upload. Therefore, if you append a very big string as a field or perhaps a few big Blobs as files, they will not be limited.

Q: Can I upload a big file in segments

A: Yes, when the file to upload is quite large, you can use the method SetUploadSegment() to configure a segmented upload operation

// For a file bigger than 1 MB, upload it in 500-KB segments 
DWObject.SetUploadSegment(1, 500);

For segmented upload, the server-side script is quite different. Check out how it is done in C# here.

Q: What are all the APIs DWT provides for HTTP upload

A: Apart from the recommended HTTPUpload() method and those already mentioned above, DWT provides 8 more methods and a few other properties for making an HTTP upload. They are listed below

HTTP with the File Uploader

The File Uploader is an independent component that is dedicated to file uploading. It can be used seamlessly with DWT .

How is upload done using the File Uploader

  1. DWT will prepare the file to upload with the method GenerateURLForUploadData()
    • Create a File Uploader instance with the method Init()
    • Create an upload job with CreateJob()
      • Define the target URL ( ServerUrl )
      • Define the upload content ( SourceValue )
      • [Optional] Define callback functions ( OnUploadTransferPercentage , OnRunSuccess , OnRunFailure )
    • Run the job
    • Wait for the confirmation from the server

Check out how to use the Uploader in the following code snippets

<div id="processbar" style="width:0%;"></div>

// Create a File Uploader instance
Dynamsoft.FileUploader.Init('', function(obj) {
        dsUploadManager = obj;
    },
    function(errCode, errStr) {
        console.log(errStr);
    }
);

function useUploader(indices, type) {
    if (DWObject) {
        DWObject.GenerateURLForUploadData(indices, type, function(url, indices, iImageType) {
            // Create a Job
            var job = dsUploadManager.CreateJob();
            // Configure the Job
            job.ServerUrl = "https://YOUR-SITE:PORT/PATH/TO/SCRIPT.aspx";
            var fileName = "SampleFile" + getExtension(type);
            job.SourceValue.Add(url, fileName);
            job.OnUploadTransferPercentage = function(obj, percentage) {
                var processbar = document.getElementById("processbar");
                processbar.style.width = a + "%";
            };
            job.OnRunSuccess = function() {};
            job.OnRunFailure = function() {};
            // Run the Job
            dsUploadManager.Run(job);
        }, function() {});
    }
}

Check out Server-side Scripting for more information on the target URL.

HTTP with existing upload logic

In some cases, you might already have an upload logic in your application and just want to upload the data in the DWT buffer with the same logic. The following code assumes the existing logic is pure AJAX which expects the FormData

function uploadThroughAJAX(indices, type) {
    DWObject.ConvertToBlob(
        indices,
        type,
        function(result, _indices, type) {
            var url = "https://YOUR-SITE:PORT/PATH/TO/SCRIPT.aspx";
            var fileName = "SampleFile" + getExtension(type);
            var formData = new FormData();
            formData.append('RemoteFile', result, fileName);
            makeRequest(url, formData, false);
        },
        function(errorCode, errorString) {
            console.log(errorString);
        }
    );
}

function makeRequest(url, formData, flg) {
    // Set up the request
    if (window.XMLHttpRequest) {
        xhr = new XMLHttpRequest();
    } else {
        if (window.ActiveXObject) {
            try {
                xhr = new ActiveXObject("MSXML2.XMLHTTP.3.0");
            } catch (ex) {
                alert(ex);
            }
        }
    }
    if (xhr) {
        if (flg) {
            // Open the connection
            xhr.open("GET", url, true);
            xhr.onreadystatechange = requestresult;
            xhr.setRequestHeader("If-Modified-Since", "0");
            xhr.send(null);
        } else {
            // Send the Data via POST
            xhr.open("POST", url, false);
            if (formData != null) {
                xhr.send(formData);
            } else {
                xhr.send(null);
            }
        }
    } else {
        alert("Sorry, but I couldn't create an XMLHttpRequest! ");
    }
}

function requestresult() {
    if (xhr.readyState == 4) {
        if (xhr.status == 200) {
            // File(s) uploaded
            var outMsg;
            if (xhr.responseXML && xhr.responseXML.documentElement) {
                outMsg = xhr.responseXML;
                alert(xhr.responseText);
            }
        }
    }
}

FTP

FTP is a lot simpler than HTTP. A simple example:

DWObject.FTPUserName = 'test';
DWObject.FTPPort = 21;
DWObject.FTPPassword = 'test';
DWObject.FTPUpload(
    '192.168.8.222', //The FTP Host
    0, // The index of the image
    'test.pdf', // The path & name of the file 
    OnFtpUploadSuccess, // Callback in case of success
    OnFtpUploadFailure // Callback in case of failure
);

DWT provides quite a few APIs for FTP upload too

Save

DWT offers several methods to save your images to an absolute file path. Depending on what your exact needs are, you can choose from any of the following methods:

Show dialog to save

Supported on desktop.

You can set the IfShowFileDialog property to true , which will show the open/save file dialog whenever you save an image(s) within the DWT buffer

DWObject.IfShowFileDialog = true;
// The path is selected in the dialog, therefore we only need the file name
DWObject.SaveAllAsPDF("Sample.pdf",
    function() {
        console.log('Successful!');
    },
    function(errCode, errString) {
        console.log(errString);
    }
);

Save to an absolute path

Supported on desktop.

If you don’t want to show any dialog and you know for sure where you want the files saved, you can save with absolute paths while setting IfShowFileDialog to false .

When using an absolute path, you must make sure the current user has the proper permission to save to that path. Otherwise the save will fail.

DWObject.IfShowFileDialog = false;
DWObject.SaveAllAsPDF("D:\\Sample.pdf",
    function() {
        console.log('Successful!');
    },
    function(errCode, errString) {
        console.log(errString);
    }
);

Save as a download

Supported on WASM browsers.

In WASM browsers, DWT runs its entire operations within the browser. So saving locally triggers will instead download the file and IfShowFileDialog will have no effect.

// The following line only works on desktop but it 
// doesn't throw errors on WASM browsers either 
DWObject.IfShowFileDialog = false;
// The following line specifies an absolute path but 
// only the name 'Sample.pdf' is used in WASM browsers
DWObject.SaveAllAsPDF("D:\\Sample.pdf",
    function() {
        console.log('Successful!');
    },
    function(errCode, errString) {
        console.log(errString);
    }
);

Save multiple files to the same loation

If you want the user to choose a file path once and then save multiple images to that location, you can do so via the OnGetFilePath event.

DWObject.RegisterEvent("OnGetFilePath", (isSave, filesCount, index, directory, _fn) => {
    if (directory === "" && _fn === "") {
        console.log("User cancelled the operation.")
    } else {
        var path = directory + "\\" + _fn.substr(0, _fn.lastIndexOf("."));
        DWObject.IfShowFileDialog = false;
        for (var i = 1; i < DWObject.HowManyImagesInBuffer; i++) {
            DWObject.SaveAsJPEG(path + "-" + i.toString() + ".jpg", i,
                function() {
                    console.log('Successful!');
                },
                function(errCode, errString) {
                    console.log(errString);
                }
            );
        }
    }
});
DWObject.IfShowFileDialog = true;
DWObject.SaveAsJPEG("Sample.jpg", 0,
    function() {
        console.log('Successful!');
    },
    function(errCode, errString) {
        console.log(errString);
    }
);

Convert

In some cases, you want to process the data yourself and want to extract it from the DWT buffer. DWT offers two approaches.

Convert to a Blob

To do this, use the method ConvertToBlob() which has been mentioned several times above. The following is a simple example

DWObject.ConvertToBlob(
    [0, 1, 2],
    Dynamsoft.EnumDWT_ImageType.IT_PDF,
    function(result, indices, type) {
        console.log(result.size);
    },
    function(errorCode, errorString) {
        console.log(errorString);
    }
);

Convert to Base64

To do this, use the method ConvertToBase64() 

DWObject.ConvertToBase64(
    [0, 1, 2],
    Dynamsoft.EnumDWT_ImageType.IT_PDF,
    function(result, indices, type) {
        console.log(result.getData(0, result.getLength()));
    },
    function(errorCode, errorString) {
        console.log(errorString);
    }
);

Print

DWT supports printing with the method Print() .

Other Questions

Q: How to reduce the size of a resulting file

A: There are a few things that you can try to reduce the size of a resulting file

  • Scan in grayscale or black & white instead of RGB;
  • Convert the images to grayscale or black & white before the save or upload call. Read more here;
  • Scan in a lower resolution;
  • Convert the images to a lower resolution (DPI). Read more here;
  • [Optional] If the resulting file is in the JPEG format (.jpg) or is a TIF or PDF that is encoded by the JPEG standard, you can set JPEGQuality to a lower value.

Q: How can I customize a resulting TIFF file

A: There are a few ways

Q: Can I hide the progress bar

A: Yes, please see this page for more information.

Is this page helpful?

YesYes NoNo

In this article:

latest version

    • Latest Version
    • Version 16.1.1
    Change +
    © 2003–2020 Dynamsoft. All rights reserved.
    Privacy Statement / Site Map / Home / Purchase / Support