EZTwain Pro User Guide A developer's guide to the EZTwain library version 3.91 Hyperlinks EZTwain Pro page: http://www.eztwain.com/eztwain3.htm Support: http://www.atalasoft.com/products/dotimage/forums Author Spike McLarty for Atalasoft Revised 11/30/2011 Copyright © 2003-2011 by Atalasoft, a Kofax company. All rights reserved. Trademarks EZTwain Pro is a trademark of Atalasoft. Microsoft and Windows are trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners. EZTwain Pro User Guide Table of Contents Table of Contents ............................................................................................. 1 Introduction ..................................................................................................... 3 Overview ......................................................................................................... 4 EZTwain Components .................................................................................... 4 EZTwain Developer Files ................................................................................ 6 How-To Guide .................................................................................................. 8 How To: Use the Code Wizard to get started ..................................................... 8 How To: Use EZTwain from other languages ................................................... 10 How To: Statically Link to EZTwain ................................................................ 11 How To: Redistribute EZTwain with your Application ........................................ 12 How To: Obtain a License Key ....................................................................... 13 How To: Select a Device for Input ................................................................. 14 How To: Acquire an Image ........................................................................... 16 How To: Negotiate Scanning Parameters ........................................................ 17 How To: Scan a Multipage Document ............................................................. 18 How To: Hide the Source User Interface ......................................................... 19 How To: Control a Document Feeder (ADF) ..................................................... 20 How To: Skip Blank Pages ............................................................................ 21 How To: Read Patch Codes ........................................................................... 22 How To: Append to PDF, TIFF & DCX Files ...................................................... 23 How To: Check for Device On-Line ................................................................. 23 How To: Do Other Random Stuff ................................................................... 23 Function Reference ......................................................................................... 25 Functions – Application Name & Licensing ...................................................... 25 Functions – Image Acquisition ....................................................................... 28 Functions – Global Modes & Queries ............................................................... 36 Functions – Post-Processing .......................................................................... 38 Functions – Extended Image Information ....................................................... 42 Functions – DIBs & Image Processing ............................................................. 45 Functions – Printing ..................................................................................... 70 Functions – Barcode Recognition ................................................................... 74 Functions – Optical Character Recognition (OCR) ............................................ 81 Functions – Image Files ................................................................................ 86 Functions – Image Files in Memory ................................................................ 97 Functions - TIFF Specific .............................................................................. 99 Functions - PDF Specific ............................................................................. 102 Functions – File Uploading .......................................................................... 109 Functions – Image Viewing ......................................................................... 115 Functions – Error Handling & Logging ........................................................... 118 Functions – TWAIN State ............................................................................ 121 Functions – Capability ................................................................................ 124 Functions – Settings Dialog ......................................................................... 142 Functions – Custom DS Data ....................................................................... 143 Functions – Container ................................................................................ 144 Functions – Testing & Validation .................................................................. 148 Functions – Obscure (Even for TWAIN) ......................................................... 149 Glossary ...................................................................................................... 157 Appendix 1 - History ..................................................................................... 163 Appendix 2 - Working with Containers ............................................................. 165 Appendix 3 - Multithreading with EZTwain ....................................................... 171 Appendix 4 - EZTwain Datatypes .................................................................... 173 Index .......................................................................................................... 175 EZTwain Pro User Guide Page 2 EZTwain Pro User Guide Introduction This guide describes how to use the Atalasoft EZTwain library to add scanning or image-acquisition to a Microsoft® Windows® application. If you don’t know much about TWAIN, the image-input standard that EZTwain is built on, don’t worry – the necessary concepts and explanations are included. For a condensed list of changes in this Guide, see Appendix 1 - History. What is EZTwain? EZTwain is a Windows DLL that provides an easy-to-use wrapper for the TWAIN API. TWAIN is the most widely supported API for controlling scanners, and downloading images from cameras. EZTwain makes TWAIN easier for developers by radically reducing their learning and programming effort – which means fewer bugs, lower cost, more predictability, shorter schedules, and we believe fewer support problems. With EZTwain, you can . Acquire an image from a TWAIN-compliant device, bringing the image into memory or writing it immediately to a file, with one call. Select the output file format to be BMP, JPEG, PNG, DCX, TIFF, or PDF. Display the TWAIN dialog that allows the user to select among his or her TWAIN devices, or - enumerate the devices and present a list to the user, or - select a specific device by name. Suppress the normal user interface presented by a device, and take control of the scanning process from your program. Restrict or pre-select the scanning mode (B&W, Grayscale, RGB Color), the bit-depth, resolution, transparent versus reflective media, brightness, contrast, threshold, auto-brightness, duplex, and any other options offered by the device through TWAIN. Detect and control a document feeder (ADF). Scan multiple pages, discard blank pages, deskew (straighten) crooked pages. Collect scans into multi-page TIFF, DCX, or PDF files. Load, examine, display, and write image files in all supported formats. Query any property that your TWAIN device offers, and manipulate that property in any way allowed by TWAIN and the device. Upload images to a server via HTTP in any supported file format. Atalasoft maintains, supports, and licenses EZTwain, as well as other tools for TWAIN developers. For more information, please visit www.atalasoft.com. EZTwain Pro User Guide Overview EZTwain Components The EZTwain Pro Toolkit setup offers to install two sets of files: Shared EZTwain DLLs Developer Files (or both) If you choose to install the Shared DLLs, the DLLs listed in the table below are copied to the System folder: C:\Windows\System32 (on most 32-bit versions of Windows) C:\Windows\SysWOW64 (on 64-bit Windows) If you choose to install Developer Files, the DLLs listed below are copied into C:\Program Files\EZTwain\Redist (32-bit Windows) C:\Program Files(x86)\EZTwain\Redist (64-bit Windows) These are the DLLs that you use and distribute with your applications. If you are concerned about disk space or file sizes, the table below will help you decide which DLLs are required for your application. See also: How to Redistribute EZTwain with your Application, page 12 Note that on 64-bit Windows, 32-bit processes that access the 'System32' folder are redirected to SysWOW64 – which means that if your 32-bit code loads e.g. “\Windows\System32\Eztwain3.dll”, this will still work on 64-bit Windows. Shared EZTwain DLLs Eztwain3.dll DLL containing the EZTwain Pro functions. It is not an ActiveX control or COM server, and does not need to be registered. EZJpeg.dll Optional DLL. Required to read and write JPEG, TIFF or PDF format files. EZTiff.dll Optional DLL to read and write TIFF files. Requires EZJpeg.dll. EZPdf.dll Optional