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
- 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 anerrorCode
and anerrorString
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
-
HTTPUploadThroughPutEx()
-
HTTPUploadThroughPost()
-
HTTPUploadThroughPostEx()
-
HTTPUploadAllThroughPostAsMultiPageTIFF()
-
HTTPUploadAllThroughPostAsPDF()
-
HTTPUploadThroughPostAsMultiPagePDF()
-
HTTPUploadThroughPostAsMultiPageTIFF()
-
HTTPUploadThroughPostDirectly()
-
HTTPPassword
-
HTTPUserName
-
HTTPPort
-
IfSSL
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
DWT
will prepare the file to upload with the methodGenerateURLForUploadData()
- 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
)
- Define the target URL (
- Run the job
- Wait for the confirmation from the server
- Create a File Uploader instance with the method
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
-
FTPUpload()
-
FTPUploadEx()
-
FTPUploadAllAsMultiPageTIFF()
-
FTPUploadAllAsPDF()
-
FTPUploadAsMultiPagePDF()
-
FTPUploadAsMultiPageTIFF()
-
FTPPassword
-
FTPPort
-
FTPUserName
-
IfPASVMode
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:
-
SaveAsBMP()
-
SaveAsJPEG()
-
SaveAsPDF()
-
SaveAsPNG()
-
SaveAsTIFF()
-
SaveSelectedImagesAsMultiPagePDF()
-
SaveSelectedImagesAsMultiPageTIFF()
-
SaveAllAsPDF()
-
SaveAllAsMultiPageTIFF()
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);
}
);
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
- Change its compression type with
TIFFCompressionType
; - Specify whether it is multi-page or single-page with
IfTiffMultiPage
; - Set TIFF tags with
ClearTiffCustomTag()
andSetTiffCustomTag()
;
Q: Can I hide the progress bar
A: Yes, please see this page for more information.