Accessing TWAIN compatible scanner in Visual Basic

PREFACE

http://lmik.sweb.cz/

This page describes the way VB programmers can use TWAIN scanners.

Developing some application I needed to access a scanner without showing the user interface that comes with a scanner driver. I have been searching the Internet to get some VB code concerning this topic but I found some DLLs or OCXs only (I must mention here a very handy dll called eztwain from www.dosadi.com). Finally I decided to dig into that problem by myself.

I have made a VB Module that can transfer one image at a time from scanner and save it as a file (BMP). There are three public functions in the module:

PopupSelectSourceDialog - shows TWAIN dialog for selecting default data source for acquisition
TransferWithoutUI - transfers one image from TWAIN data source without showing the data source user interface (silent transfer). The programmer can set following attributes of the image:The image is saved into the BMP file.

resolution (DPI)
colour depth - monochromatic, grey, fullcolour
image size and position on the scanner glass - left, top, right, bottom (in inches).

TransferWithUI - transfers one image from TWAIN data source using the data source user interface to set image attributes.The image is saved into the BMP file.

Functions return 0 if everything is OK, 1 if an error occurs.

ABOUT TWAIN

The way one can access an optical scanner is through a standard called TWAIN. If you want to get real knowledge about it I strongly recommend you to read the twain specification, located inwww.twain.org. If you just want to touch it briefly I can tell you that your application can communicate with the scanner using the DSM_Entry function located in the twain library.

To simply get one image one must:

open data source manager (twain dll)
open data source (scanner)
enable data source
transfer image from data source
disable data source
close data source
close data source manager.

Using different TWAIN triplets as the DSM_Entry function parameters, the programmer communicates with the data source manager or with the data source. For example a triplet DG_CONTROL DAT_PARENT MSG_OPENDSM opens data source manager, a triplet DG_CONTROL DAT_PARENT MSG_CLOSEDSM closes data source manager.

DECLARATION

First of all one must convert C declaration from twain.h into VB one. This is not much difficult if one has experienced it before. Declaration in twain.h says that TW_UINT32 is an unsigned longtype, TW_UINT16 is an unsigned short type, pTW_IDENTITY is a pointer to TW_IDENTITY structure and TW_MEMREF is a pointer to void.

Therefore

TW_UINT16 FAR PASCAL DSM_Entry (pTW_IDENTITY pOrigin, pTW_IDENTITY pDest, TW_UINT32 DG, TW_UINT16 DAT, TW_UINT16 MSG, TW_MEMREF pData);

is converted into:

Private Declare Function DSM_Entry Lib "TWAIN_32.DLL" _ (ByRef pOrigin As Any, _ ByRef pDest As Any, _ ByVal DG As Long, _ ByVal DAT As Integer, _ ByVal MSG As Integer, _ ByRef pData As Any) As Integer

But there is a problem in converting some UDTs and it is called byte alignment. VB uses 4-byte alignment in UDT and adds so-called padding bytes to keep this kind of alignment. If Len of UDT differs from UDT's LenB you know there are some padding bytes in this UDT. Here in TWAIN, it is important to eliminate those padding bytes to get right values into right places (bytes) in UDT variables.

Example:

C declaration:

typedef struct { TW_UINT16 ItemType; TW_UINT32 Item; } TW_ONEVALUE, FAR * pTW_ONEVALUE;

VB declaration:

Private Type TW_ONEVALUE ItemType As Integer ' TW_UINT16 Item As Long ' TW_UINT32 End Type

Using this kind of declaration VB adds 2 padding bytes after the ItemType variable. So the size of TW_ONEVALUE becomes 8 bytes instead of 6 bytes. To eliminate padding bytes you may cut one Long type variable into two Integer ones:

Private Type TW_ONEVALUE ItemType As Integer ' TW_UINT16 Item1 As Integer ' TW_UINT32 Item2 As Integer End Type

EXAMPLES OF USE

Finally there are some examples how to use this module in your code:

Let us scan a greyscale image with 200 DPI and save it as noui_grey.bmp. We want to scan the whole scanner glass (set sngImageRight and sngImageBottom to 0) and we want to use silent transfer without showing the data source user interface:
Dim lRtn As Long lRtn = mdlTwain.TransferWithoutUI(200, GREY, 0, 0, 0, 0, _ "noui_grey.bmp")
Let us scan a monochromatic image with 300 DPI and save it as noui_mono.bmp. We want to scan the partial rectangle (left=1, top=1, right=2, bottom=5 inches) of the scanner glass and we want to use silent transfer without showing the data source user interface:
Dim lRtn As Long lRtn = mdlTwain.TransferWithoutUI(300, BW, 1, 1, 2, 5, _ "noui_mono.bmp")
Let us scan an image using the data source user interface to set its attributes and save it as ui.bmp:
Dim lRtn As Long lRtn = mdlTwain.TransferWithUI("ui.bmp")
Let us choose the default data source (scanner) that will be used for next transfers:
Dim lRtn As Long lRtn = mdlTwain.PopupSelectSourceDialog()

UPDATES AND CHANGES

2004/10/14 - Major changes. I have completely rebuilt the code and have numbered it as version 1.0.

As I left my first ideas about this code to be a class, I have changed it into VB module
Added option to transfer image with UI enabled - new public function TransferWithUI
Added option to select source - new public function PopupSelectSourceDialog
Added universal functions to set and get transfer and image attributes
Added some macros for converting data types
Added a lot of comments (hope useful)

2004/03/30 - The new class version with corrected DMS_Entry function declaration.

DOWNLOAD AND CONTACT

The module can be downloaded here (version 1.0 - free to any use). I appreciate any feedback from you. It can be sent to LMik@seznam.cz.

Let me say a word of thanks to Alfred Koppold, who helped me with setting the scanner resolution and whose feedback helped me to understand the byte alignment problem.