| Herd Software Development
DaVinci Graphics Library
DaVinci Documentation Home Search Order

Using Leonardo's TWAIN interface

The TWAIN scanner interface is an industry standard interface used by Windows for the transfer of data, usually graphical in nature, from scanning devices (flatbed scanners, digital cameras, hand scanners, etc.) directly into applications which can make use of this data.

Leonardo simplifies the implementation of TWAIN functionality into applications by providing several standard functions for working with TWAIN-compliant devices.

Leonardo does not act as the interface between the hardware device and the application, however. The actual TWAIN interface is contained within TWAIN.DLL and/or TWAIN32.DLL which is either provided with the hardware device as part of its driver software or installed with Windows when TWAIN-compliant devices are detected as new hardware.

It should be clear to all developers that PCs are not universally shipped with scanners, fax devices or cameras. This means that TWAIN drivers and interface software may not be present on all PCs on which your software will be deployed. TWAIN access features built into your software should always be supplied as optional menu items or on-demand features which are either unavailable or trapped by your application if TWAIN.DLL or TWAIN32.DLL are not found on the target machine.

Simplified API call

Accessing TWAIN-compliant devices for acquisition of image data can be reduced to a single function within Leonardo, TWAINGetImage. When using this function in applications, always keep in mind that the scanning (acquisition) process is normally an application-modal process. The user will not, and should not, have access to the application acquiring the data until acquisition is complete. When using this function, no other function calls are neccessary.

Initializing TWAIN

All applications accessing the TWAIN interface need to call the TWAINInitialize function to initialize the acquisition processs. This function returns a handle used in subsequent calls to the TWAIn interface. Before the application terminates, it must call the function TWAINTerminate, function to release any hidden windows which may have been created by the acquisition software itself. The TWAINInitialize function returns without any severe error if no TWAIN.DLL or TWAIN32.DLL can be found.

Selecting the data source

As with printers and modems, PCs can have multiple TWAIN devices connected, meaning that a default device needs to be selected before acquisition can begin. As with printers, users can alternate between different TWAIN devices during the same session within a given application. But it's up to you to give the user access to their list of TWAIN-compliant devices. The system will not call a device selection dialog prior to acquisition unless you specifically call the TWAINSelectDS. function to open the dialog. The selection results are stored in a file and used automatically on the next aquire process.

Initiating the scan (acquisition)

Scanning is initiated by calling TWAINAquire,, which opens an instance of the scanner's interface software. At that point, the scanner's software is responsible for all action between the user and the TWAIN device until data acquisition is complete.

Applications must insure that no TWAIN data sources are open on the system prior to executing TWAINAquire. Leonardo provides the TWAINIsDSMOpen function to alert the application to possible conflicts. Buttons or menu items can then be disabled, or alerts opened, if open TWAIN sources are found.

In order to insure that the scanning process is working correctly, a data processing procedure is provided which monitors the Windows message stream for messages specific to the scanner interface. TWAINIsTwainMessage is provided as a simple means of intercepting and handling TWAIN-related messages within your application.

Unattended Scanning: Scanning without user interaction

The function TWAINAquireExt allowes scanning without displaying the user interface. With the functions TWAINSetResolution and TWAINSetRect, allow setting the image resolution and the frame of the paper selected to be scanned. The function TWAINCallDS can be called to make further TWAIN API calls, however this requires detailed knowledge of the TWAIN API.

Þ Problems with TWAIN - implementations

Transfer of scanned data to the requesting application

After a successful acquisition, (a scan that terminated without errors), the scanned image is transferred to the requesting application via the UWM_TWAINIMAGERECEIVED message. The wParam of this message contains a memory block in the CF_DIB data format.

Þ problems with TWAIN - implementations

Þ example for unattended scanning

Þ function TWAINInitialize

Þ function TWAINAquireExt