IKScanExec

This function retrieves an image from a TWAIN scan device

Parameters

Return Value

Returns the number of scanned images if successful. Returns 0 if unsuccessful or if there were no images retrieved.

Explanation

The IKScanExec function retrieves an image from a TWAIN datasource (scan device).

If the SrcHandle is being used with the value retrieved by the IkScanOpenDS then no other application can use the opened scan device until it has been closed.

The Image parameter contains the scan information. For more information about IKSCAN_EXEC member variables, see the IKSCAN_EXEC in the Structure Definitions and Explanations in the Ik8Scan.dll, Ik8ScanA.dll, Ik8Scan64.dll, Ik8Scan64A.dll section.

When UiMode is 0 or 1 then all member variables except ScanDsName, TransferMode, and Compression are disabled. When SrcHandle is 0, ScanDSName is required otherwise ScanDSName is disabled. Index is only enabled when the UiMode is 2 and the ScanMode refers to digital camera however, when not needed please set Index to NULL or to a dummy array. Index is used to specify which images to retrieve from a digital camera (enabled when ScanMode is 4 or 6). For example to retreive the 5th and 8th image from a digital camera:

Index(0) = 5
Index(1) = 8

The Index array will have 2 elements and 2 will be set into PageCount member variable.

Control is passed to user procedures (BeforeScanProc, AfterScanProc, ScanningProc) before, during, and after each image is scanned so it is possible to write processing code in each of these stages of the scan process. Depending on the scan device some functionality may not be supported. In such cases, only the supported functions will be used to scan.

The following member variables should be set prior to executing the IKSCAN_EXEC function 

The following are required settings: 
ScanDsName (If a blank string is used in ScanDsName then IKScanSelect must be executed first)
     *If the IKScanOpenDS function has been executed the ScanDsName is disabled and the open datasource is used.
TransferMode, Compression, UiMode, (If an Epson scan driver is used then ExtUiMode is required)

The following are necessary depending on the scan settings:
FileFormat, FileName, InformationFileName, JpegQuality

These are also necessary when UiMode is 2:

(1) For Scanners
AdjustGamma, BitDepth, BitDepthReduction, BorderDetection, Brightness, ColorBWRatio, Contrast, Deskew, DropoutColor, DynamicThreshold, FocusPosition, Gamma, HalfTone, Highlight, IgnoreBackColor, ImageFilter, Indicator, MoireFilter, NoiseFilter, Orientation, OverScan, PageCount, PaperSize, PixelType, RemoveHole, Rotation, ScanMode, ScanningSpeed, Shadow, Sharpness, SkipBlankPage, SkipBlankThreshold, TextEnhancement, Threshold, UnitFlag, UnitMode, XResolution, XScaling, YResolution, YScaling
PaperSize<=0: Bottom, Left, Right, Top

Note: Depending on the scan driver, the following may be disabled: AdjustGamma, ColorBWRatio, DynamicThreshold, FocusPosition, IgnoreBackColor, MoireFilter, RemoveHole, RotateBack, ScanningSpeed, Sharpness, SkipBlankThreshold, TextEnhancement

(2) For Digital Cameras
PageCount, ScanMode, UnitMode Note: When ScanMode=1, set XResolution = 0.

The following member variables can be retrieved after the IKSCAN_EXEC function executes
BitDepth, Bottom, Compression, FileFormat (when using file transfer), Left, PixelType, Right, Top, UnitMode, XResolution, YResolution

Important points when using a custom built user interface (UiMode = 2)
When UiMode is 2, depending on the scan device and the property values set, the scan can fail. For the most part the causes for scan failure when the UiMode is 2 can be traced to the following:

1. The scan units set are not supported by the scan device. The supported scan unit values can be retrieved using IKScanGetCapEnum.
2. The pixel type set is not supported by the scan device. The supported pixel type values can be retrieved using IKScanGetCapEnum or IKScanGetCapPixelType
3. The bit count set is not supported by the scan device. The supported bit count values can be retrieved using IKScanGetBitDepth.
4. The resolution set is not supported by the scan device. The supported resolution values can be retrieved using IKScanGetCapEnum or IKScanGetCapRange.
5. The paper size set is not supported by the scan device. The supported values can be retrieved using IKScanGetCapEnum. If settings for paper size are not supported at all, then set PaperSize to 0 and set the appropriate scan area in the Left, Top, Right, and Bottom properties. If the scan area is not correctly set (i.e. it is smaller than the minimum or larger than the maximum), the scan can fail. The proper scan area values can be retrieved using IKScanGetMinimumSize, IKScanGetMinimumSizeEx, IKScanGetPhysicalSize, or IKScanGetPhysicalSizeEx. If paper size settings are supported and the scan still fails, check to make sure PaperSize is set to a value other than 0

[Differences from the ImageKit5]

In the ImageKit6, hWnd is passed to IKScanInitialize and the return value is used in AppHandle.
The ImageKit5 ScanUserProc has become AfterScanProc in ImageKit6 and later versions of the ImageKit. The Image structure is different in the ImageKit5 and ImageKit8 ActiveX

[Differences from the ImageKit6]
New member variables have been added to the IKSCAN_EXEC structure.

Defintions of User Function

In Visual Basic, create user functions in standard modules not form modules.

BeforeScanProc: Control is passed to this procedure just before the image is scanned

[Syntax]
(1)C++Builder/Visual C++
BOOL __stdcall BeforeScanProc(PTR_IKSCAN_IMAGEINFO ImageInfo, long Count);

(2)Delphi
function BeforeScanProc(var ImageInfo: IKSCAN_IMAGEINFO; Count: Integer): LongBool; stdcall;

(3)Visual Basic
Function BeforeScanProc(ImageInfo As IKSCAN_IMAGEINFO, ByVal Count As Long) As Long

[Parameters]

Name Explanation

------------------------------------------------------------------------------------------------------

ImageInfo Contains information about the image to be scanned.
Count The number of the image to be scanned (from 1)

[Return Value]

If False (0), then the scan is terminated. If True (nonzero) then the scan continues.

If the PaperSize in the IKSCAN_EXEC structure is set to 1000, the ImageInfo's Width and Height may be returned as -1. Also it is possible for the Width and Height to be returned with values exceeding the size of the actual document plate. When the PixelType in the IKSCAN_EXEC structure is set to 1000, the ImageInfo's BitDepth and PixelType may be returned with values that differ from the actual image.

The above explanation applies to the user function named BeforeScanProc. If fact it is possible to assign any name that you wish to this user function.

ScanningProc: Control is passed to this procedure while the image is being scanned

[Syntax]

(1)C++Builder/Visual C++
BOOL __stdcall ScanningProc(short Percent);

(2)Delphi
function ScanningProc(Percent: Smallint): LongBool; stdcall;

(3)Visual Basic
Function ScanningProc(ByVal Percent As Integer) As Long

[Parameters]

Name Explanation

------------------------------------------------------------------------------------------------------

Percent The percentage of the scan completed (from 0 to 100 percent)

[Return Value]

If False (0), then the scan is terminated. If True (nonzero) then the scan continues
Note: This function is enable for memory transfer only. It is disabled for native transfer.

The above explanation applies to the user function named ScanningProc. If fact it is possible to assign any name that you wish to this user function.

AfterScanProc: Control is passed to this procedure after the image has been scanned

[Syntax]
(1)C++Builder/Visual C++
BOOL __stdcall AfterScanProc(HANDLE DibHandle, HANDLE OrgHandle, long Count, short BitOrder);

(2)Delphi
function AfterScanProc(DibHandle, OrgHandle: THandle; Count: Integer; BitOrder): LongBool; stdcall;

(3)Visual Basic
Function AfterScanProc(ByVal DibHandle As Long, ByVal OrgHandle As Long, ByVal Count As Long, ByVal BitOrder As Integer) As Long

[Parameters]

Name Explanation

------------------------------------------------------------------------------------------------------

DibHandle The DIB memory handle which is the memory handle that can be processed by Windows
OrgHandle The memory handle that cannot be processed by Windows (12, 14,16 bit grayscale or 36,42, or 48 bit color)
Count The number of images scanned
BitOrder This parameter refers to whether the bits in each byte of the scanned image start from the left or start from the right. 0: Start from the right (LSB), 1: Start from the left (MSB)

[Return Value]

If False (0), then the scan is terminated. If True (nonzero) then the scan continues

Note: The scanned image's memory handle (DibHandle and OrgHandle) is freed after this procedure finishes so if you want to use this image data in any way you must make a copy of the scanned image in the memory or save it in an image file. If the scanned image is 1, 4, 8, or 24 bits then the image will be set in the DibHandle and 0 will be set in the OrgHandle. If the scanned image is 12, 14, 16 bit grayscale, or 36, 42, or 48 bit color then the original image data will be set in the OrgHandle and the image data set in the DibHandle will be 8 bit grayscale or 24 bit color. If the image data is not supported by DibHandle, then it will be set to 0. Furthermore, when the UiMode property is 2 (ikScanNONUI) and the UnitMode property is 5 (ikScanPixel), depending on the datasource, the XResolution and YResolution values are set to 1

The above explanation applies to the user function named AfterScanProc. If fact it is possible to assign any name that you wish to this user function.

[Differences from the ImageKit5]
The BitOrder parameter has been added in the ImageKit6