{WebTwainObject} Scan
The properties and methods on this page live in the namespace {WebTwainObject}. {WebTwainObject} denotes the
WebTwain
instance. Learn about how to create a web twain object.
1. The following APIs are compatible with TWAIN, ICA, SANE (Windows, macOS and Linux)
Methods
Properties
CurrentSourceName |
IfDisableSourceAfterAcquire |
IfDuplexEnabled |
IfFeederEnabled |
PageSize |
PixelType |
Resolution |
SourceCount |
Events
OnPostAllTransfers |
OnPostTransfer |
OnPostTransferAsync |
OnPreAllTransfers |
OnPreTransfer |
2. The following APIs are compatible with TWAIN and ICA
Methods
getCapabilities() |
setCapabilities() |
3. The following APIs are compatible with TWAIN (mostly Windows, but could also be macOS)
Methods
Properties
Events
OnSourceUIClose |
The Android Service Edition only supports a subset of the APIs available in the Desktop Service Edition. For the APIs that are compatible with both editions, the usage remains the same. To learn how to use the APIs, please refer to the documentation for the Desktop Service Edition.
Methods
SelectSourceAsync() |
CloseSourceAsync() |
GetDevicesAsync() |
SelectDeviceAsync() |
AcquireImageAsync() |
getCapabilities() |
setCapabilities() |
Events
OnPostTransferAsync |
AcquireImage
Start image acquisition.
Syntax
AcquireImage(
deviceConfiguration?: DeviceConfiguration,
successCallBack?: () => void,
failureCallBack?: (deviceConfiguration?: DeviceConfiguration, errorCode: number, errorString: string) => void
): void;
Parameters
deviceConfiguration
: Configuration for the acquisition. Please refer to DeviceConfiguration.
successCallback
: A callback function that is executed if the request succeeds.
failureCallback
: A callback function that is executed if the request fails.
errorCode
: The error code.errorString
: The error string.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
extendedImageInfoQueryLevel
is 0 by default which means the following information will be retrieved (if available):
Label | Value |
---|---|
TWEI_BARCODEX | 0x1200 |
TWEI_BARCODEY | 0x1201 |
TWEI_BARCODETEXT | 0x1202 |
TWEI_BARCODETYPE | 0x1203 |
TWEI_ENDORSEDTEXT | 0x1213 |
TWEI_BARCODECONFIDENCE | 0x121A |
TWEI_BARCODEROTATION | 0x121B |
TWEI_BARCODETEXTLENGTH | 0x121C |
TWEI_BOOKNAME | 0x1238 |
TWEI_CHAPTERNUMBER | 0x1239 |
TWEI_DOCUMENTNUMBER | 0x123A |
TWEI_PAGENUMBER | 0x123B |
TWEI_CAMERA | 0x123C |
TWEI_FRAMENUMBER | 0x123D |
TWEI_FRAME | 0x123E |
TWEI_PIXELFLAVOR | 0x123F |
TWEI_MAGDATA | 0x1243 |
TWEI_MAGTYPE | 0x1244 |
TWEI_PAGESIDE | 0x1245 |
If it’s set to 1, the following will also be retrieved (if available):
Label | Value |
---|---|
TWEI_DESHADETOP | 0x1204 |
TWEI_DESHADELEFT | 0x1205 |
TWEI_DESHADEHEIGHT | 0x1206 |
TWEI_DESHADEWIDTH | 0x1207 |
TWEI_DESHADESIZE | 0x1208 |
TWEI_SPECKLESREMOVED | 0x1209 |
TWEI_HORZLINEXCOORD | 0x120A |
TWEI_HORZLINEYCOORD | 0x120B |
TWEI_HORZLINELENGTH | 0x120C |
TWEI_HORZLINETHICKNESS | 0x120D |
TWEI_VERTLINEXCOORD | 0x120E |
TWEI_VERTLINEYCOORD | 0x120F |
TWEI_VERTLINELENGTH | 0x1210 |
TWEI_VERTLINETHICKNESS | 0x1211 |
TWEI_PATCHCODE | 0x1212 |
TWEI_FORMCONFIDENCE | 0x1214 |
TWEI_FORMTEMPLATEMATCH | 0x1215 |
TWEI_FORMTEMPLATEPAGEMATCH | 0x1216 |
TWEI_FORMHORZDOCOFFSET | 0x1217 |
TWEI_FORMVERTDOCOFFSET | 0x1218 |
TWEI_BARCODECOUNT | 0x1219 |
TWEI_DESHADECOUNT | 0x121D |
TWEI_DESHADEBLACKCOUNTOLD | 0x121E |
TWEI_DESHADEBLACKCOUNTNEW | 0x121F |
TWEI_DESHADEBLACKRLMIN | 0x1220 |
TWEI_DESHADEBLACKRLMAX | 0x1221 |
TWEI_DESHADEWHITECOUNTOLD | 0x1222 |
TWEI_DESHADEWHITECOUNTNEW | 0x1223 |
TWEI_DESHADEWHITERLMIN | 0x1224 |
TWEI_DESHADEWHITERLAVE | 0x1225 |
TWEI_DESHADEWHITERLMAX | 0x1226 |
TWEI_BLACKSPECKLESREMOVED | 0x1227 |
TWEI_WHITESPECKLESREMOVED | 0x1228 |
TWEI_HORZLINECOUNT | 0x1229 |
TWEI_VERTLINECOUNT | 0x122A |
TWEI_DESKEWSTATUS | 0x122B |
TWEI_SKEWORIGINALANGLE | 0x122C |
TWEI_SKEWFINALANGLE | 0x122D |
TWEI_SKEWCONFIDENCE | 0x122E |
TWEI_SKEWWINDOWX1 | 0x122F |
TWEI_SKEWWINDOWY1 | 0x1230 |
TWEI_SKEWWINDOWX2 | 0x1231 |
TWEI_SKEWWINDOWY2 | 0x1232 |
TWEI_SKEWWINDOWX3 | 0x1233 |
TWEI_SKEWWINDOWY3 | 0x1234 |
TWEI_SKEWWINDOWX4 | 0x1235 |
TWEI_SKEWWINDOWY4 | 0x1236 |
TWEI_ICCPROFILE | 0x1240 |
TWEI_LASTSEGMENT | 0x1241 |
TWEI_SEGMENTNUMBER | 0x1242 |
TWEI_FILESYSTEMSOURCE | 0x1246 |
TWEI_IMAGEMERGED | 0x1247 |
TWEI_MAGDATALENGTH | 0x1248 |
TWEI_PAPERCOUNT | 0x1249 |
TWEI_PRINTERTEXT | 0x124A |
If it’s set to 2, then besides what’s mentioned in the two tables above, the Dynamic Web TWAIN library will also try to query the scanner for its own custom extended image info.
Example
The example code shows 4 ways to use the API
AcquireImage()
var deviceConfiguration = {
IfShowUI: false,
PixelType: Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB,
Resolution: 300,
IfFeederEnabled: true,
IfDuplexEnabled: false,
IfDisableSourceAfterAcquire: true,
IfGetImageInfo: true,
IfGetExtImageInfo: true,
extendedImageInfoQueryLevel: 0,
};
function successCallback() {
console.log("successful");
}
function failureCallback(errorCode, errorString) {
alert(errorString);
}
function AcquireImage1() {
DWObject.SelectSource(function () {
DWObject.OpenSource();
DWObject.IfShowUI = false;
DWObject.PixelType = Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB;
DWObject.Resolution = 300;
DWObject.IfFeederEnabled = true;
DWObject.IfDuplexEnabled = false;
DWObject.IfDisableSourceAfterAcquire = true;
DWObject.AcquireImage();
}, failureCallback);
}
function AcquireImage2() {
DWObject.SelectSource(function () {
DWObject.OpenSource();
DWObject.AcquireImage(deviceConfiguration);
}, failureCallback);
}
function AcquireImage3() {
DWObject.SelectSource(function () {
DWObject.OpenSource();
DWObject.IfShowUI = false;
DWObject.PixelType = Dynamsoft.DWT.EnumDWT_PixelType.TWPT_RGB;
DWObject.Resolution = 300;
DWObject.IfFeederEnabled = true;
DWObject.IfDuplexEnabled = false;
DWObject.IfDisableSourceAfterAcquire = true;
DWObject.AcquireImage(successCallback, failureCallback);
}, failureCallback);
}
function AcquireImage4() {
DWObject.SelectSource(function () {
DWObject.OpenSource();
DWObject.AcquireImage(
deviceConfiguration,
successCallback,
failureCallback
);
}, failureCallback);
}
CloseSource
Close the data source (a TWAIN/ICA/SANE device which in most cases is a scanner) to free it to be used by other applications.
Syntax
CloseSource(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
// Close the scanner source in the success/failure callback after all images are acquired. In this case, the source can be freed and used by others.
DWObject.OpenSource();
DWObject.AcquireImage(successCallback,failureCallback);
function successCallback() {
console.log("successful");
DWObject.CloseSource();
}
function failureCallback(errorCode, errorString) {
alert(errorString);
DWObject.CloseSource();
}
CloseSourceAsync
Close the data source (a TWAIN/ICA/SANE device which in most cases is a scanner) to free it to be used by other applications.
Syntax
CloseSourceAsync(): Promise<boolean>;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v18.0+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ | v18.2+ |
DisableSource
Disable the data source (a TWAIN/ICA/SANE device which in most cases is a scanner) to stop the acquiring process. If the data source’s user interface is displayed, it will be closed.
Syntax
DisableSource(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
After DisableSource()
is called, the Source is still open and you can continue to acquire images by calling AcquireImage()
or EnableSource()
.
EnableSource
Enable the data source to start the acquiring process.
Syntax
EnableSource(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
The method is equivalent to AcquireImage()
without parameters.
EnableSourceUI
Display the TWAIN source’s built-in user interface.
Syntax
EnableSourceUI(
successCallBack: () => void,
failureCallBack: (errorCode: number, errorString: string) => void
): void;
Parameters
successCallback
: A callback function that is executed if the request succeeds.
failureCallback
: A callback function that is executed if the request fails.
errorCode
: The error code.errorString
: The error string.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
not supported | v16.0+ | v16.0+ | v16.0+ | v16.0+ |
Usage notes
This method enables the user to manipulate the settings for scanning but not start an actual scan. It only works if the source supports the capability CAP_ENABLEDSUIONLY
. User can call GetCustomDSDataEx() to save the settings in the callback successCallBack
and later call SetCustomDSDataEx() to apply the settings before starting a scan.
OpenSource
Load a data source to get it ready to acquire images.
Syntax
OpenSource(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
DWObject.GetSourceNames(); // for example ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']
DWObject.SelectSourceByIndex(0); // choose scanner with the name "PaperStream IP fi-7300NX Net"
DWObject.OpenSource();
DWObject.AcquireImage();
OpenSourceAsync
Load a data source to get it ready to acquire images.
Syntax
OpenSourceAsync(): Promise<boolean>;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v18.0+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ |
GetSourceNames
Return all available data sources (scanners, etc.) and optionally all detailed information about them.
Syntax
GetSourceNames(bIncludeDetails?: boolean): string[] | SourceDetails[];
Parameters
bIncludeDetails
: Whether to return more details about the data sources or just their names.
Arguments
SourceDetails
: Please refer to SourceDetails.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
not supported | v15.3+ | v15.3+ | v15.3+ | v15.3+ |
Example
DWObject.GetSourceNames(); // return a list of scanner sources such as ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']
GetSourceNamesAsync
Return all available data sources (scanners, etc.) and optionally all detailed information about them.
Syntax
GetSourceNamesAsync(bIncludeDetails: boolean): Promise<string[] | ISourceDetails[]>;
Parameters
bIncludeDetails
: Whether to return more details about the data sources or just their names.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v18.0+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ |
SelectSource
Bring up the Source Selection User Interface (UI) for the user to choose a data source.
Syntax
SelectSource(
successCallBack?: () => void,
failureCallBack?: (errorCode: number, errorString: string) => void
): boolean | string;
Parameters
successCallback
: A callback function that is executed if the request succeeds.
failureCallback
: A callback function that is executed if the request fails.
errorCode
: The error code.errorString
: The error string.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v14.0+ |
Usage notes
- It’s recommended to use this API asynchronously by pass arguments to the parameters
successCallback
andfailureCallback
. - On
Windows
andWindows
only, you can call this method with no arguments so that it runs synchronously and return a boolean value.
Example
DWObject.SelectSource(
function () {
DWObject.OpenSource();
DWObject.AcquireImage();
},
function (errorCode, errorString) {
console.log(errorString);
}
);
SelectSourceAsync
Bring up the Source Selection User Interface (UI) for the user to choose a data source.
Syntax
SelectSourceAsync(deviceType?: Dynamsoft.DWT.EnumDWT_DeviceType | number): Promise<number>;
Parameters
deviceType
: Specify the device type of scanners. Please refer to EnumDWT_DeviceType.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v16.1+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ | v18.2+ |
Example
DWObject.SelectSourceAsync()
.then(function (sourceIndex) {
console.log(sourceIndex);
return DWObject.AcquireImageAsync();
})
.catch(function (e) {
console.log(e);
});
SelectSourceByIndex
Select a data source by its index.
Syntax
SelectSourceByIndex(index: number): boolean;
Parameters
index
: The index of the data source.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
DWObject.GetSourceNames(); // for example ['PaperStream IP fi-7300NX Net', 'TWAIN2 FreeImage Software Scanner']
DWObject.SelectSourceByIndex(0); // choose scanner with the name "PaperStream IP fi-7300NX Net"
DWObject.OpenSource();
DWObject.AcquireImage();
SelectSourceByIndexAsync
Select a data source by its index.
Syntax
SelectSourceByIndexAsync(index: number): Promise<boolean>;
Parameters
index
: The index of the data source.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v16.1+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ |
Example
DWObject.SelectSourceByIndexAsync(0)
.then(() => {
return DWObject.OpenSourceAsync();
})
.then(() => {
return DWObject.AcquireImageAsync();
});
SetOpenSourceTimeout
Sets a timer which stops the data source opening process once it expires.
Syntax
SetOpenSourceTimeout(duration: number): boolean;
Parameters
duration
: Define the duration of the timer (in milliseconds).
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v11.0+ | v11.0+ | v11.0+ | v11.0+ | not supported |
Example
DWObject.SelectSource(function () {
DWObject.SetOpenSourceTimeout(3000); // stop the opening process if the source cannot be opened within 3000 ms.
DWObject.OpenSource();
DWObject.AcquireImage();
});
startScan
Start the acquisition by passing all settings at once.
Syntax
startScan(scanSetup: ScanSetup): Promise<IScanSetup>;
Parameters
scanSetup
: Configuration for the acquisition. Please refer to ScanSetup.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
not supported | v15.0+ | v15.1+ | v15.1+ | v15.1+ |
Sample
CancelAllPendingTransfers
Cancels all pending transfers.
Syntax
CancelAllPendingTransfers(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
This method is only valid in the events OnPreAllTransfers, OnPreTransfer and OnPostTransfer.
CloseSourceManager
Closes and unloads Data Source Manager.
Syntax
CloseSourceManager(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
DWObject.CloseSourceManager();
CloseSourceManagerAsync
Closes and unloads Data Source Manager.
Syntax
CloseSourceManagerAsync(): Promise<boolean>;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v18.0+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ |
CloseWorkingProcess
Closes the scanning process to release resources on the machine.
Syntax
CloseWorkingProcess(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v11.2+ | v11.2+ | v11.2+ | v11.2+ | v12.1+ |
Usage notes
In the HTML5 edition, Dynamic Web TWAIN uses a separate process to communicate with the scanners. When it’s not scanning, you can choose to close this process to release the resources (CPU, memory, etc.) used on the machine.
FeedPage
Ejects the current page and begins scanning the next page in the document feeder.
Syntax
FeedPage(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Use this method after OpenSource() is called and make sure IfFeederEnabled is true
.
GetCustomDSData
Get the custom data source data and saves the data in a specified file.
Syntax
GetCustomDSData(fileName: string): boolean;
Parameters
fileName
: The path of the file to save the data source data to.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v10.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Typically, the data source data file is set by the method SetCustomDSData().
Example
// Please note, the API only works for TWAIN driver.
DWObject.GetCustomDSData("C:\\Users\\UserName\\Desktop\\ProfileName");
GetCustomDSDataEx
Gets custom DS data and returns it in a base64 string.
Syntax
GetCustomDSDataEx(): string;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v10.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Typically, the data source data file is set by the method SetCustomDSDataEx().
Example
// Please note, the API only works for TWAIN driver.
DWObject.GetCustomDSDataEx(); // Return a base64 string
GetSourceNameItems
Get the name of a data source by its index in data source manager source list.
Syntax
GetSourceNameItems(index: number): string;
Parameters
index
: The index of the data source.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v7.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
DWObject.GetSourceNames(); // [scanner 1, scanner 2, scanner 3...]
DWObject.GetSourceNameItems(0); // return the name of scanner 1
OpenSourceManager
Load and open data source manager.
Syntax
OpenSourceManager(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
If application identification needs to be set, it should be set before this API.
Example
DWObject.OpenSourceManager();
OpenSourceManagerAsync
Load and open data source manager.
Syntax
OpenSourceManagerAsync(): Promise<boolean>;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v18.0+ | v16.1+ | v16.1+ | v16.1+ | v16.1+ |
Usage notes
If application identification needs to be set, it should be set before this API.
ResetImageLayout
Reset the image layout in the data source.
Syntax
ResetImageLayout(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
To set the image layout manually, you can use SetImageLayout()
RewindPage
If called while {IfFeederEnabled} property is true, the data source will return the current page to the input area and return the last page from the output area into the acquisition area.
Syntax
RewindPage(): boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Use this method after OpenSource() method and make sure IfFeederEnabled is true
.
SetCustomDSData
Sets custom data source data to be used for scanning, the data is stored in a file which can be regarded as a scanning profile.
Syntax
SetCustomDSData(fileName: string): boolean;
Parameters
fileName
: The path of the file.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v10.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Typically, the data source data file is created by the method GetCustomDSData().
Example
// Please note, the API only works for TWAIN driver.
DWObject.SetCustomDSData("C:\\Users\\UserName\\Desktop\\ProfileName");
SetCustomDSDataEx
Set custom data source data to be used for scanning, the input is a base64 string.
Syntax
SetCustomDSDataEx(dsDataString: string): boolean;
Parameters
dsDataString
: The string that contains custom data source data.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v10.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Typically the data source data string is created by the method GetCustomDSDataEx()
// Please note, the API only works for TWAIN driver.
DWObject.SetCustomDSData("the base64 string of your profile");
SetFileXferInfo
Set the file transfer information to be used in File Transfer mode.
Syntax
SetFileXferInfo(
fileName: string,
fileFormat: Dynamsoft.DWT.EnumDWT_FileFormat | number
): boolean;
Parameters
fileName
: The path to transfer the file to.
fileFormat
: The format of the file.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v17.0+ | not supported |
Usage notes
Make sure the format you set is supported by the data source.
Example argument for the parameter fileName
- “C:\webtwain.jpg”: The next scanned image will be compressed as a JPEG file named
webtwain
and transferred to “C:\”. - “C:\webtwain” + <> + “.jpg”: The scanned images will result in “C:\webtwain1.jpg”, “C:\webtwain2.jpg”, “C:\webtwain3.jpg”, etc.
- “C:\webtwain” + <%06d> + “.jpg”: The scanned images will result in “C:\webtwain000001.jpg”, “C:\webtwain000002.jpg”, “C:\webtwain000003.jpg”, etc.
Check out the available formats Dynamsoft.DWT.EnumDWT_FileFormat.
Example
DWObject.OpenSource();
DWObject.TransferMode = Dynamsoft.DWT.EnumDWT_TransferMode.TWSX_FILE;
if (DWObject.TransferMode === Dynamsoft.DWT.EnumDWT_TransferMode.TWSX_FILE) {
if (
DWObject.SetFileXferInfo(
"C:\\Temp\\WebTWAIN<%06d>.bmp",
Dynamsoft.DWT.EnumDWT_FileFormat.TWFF_BMP
)
) {
DWObject.IfShowUI = true;
DWObject.AcquireImage();
}
}
SetImageLayout
Set the left, top, right, and bottom sides of the image layout rectangle for the current data source. The image layout rectangle defines a frame of the data source’s scanning area to be acquired.
Syntax
SetImageLayout(
left: number,
top: number,
right: number,
bottom: number
): boolean;
Parameters
left
: Specify the rectangle (leftmost coordinate).
top
: Specify the rectangle (topmost coordinate).
right
: Specify the rectangle (rightmost coordinate).
bottom
: Specify the rectangle (bottommost coordinate).
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
The arguments set to the parameters left
, top
, right
, bottom
are based on the value of the Unit
property which is inches
by default.
This API is device-dependent. If a data source doesn’t support the customization of the scan area, this method might not work correctly.
Since there are several ways to negotiate the scan area, it becomes confusing when deciding what should take precedence.
The TWAIN Working Group has suggested the following behavior
- If the current frame is set by
SetImageLayout
. The same frame shall be what you get with the APIs CapGetFrameBottom(), CapGetFrameLeft(), CapGetFrameRight(), CapGetFrameTop() and the property PageSize shall returnTWSS_NONE
(0). - If the current frame is set from negotiating the capability
ICAP_FRAMES
with the method CapSetFrame(), the property PageSize shall returnTWSS_NONE
(0) and the image layout shall reflect the same frame with the properties ImageLayoutFrameBottom, ImageLayoutFrameLeft, ImageLayoutFrameRight and ImageLayoutFrameTop. - If the current fixed frame is set by the property PageSize, the same dimensions shall be reflected in the APIs CapGetFrameBottom(), CapGetFrameLeft(), CapGetFrameRight(), CapGetFrameTop() as well as ImageLayoutFrameBottom, ImageLayoutFrameLeft, ImageLayoutFrameRight and ImageLayoutFrameTop. Note, however, the orientation (in other words, whether it’s in the portrait mole or landscape mode) also plays a role in the order of the values.
Example
DWObject.SelectSource();
DWObject.OpenSource();
DWObject.IfShowUI = false;
DWObject.Unit = Dynamsoft.DWT.EnumDWT_UnitType.TWUN_PIXELS;
DWObject.SetImageLayout(50, 50, 100, 100);
DWObject.AcquireImage();
BitDepth
Return or set the pixel bit depth for the current value of PixelType
.
Syntax
BitDepth: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
By default, the bit depth is 1 for TWPT_BW
, 8 for TWPT_GRAY
and 24 for TWPT_RGB
.
IfAppendImage
Return or set whether newly acquired images are inserted or appended.
Syntax
IfAppendImage: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.1+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
The value of this property defaults to true
, which means that the newly acquired image will be appended to the last image in the buffer.
If it’s set to false
, the images will be inserted before the current image. The important thing to note is that, by design, the current image is always the last acquired one which means that the images acquired after setting IfAppendImage
to false
will be displayed / retained in the reverse order.
Here is an article to demonstrate how to insert new images to a specified index.
IfDisableSourceAfterAcquire
Return or set whether to close the built-in User Interface after all images have been acquired.
Syntax
IfDisableSourceAfterAcquire: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
This property only makes sense when IfShowUI
is set to true
.
Example
DWObject.OpenSource();
DWObject.IfDisableSourceAfterAcquire = true; // Close the scanner UI after images acquired.
DWObject.IfShowUI = true;
DWObject.AcquireImage(successCallback,failureCallback);
function successCallback() {
DWObject.CloseSource();
}
function failureCallback(errorCode, errorString) {
DWObject.CloseSource();
}
IfDuplexEnabled
Return or set whether to enable duplex scanning (in other words, whether to scan both sides of the paper).
Syntax
IfDuplexEnabled: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
Not all scanners support duplex scanning. To confirm, check the user manual of the device or check the value of Duplex
after OpenSource()
.
Example
DWObject.OpenSource();
if (DWObject.Duplex != 0) { // Note: DWObject.Duplex doesn't support Linux.
DWObject.IfDuplexEnabled = true;
}
DWObject.AcquireImage();
IfFeederEnabled
Return or set whether a data source’s Automatic Document Feeder (ADF) is enabled for scanning.
Syntax
IfFeederEnabled: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
If the property is set to true
, the data source will try acquiring images from the document feeder first. If the data source doesn’t have a document feeder, the flatbed will be used.
Example
DWObject.OpenSource();
DWObject.IfFeederEnabled = true;
DWObject.AcquireImage();
IfShowUI
Return or set whether the data source displays the user interface when scanning.
Syntax
IfShowUI: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
If the property is set to true
, the data source will display its user interface when AcquireImage()
is called. Otherwise, the UI will not be displayed and the scan will start immediately.
It’s recommended to use this API after OpenSource()
is called.
Example
DWObject.OpenSource();
DWObject.IfShowUI = true; // display the scanner UI before acquiring image
DWObject.AcquireImage();
ImageCaptureDriverType
Return or set the driver type which determines the type of sources to use.
Syntax
ImageCaptureDriverType: Dynamsoft.DWT.EnumDWT_Driver | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
not supported | v11.0+ | v11.0+ | v11.0+ | not supported |
Usage notes
Set this property right after the SDK is initialized or after calling CloseSourceManager()
and OpenSourceManager()
.
The allowed values for EnumDWT_Driver
are
Label | Value | Description |
---|---|---|
TWAIN | 0 | Use data sources that conforms to the TWAIN protocol (Default value on Windows) |
ICA | 3 | Use data sources that conforms to the Image Capture Architecture |
SANE | 3 | Use data sources that conforms to the SANE API (Default value on Linux) |
TWAIN_AND_ICA | 4 | Use both TWAIN and ICA data sources (Default value on MacOS) |
TWAIN_AND_TWAIN64 | 4 | Use both 32bit and 64bit TWAIN drivers |
TWAIN64 | 5 | Use 64bit TWAIN sources |
PageSize
Return or set the page size the data source uses to acquire images.
Syntax
PageSize: Dynamsoft.DWT.EnumDWT_CapSupportedSizes | number;
Parameters
PageSize
: Please refer to EnumDWT_CapSupportedSizes
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | not supported |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
PixelType
Return or set the pixel type used when acquiring images.
Syntax
PixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;
Parameters
PixelType
: Please refer to EnumDWT_PixelType
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
Resolution
Return or set the resolution used when acquiring images.
Syntax
Resolution: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v3.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
SourceCount
Returns how many data sources are available on the local system.
Syntax
readonly SourceCount: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
BlankImageThreshold
Retrun or set the dividing line between black and white.
Syntax
BlankImageThreshold: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v5.2+ | v5.2+ | v5.2+ | v5.2+ |
Usage notes
BlankImageThreshold
ranges from 0 to 255 and is 128 by default, it’s only effective when [ PixelType
] is set to TWPT_BW
. The bigger the value is, the more likely an image may be regarded as blank.
Brightness
Return or set the brightness to be used for scanning by the data source.
Syntax
Brightness: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
Typically, the value range is -1000 ~ 1000 where -1000 indicates the darkest and 1000 the brightest.
Contrast
Return or set Contrast to be used for scanning by the data source.
Syntax
Contrast: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | v12.1+ |
Usage notes
Set this property after OpenSource()
and before AcquireImage()
.
Typically, the value range is -1000 ~ 1000 where -1000 indicates the darkest and 1000 the brightest.
CurrentSourceName
Return the device name of current source.
Syntax
readonly CurrentSourceName: string;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
If no source is currently selected, this property returns “”.
DataSourceStatus
Return a value that indicates the data source status.
Syntax
DataSourceStatus: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Value | Description |
---|---|
0 | The data source is closed. |
1 | The data source is opened. |
2 | The data source is enabled. |
3 | The data source is acquiring images. |
DefaultSourceName
Return the name of the last used source.
Syntax
DefaultSourceName: string;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Duplex
Return whether the source supports duplex. If yes, it further returns the level of duplex the data source supports.
Syntax
readonly Duplex: Dynamsoft.DWT.EnumDWT_DUPLEX | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Label | Value | Description |
---|---|---|
TWDX_NONE | 0 | duplex is not supported |
TWDX_1PASSDUPLEX | 1 | 1-pass duplex |
TWDX_2PASSDUPLEX | 2 | 2-pass duplex |
1-pass means the paper gets scanned on both sides at the same time. 2-pass means the paper passes the light bar twice to get both sides scanned separately.
This property does not support Linux.
IfAutoBright
Return or set whether to enable the data source’s auto-brightness feature.
Syntax
IfAutoBright: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
IfAutoDiscardBlankpages
Return or set whether the data source (the scanner) discards blank images during scanning automatically.
Syntax
IfAutoDiscardBlankpages: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v7.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
The property works only if the device and its driver supports discarding blank pages. You can find whether your device supports this capbility from its user manual.
Alternatively, the Dynamic Web TWAIN library can also detect blank images after they are transferred.
IfAutoFeed
Return or set whether to enable the data source’s automatic document feeding process.
Syntax
IfAutoFeed: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v7.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
If set to true
, the data source will automatically feed the next page from the document feeder as soon as the previous page is scanned.
IfAutomaticBorderDetection
Return or set whether to enable the data source’s automatic border detection feature.
Syntax
IfAutomaticBorderDetection: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v7.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
The property works only if the device and its driver support detecting the border automatically. You can find whether your device supports this capbility from its user manual.
Once enabled, the data source (scanner) will automatically detect the borders of the document so that no extra margins are scanned.
IfAutomaticDeskew
Return or set whether to enable the data source’s automatic skew correction feature.
Syntax
IfAutomaticDeskew: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v7.0+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
The property works only if the device and its driver supports automatical deskewing. You can find whether your device supports this capbility from its user manual.
IfAutoScan
Return or set whether to enable the data source’s automatic document scanning process.
Syntax
IfAutoScan: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
This property is only valid when IfFeederEnabled is set to true
.
The fundamental assumption behind this property is that the device may be able to capture the number of images indicated by the property XferCount without waiting for the Application to request the image transfers. This is only possible if the device has internal buffers capable of caching the images it captures.
IfFeederLoaded
Return whether or not there are documents loaded in the data source’s feeder.
Syntax
readonly IfFeederLoaded: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
This property is only valid when IfFeederEnabled and IfPaperDetectable are true
.
IfPaperDetectable
Return whether the Source has a paper sensor that can detect pages on the ADF or Flatbed.
Syntax
readonly IfPaperDetectable: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Check this property after OpenSource() is called.
IfShowIndicator
Return or set whether the data source displays a progress indicator during acquisition and transfer.
Syntax
IfShowIndicator: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
This property works only when IfShowUI is set to false
.
The indicator will only be hidden if you set both IfShowUI and IfShowIndicator to false
.
IfUIControllable
Return whether the data source supports acquisitions with the UI (User Interface) disabled.
Syntax
readonly IfUIControllable: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Check this property after OpenSource() is called.
IfUseTwainDSM
Return or set whether the new TWAIN DSM (data source Manager) is used for acquisitions. The new TWAIN DSM is a DLL called ‘TWAINDSM.dll’ while the default or old DSM is called ‘twain_32.dll’.
Syntax
IfUseTwainDSM: boolean;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v6.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
This property should be set before any TWAIN related methods or properties are called or set.
ImageLayoutFrameBottom
Return the value of the bottom edge of the current image frame (in Unit).
Syntax
readonly ImageLayoutFrameBottom: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLayoutFrameLeft
Return the value of the left edge of the current image frame (in Unit).
Syntax
readonly ImageLayoutFrameLeft: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLayoutFrameNumber
Returns the frame number of the current image.
Syntax
readonly ImageLayoutFrameNumber: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
Usage Notes Usually a chronological index of the acquired frames, these frames are related to one another in some way. Usually, they were acquired from the same page. The source assigns these values. Initial value is 1. Reset when a new page is acquired.
ImageLayoutFrameNumber
property, along with other properties about the current image information, is valid only in the OnPreTransfer
and OnPostTransfer
events.
The frame information here is only about the current frame. To get the information about all the frames to be transferred in an acquire session, please use capability negotiation. The capability to be negotiated is ICAP_FRAMES (4372).
ImageLayoutFrameRight
Return the value of the right edge of the current image frame (in Unit).
Syntax
readonly ImageLayoutFrameRight: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLayoutFrameTop
Return the value of the top edge of the current image frame (in Unit).
Syntax
readonly ImageLayoutFrameTop: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLayoutDocumentNumber
Return the document number of the current image.
Syntax
readonly ImageLayoutDocumentNumber: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLayoutPageNumber
Return the page number of the current image.
Syntax
readonly ImageLayoutPageNumber: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageBitsPerPixel
Return the bit depth of the current image.
Syntax
readonly ImageBitsPerPixel: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageLength
Return the length of the current image.
Syntax
readonly ImageLength: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageWidth
Return the width of the current image.
Syntax
readonly ImageWidth: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageXResolution
Return the horizontal resolution of the current image.
Syntax
readonly ImageXResolution: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImageYResolution
Return the vertical resolution of the current image.
Syntax
readonly ImageYResolution: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
ImagePixelType
Return the pixel type of the current image.
Syntax
readonly ImagePixelType: Dynamsoft.DWT.EnumDWT_PixelType | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
all versions | all versions | all versions | all versions | all versions |
MagData
Return the data of the magnetic data if the data source supports magnetic data recognition.
Syntax
readonly MagData: string;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v8.0+ | v8.0+ | v8.0+ | v8.0+ | v8.0+ |
MagType
Return the type of the magnetic data if the data source supports magnetic data recognition.
Syntax
readonly MagType: Dynamsoft.DWT.EnumDWT_MagType | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v8.0+ | v8.0+ | v8.0+ | v8.0+ | v8.0+ |
Usage notes
The numbers returned by these APIs are based on the value of the Unit property which by default means “inches”.
These APIs are only valid in the callbacks for the events OnPreTransfer and OnPostTransfer.
MagData
and MagType
are device-dependent. Check the user manual of the device to see if magnetic data recognition is supported.
PendingXfers
Return the number of transfers the data source is ready to supply upon demand.
Syntax
readonly PendingXfers: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
This property is only valid in the event OnPostTransfer.
The data source returns -1 if it is not sure how many transfers are pending which normally occurs when the ADF (Automatic Document Feeder) is used.
PixelFlavor
Return or set the pixel flavor to be used for acquiring images.
Syntax
PixelFlavor: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | not supported |
Usage notes
Available values:
- 0: Chocolate. Zero pixel represents darkest shade
- 1: Vanilla. Zero pixel represents lightest shade.
TransferMode
Return or set the data source’s transfer mode.
Syntax
TransferMode: Dynamsoft.DWT.EnumDWT_TransferMode | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | not supported | v11.0+ | not supported |
Usage notes
Allowed values are
-
TWSX_NATIVE 0: The default mode. In this mode, the whole image is transfered in a single memory block. -
TWSX_FILE 1: In this mode, the image is transfered to a specified file on the disk directly. This mode is ideal when transferring large images that might encounter memory limitations with Native mode. Check out SetFileXferInfo for more information. -
TWSX_MEMORY 2: In this mode, the image is transferred in multiple memory blocks. It’s ideal for transferring very large images or a large number of images in a short time.
TWSX_NATIVE and TWSX_MEMORY are required by all TWAIN data sources while TWSX_FILE is not. Therefore, make sure the data source supports TWSX_FILE before you use it.
Unit
Return or set the unit of measure for all quantities. Note that this setting is only effective for TWAIN/ICA (hardware) related operations.
Syntax
Unit: Dynamsoft.DWT.EnumDWT_UnitType | number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | not supported |
Usage notes
Allowed values are
Label | Value | Description |
---|---|---|
TWUN_INCHES | 0 | inches(Default) |
TWUN_CENTIMETERS | 1 | centimeters |
TWUN_PICAS | 2 | picas |
TWUN_POINTS | 3 | points |
TWUN_TWIPS | 4 | twips |
TWUN_PIXELS | 5 | pixels |
TWUN_MILLIMETERS | 6 | millimeters |
XferCount
Return and set the number of images your application is willing to accept for each scan job.
Syntax
XferCount: number;
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | not supported | v12.1+ |
Usage notes
Allowed values are between -1 and 215 where -1 indicate multiple images.
OnPostAllTransfers
This event is triggered when all page(s) have been scanned and transferred.
Syntax
RegisterEvent("OnPostAllTransfers", function () {});
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
This event fires after all pages in the document feeder have been scanned and transferred. This is a good place to upload the images, detect barcodes, discard blank pages, etc.
Example
DWObject.RegisterEvent("OnPostAllTransfers", function () {
console.log("All images are transferred.");
});
OnPostTransfer
This event is triggered after each page has been scanned and transferred.
Syntax
RegisterEvent("OnPostTransfer", function () {});
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v1.0+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Example
DWObject.RegisterEvent("OnPostTransfer", function () {
console.log("An image has been scanned");
});
OnPostTransferAsync
This event is triggered after each page has been scanned and transferred. This is the asynchronous counterpart to the synchronous event {OnPostTransfer}.
Syntax
RegisterEvent("OnPostTransferAsync", function (outputInfo: OutputInfo) {});
Parameters
outputInfo
: Detailed information about the image that just got transferred. Please refer to OutputInfo.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
not supported | v15.0+ | v15.1+ | v15.1+ | v15.1+ | v18.2+ |
Example
DWObject.RegisterEvent("OnPostTransferAsync", function (outputInfo) {
console.log("The image ID is " + outputInfo.imageId);
});
OnPreAllTransfers
This event is triggered when all images are scanned and ready to be transferred.
Syntax
RegisterEvent("OnPreAllTransfers", function () {});
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
Multiple transfers may occur in two cases
- Multiple images are scanned through the ADF(Auto Document Feeder)
- Multiple frames are scanned on one single page
In such cases, the event OnPreTransfer
is triggered multiple times but OnPreAllTransfers
is triggerred only once.
In the callback function of this event, you can call CancelAllPendingTransfers()
to cancel all the transfers.
OnPreTransfer
This event is triggered when a page has been scanned and is ready to be transferred.
Syntax
RegisterEvent('OnPreTransfer',function(){...});
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v5.2+ | v10.0+ | v11.0+ | v11.0+ | v12.1+ |
Usage notes
In the callback function of this event, you can
- Check
PendingXFERs
for the number of pending transfers. - Check the information about the transferred image including
ImageLayoutDocumentNumber
,ImageLayoutFrameLeft
,ImageLayoutFrameTop
,ImageLayoutFrameRight
,ImageLayoutFrameBottom
,ImageLayoutPageNumber
,ImageLayoutFrameNumber
, etc. - Call
CancelAllPendingTransfers()
to cancel all the rest of the transfers.
OnSourceUIClose
This event is triggered when the user interface of the data source is closed manually by the user.
Syntax
RegisterEvent("OnSourceUIClose", function () {});
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) |
v8.0.1+ | v10.0+ | v11.0+ | not supported | not supported |
getCapabilities
Gets detailed information about all capabilities of the current data source.
Syntax
getCapabilities(
successCallback: (capabilityDetails: CapabilityDetails[]) => void,
failureCallback: (errorCode: number, errorString: string) => void
): void;
Parameters
successCallback
: A callback function that is executed if the request succeeds.
capabilityDetails
: Detailed information about the specified capabilities. Please refer to CapabilityDetails.
failureCallback
: A callback function that is executed if the request fails.
errorCode
: The error code.errorString
: The error string.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v16.0+ | v16.0+ | v16.0+ | v16.0+ | v16.0+ | v18.2+ |
setCapabilities
Sets up one or multiple capabilities in one call.
Syntax
setCapabilities(
capabilities: Capabilities,
successCallback: (capabilities: Capabilities) => void,
failureCallback: (capabilities: Capabilities) => void
): void;
Parameters
capabilities
: An object that describes how to set capabilities.
successCallback
: A callback function that is executed if the request succeeds.
capabilities
: The capabilities to set.
failureCallback
: A callback function that is executed if the request fails.
capabilities
: The capabilities to set.
Please refer to Capabilities.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v16.0+ | v16.0+ | v16.0+ | v16.0+ | v16.0+ | v18.2+ |
Usage notes
To make things easier, Dynamsoft designed the API with a simplified parameter Capabilities
which only requires the minimum information for setting a capability: a number to specify the capability and the value to set to it. Underneath, Dynamsoft takes care of container type setting, value type setting as well as data validation.
Pay attention to the argument you set to the overall parameter exception
and the individual parameter exception
for each capability. If the overall parameter is set to fail
, the setting will abort as soon as an exception is raised while setting any of the capabilities. Otherwise, ignore
means to carry on setting the next capability even when the previous one failed. Aside from the overall parameter, the individual exception
is optional but takes precedence if set. In other words, you can set the overall exception
to ignore
and then set the individual one to fail
for the capabilities which you think are important. This way, you get notified if these important capabilities failed to be set while other less-important ones are ignored when setting them failed.
Example
DWObject.SelectSourceByIndex(0);
DWObject.IfShowUI = false;
DWObject.OpenSource();
DWObject.setCapabilities(
{
exception: "ignore",
capabilities: [
{
capability: Dynamsoft.DWT.EnumDWT_Cap.ICAP_CONTRAST, // your own capability
curValue: 500, // your own curValue
},
{
capability: Dynamsoft.DWT.EnumDWT_Cap.CAP_PRINTERSTRING, // your own capability
curValue: "abc", // your own curValue
exception: "fail",
},
{
capability: Dynamsoft.DWT.EnumDWT_Cap.ICAP_PIXELTYPE, // your own capability
curValue: 0, // your own curValue
},
],
},
function (successData) {
DWObject.AcquireImage(
function () {},
function () {
console.log(DWObject.ErrorString);
}
);
},
function (errorData) {
console.error(errorData);
DWObject.AcquireImage(
function () {},
function () {
console.log(DWObject.ErrorString);
}
);
}
);
GetDevicesAsync
Return all available devices (scanners, eSCL scanners, etc.) for the device type (if specified)
Syntax
GetDevicesAsync(deviceType?: Dynamsoft.DWT.EnumDWT_DeviceType | number, refresh?:boolean): Promise<Device[]>;
Parameters
deviceType
: The device type. Please refere to EnumDWT_DeviceType
refresh
: Default value is false
Arguments
Device
: Please refer to Device.
Example
DWObject.GetDevicesAsync().then((deviceList)=>{
return DWObject.SelectDeviceAsync(deviceList[0]) //Select the first device
}).then(()=>{
return DWObject.AcquireImageAsync({})
}).catch((e)=>{
console.error(e)
})
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.2+ |
SelectDeviceAsync
Select the device to use for scanning
Syntax
SelectDeviceAsync(device: Device): Promise< boolean>;
Example
DWObject.GetDevicesAsync().then((deviceList)=>{
return DWObject.SelectDeviceAsync(deviceList[0]) //Select the first device
}).then(()=>{
return DWObject.AcquireImageAsync({})
}).catch((e)=>{
console.error(e)
})
Parameters
device
: the device object. Please refer to Device.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.2+ |
AcquireImageAsync
Scan documents into another DWObject control. eSCL is not supported.
Syntax
AcquireImageAsync(deviceConfiguration?: DeviceConfiguration): Promise< boolean>;
Parameters
deviceConfiguration
: The device configuration. Please refer to DeviceConfiguration.
Availability
ActiveX | H5(Windows) | H5(macOS/TWAIN) | H5(macOS/ICA) | H5(Linux) | Android Service |
v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.0+ | v18.2+ |
Example
DWObject.GetDevicesAsync().then((deviceList)=>{
return DWObject.SelectDeviceAsync(deviceList[0]) //Select the first device
}).then(()=>{
return DWObject.AcquireImageAsync({})
}).catch((e)=>{
console.error(e)
})