This function retrieves an image from a TWAIN scan device
Parameters
| Name | Explanation |
|---|---|
| AppHandle | The application handle retrieved by IKScanInitialize |
| SrcHandle | The scan device handle retrieved by IKScanOpenDS |
| Image | A structure (user-defined type) whose member variable contain the scan settings |
| BeforeScanProc | The address of the user function that executes prior to the image being scanned (set to 0 if not needed.) |
| ScanningProc | The address of the user function that executes while the image being scanned (set to 0 if not needed.) |
| AfterScanProc | The address of the user function that executes
after the image being scanned (set to 0 if not needed.) If the user function name is AfterScanProc then the syntax is as follows: (1)C++Builder AfterScanProc (2)Delphi Longint(Addr(AfterScanProc)) or Longint(@UserProc) |
| Index | An array containing the image indexes. (used with a
digial camera) In C++Builder, pass the pointer to the first element in the array. In Delphi, the arguments are returned in the first element of the array x[0] of DWORD. *When not using an index array, set this to NULL or to a dummy array. |
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 Ik10Scan.dll, Ik10ScanA.dll, Ik10Scan64.dll,
Ik10Scan64A.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, Border, BorderColor,
BorderDetection, Brightness, ColorBWRatio, Contrast, Deskew,
DropoutColor, DynamicThreshold, FocusPosition, Gamma, HalfTone,
Highlight, IgnoreBackColor, ImageFilter, ImageMerge, 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, Border, BorderColor, 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]
| Function Name | Parameters |
|---|---|
| IK5ScanExec: | hWnd, Image, ScanUserProc |
| IKScanExec: | AppHandle, SrcHandle, Image, BeforeScanProc, ScanningProc, AfterScanProc, Index |
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 ImageKit10 ActiveX
[Differences from the ImageKit6]
New member variables have been added to the IKSCAN_EXEC structure.
[Differences from the ImageKit7]
New member variables have been added to the IKSCAN_EXEC structure.
[Differences from the ImageKit8]
New member variables have been added to the IKSCAN_EXEC
structure.
Defintions of User Function
BeforeScanProc: Control is passed to this procedure just before the image is scanned
[Syntax]
(1)C++Builder
BOOL __stdcall BeforeScanProc(PTR_IKSCAN_IMAGEINFO ImageInfo, long
Count);
(2)Delphi
function BeforeScanProc(var ImageInfo: IKSCAN_IMAGEINFO; Count:
Integer): LongBool; stdcall;
[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
BOOL __stdcall ScanningProc(short Percent);
(2)Delphi
function ScanningProc(Percent: Smallint): LongBool; stdcall;
[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
BOOL __stdcall AfterScanProc(HANDLE DibHandle, HANDLE OrgHandle,
long Count, short BitOrder);
(2)Delphi
function AfterScanProc(DibHandle, OrgHandle: THandle; Count:
Integer; BitOrder): LongBool; stdcall;
[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