Atalasoft DotTwain 2.

1 Developer's Guide | 1

Twain Acquisition for Microsoft .NET

Developer's Guide for Atalasoft DotTwain 2.1

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 2

Table Of Contents
1. 2. 3. 4. 5. 6. Introduction Overview Getting Started Deployment License Agreement History 6.1. What's new in DotTwain 2.1 6.2. What's New in DotTwain 2.0 7. How To's 7.1. Acquire a Select Region of the Device 7.2. Acquire Directly to a File 7.3. Detecting a Camera Device 7.4. Embed in Internet Explorer 7.5. Upload an Image to a Server 3 4 5-7 8 9-12 13 13 13-14 15 15-16 16-18 18 18-19 19-21

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 3

Introduction
Atalasoft DotTwain 2.1 is a 100% Managed .NET Windows Form component with fast capturing of digital images from scanners, cameras, and other devices supporting TWAIN. It utilizes the improvements of the TWAIN 1.9 specifications for ultra fast scanning. It works with a .NET Bitmap object and has no dependencies other then the .NET Framework. This is intended for a small footprint "no-touch" deployment over the web or if you need scanning abilities without Atalasoft dotImage.

1.1 Supported Features

l l l l l l l l l l

Full context sensitive help and documentation. Object-oriented design; a TWAIN extension to the .NET Framework. Create a custom interface to scan images, or use the default TWAIN interface. Automatic Document Feeder support, with full control of the feeder operations. Support for duplex scanning. File system support for navigating the internal device memory. Acquire images directly to file utilizing compression algorithms supported by the device. Select a region of the scanning bed to be acquired with frame support . Upload a scanned image to a server with the built in HTTP Post class. Supports Web Deployment ; Embed into an Internet Explorer Browser or deploy as a WinForms application Simplified automatic capture allowing the device to quickly capture multiple images for later acquisition. Imprinter/Endorser methods allowing a text string ito be stamped onto the acquired image during the acquisition. Barcode/Patchcode classes to access barcode and patchcode recognition abilities of the device. A low-level class allowing even more control over the scanning session for advanced users. Extensible to allow custom driver capabilities access. Image dataset support enables acquisition of specific images from a camera in a single operation. Quickly find out what capabilities, compression modes, frame sizes, resolutions and more, are supported by a device. Over 80 properties and 50 methods to give total control over the image acquisition.

l l

l l l l l

DotTwain has been tested on many industry leading document scanners including those from Kodak, Fujitsu, Panasonic, Canon, Visioneer, Xerox, and Bell & Howell.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 4

Overview
This topic introduces you to the basic classes to give you a general understanding of Atalasoft DotTwain and how to begin using it.

2.1 Acquiring Images

Acquisition The Acquisition object is the primary class in DotTwain. This component can be dropped onto a form after adding it to the toolbox, or be instantiated directly. For adding standard image acquisition capabilities to an application, this is the only class that is needed. For more control over the acquire process, this class contains a collection of Device objects that controls numerous properties used for the image acquisition. TwainController The TwainController object is a low-level TWAIN class used by the Device and Acquisition objects. Using this class can provide more direct access to TWAIN and allows custom driver capabilities to be used. This class can be created as a standalone object or can be accessed through the Device.Controller property. Only advanced users with knowledge of the TWAIN specification should attempt using this class. Device The Device object gives full access to a TWAIN compatible source on the system. It is used to open a connection to the device, get and set properties, and then acquire one or more images. Because this class represents a system device resource, you cannot create an instance of it. An instance to a Device object can be obtained by calling ShowSelectSource , or from the Devices collection in the Acquisition object. DeviceCollection The DeviceCollection holds a read-only collection of Device objects which represent all of the TWAIN compatible system resources. From this collection, the system default device can be obtained, or a suitable device can be found by enumerating through the collection. Should system conditions change, such as a device being unplugged, the ScanForChanges method is used to recreate this collection.

2.2 Document Feeder Control

DocumentFeeder Many scanners have an automatic document feeder (ADF) allowing multiple images to be scanned in a single process. The DocumentFeeder class gives full control over the feeder, as well as being able to enable or disable its use.

2.3 Navigating Files in a Camera

FileSystem The FileSystem object can be used to walk through the file system structure in a TWAIN compatible camera's internal storage or used to create, delete, copy and rename files and directories directly in the camera. Images are acquired from the camera by using the SetImageDataset method in the Device object, then calling the Acquire method of the same Device object.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 5

Getting Started
This topic explains how to get started using Atalasoft DotTwain in your applications.

3.1 Adding Atalasoft DotTwain to the Toolbox

To add the Acquisition component to the toolbox: 1. 2. 3. 4. Click Tools | Customize Toolbox on the Visual Studio .NET menu. Make sure the .NET Framework Components tab is selected, and find the Atalasoft.Twain namespace. Select the checkbox that corresponds to the Acquisition component. Click OK .

Acquisition is now included in your toolbox and you can double-click the control to add it to your form.

3.2 Setting Application Information

After you add the Acquisition control to your form, you should set the ApplicationIdentity properties which will be used by the TWAIN driver. If you don't set these properties, default values will be used. Setting the following properties is optional but recommended:
l l l l l l l l

Country Info Language Manufacturer ProductFamily ProductName VersionMajor VersionMinor

There is also a Parent property which is used by TWAIN when displaying dialogs and acquiring images. You must set the Parent property to the parent form or control in order to acquire images.

3.3 Modal Acquisition

By default, the Acquire method is asynchronous and will return before scanning has completed. This method can be made to work in a synchronous manner by using the Device object and setting its ModalAcquire property to true. An example of this is shown in the sample code below. [C#] this.device = this.acquisition.Devices.Default; this.device.ModalAcquire = true; this.device.Acquire(); [Visual Basic] Me.device = Me.acquisition.Devices.Default Me.device.ModalAcquire = True Me.device.Acquire()

3.4 Setting Up Events

For acquiring images events need to be used. When an image is acquired, the ImageAcquired event fires providing an AcquireEventArgs object containing the image. At the very least, the ImageAcquired event should be handled, but it's recommended that the AcquireCanceled and AcquireFinished events also be handled. The following code shows how the image is handled [C#] this.acquisition.ImageAcquired += new ImageAcquiredEventHandler(OnImageAcquired); private void OnImageAcquired(object sender, AcquireEventArgs e) { // If the image exists, load it into a WorkspaceViewer control. if (e.Image != null) { this.viewer.Images.Add(AtalaImage.FromBitmap(e.Image));

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 6

e.Image.Dispose(); } } [Visual Basic] Private Sub OnImageAcquired(ByVal sender As System.Object, ByVal e As Atalasoft.Twain.AcquireEventArgs) ' If the image exists, load it into a WorkspaceViewer control. If Not e.Image Is Nothing Then Me.viewer.Images.Add(AtalaImage.FromBitmap(e.Image)) e.Image.Dispose() End If End Sub

3.5 Showing the "Select Source" dialog

Your application should allow users to select which TWAIN device they want to use. This is accomplished by displaying the "Select Source" dialog using the ShowSelectSource method. The code below assumes the Acquisition component is named "acquisition". [C#] Device device = this.acquisition.ShowSelectSource(); [Visual Basic] Dim device As Device = Me.acquisition.ShowSelectSource() ShowSelectSource returns a Device object or null (Nothing in VB) if the user canceled the dialog. When a user selects a device in this dialog, it becomes the system default device.

3.6 Getting and Setting Properties

To get or set a device property, a connection to the device must be opened by using the Open method. Whenever the Open method is invoked, the Close method must be invoked to close the connection. Closing a connection will reset all of the device properties to their default values and therefore should be closed after the image has been acquired or all desired properties have. Open and Close only need to be used when getting or setting properties on the device. [C#] device.Open(); ResolutionData res = device.Resolution; int bitDepth = device.BitDepth; device.Close(); [Visual Basic] device.Open() Dim res As ResolutionData = device.Resolution Dim bitDepth As Integer = device.BitDepth device.Close() The above code opens a connection to the device in order to retrieve the default Resolution and BitDepth values of the device, then closes the connection. This technique may be useful if you are looking for a device in the DeviceCollection with specific default properties or capabilities. See QueryCapability for more information.

3.7 Acquiring an Image

You can acquire an image through the Acquisition object or from a Device object. If you don't need to get or set any properties, the easiest method is to use the Acquire from the Acquisition object, which will use the system default device. This is the method shown below: [C#] this.acquisition.Acquire(); [Visual Basic] Me.acquisition.Acquire() You can optionally hide the device interface and/or ask that the device save the acquired image directly to file. Once the image has been acquired, the ImageAcquired event will fire and provide an AcquireEventArgs object containing the image. If you invoked the Open method in order to set properties before the acquire,

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 7

you should invoke the Close method in the AcquireFinished event to close the device.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 8

Deployment
4.1 Windows Based Deployment
To distribute Atalasoft Twain for .NET with your .NET application you simple need to include Atalasoft.DotTwain.dll and Atalasoft.Shared.dll in the same folder as the assembly that references it. Make sure that the version you distribute is the version your assembly was compiled with.

4.2 Web Based Deployment

Also known as "no-touch install" this is a method of deploying a .NET assembly over the internet or intranet. Because Atalasoft DotTwain is a 100% managed code assembly this is possible however it does require the correct .NET security policy to be set. There are two methods of deploying over the internet. The first method is deploying the full Windows Form application as an EXE. This can be done with a strong name permission of the Atalasoft.DotTwain.dll assembly. The other method is embedding DotTwain into Internet Explorer via a UserControl. See our ASP.NET Demo for an example and the Deploy over the Internet (Section 7.4) topic for more details.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 9

License Agreement
ATALASOFT SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT IMPORTANT READ CAREFULLY: This License Agreement (the Agreement) is a legal contract between you (either an individual or single business entity)(LICENSEE) and Atalasoft, Inc., (Atalasoft or LICENSOR) for the software product identified above, which includes computer software and, as applicable, associated media, printed materials, and online or electronic documentation (collectively the Software). BY CLICKING THE AGREE OPTION BELOW, OR BY INSTALLING, COPYING OR OTHERWISE USING THE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT, INCLUDING THE WARRANTY DISCLAIMERS, LIMITATIONS OF LIABILITY AND TERMINATION PROVISIONS BELOW. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT INSTALL THE SOFTWARE, AND EXIT NOW. You are entitled to receive a full refund of any payment made for the Software by so requesting and returning any media and materials in unopened, unused condition and discarding any electronic serial numbers or registration information within 30 days after date of payment. 1. LICENSE GRANT AND LICENSE TERMS. This Agreement permits the LICENSEE the non-exclusive right to use one copy of a properly registered Atalasoft Software Development Kit (SDK), for development purposes on any two computers, provided the Software is in use on only one computer at any time, and is being used by the registered user. The Software is "in-use" on a computer when it is loaded into temporary memory (i.e. RAM) or installed into the permanent memory (i.e. hard disk, CD-ROM, or other storage device) of that computer. Its use in any other fashion is a default hereunder and Licensee shall be liable for all of Atalasoft's damages, including costs of collection and reasonable attorney's fees. It does not cover the use of the software under any other deployment condition, including without limitation: Kiosks, Quality Assurance/Testing Server License, COM Callable Wrapper Licenses for which a separate license agreement must be executed for an additional fee. In accordance with the deployment conditions contained in clause B of this Agreement, please contact our sales department for pricing. The Software accompanying this Agreement, regardless of the media on which it is distributed, is licensed to LICENSEE by Atalasoft. LICENSEE owns the medium on which the Software is recorded, but Atalasoft or its licensors retain title to the Software and related documentation. The license granted under this Agreement is subject to the terms and conditions contained herein. A. SDK License Conditions i. One License Per Developer. Developer is defined as an individual engaged in the development of a software application (the Application). Use of the Software requires one license per developer. Licenses are non-transferable between developers. For example, if a company has two developers that will use the Software, said company requires two licenses. This is the case even if the developers will not be working with the Software at the same time. This is also the case if a project involving the use of the Software is transferred from the original developer to a new developer and if the original developer returns within a one-year period. For easier access to the SDK and as a courtesy, the license allows a developer to install the SDK on up to two computers where the registered developer is the primary user (for example, a desktop workstation and a laptop). ii. No Application Programming Interfaces. This Agreement does not allow for exposing of the application programming interface (API) functionality to non-licensed users. LICENSEE may not create a dynamic link library (DLL) that exposes or wraps

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 10 functionality of the SDK to a non-licensed developer. Violation of this stipulation is subject to the interpretation of Atalasoft and no other party. Atalasoft reserves the right to seek punitive damages including, but not limited to, lost income from sales. Contact the Sales Department for information on an OEM license allowing the API to be exposed to other developers. B. Deployment Conditions i. One Server License Required Per Application Server. "Application Server" is defined as a non-user computer, with up to two physical CPUs, configured with the intention of multiple people accessing it for any kind of service that has Atalasoft Software loaded into the servers RAM. Use of this Software requires one license per server. An additional server requires an additional license. Servers with more than two physical CPUs need a server license per each additional pair (or less) of CPUs. ii. Custom License Agreement Required for Client Applet Server . Client Applet Server is defined as a non-user computer that is used to directly deploy Atalasoft Software to the client to use the Software directly from a Web Browser. This includes ActiveX components that are deployed via CAB files, and DLLs that are distributed via Microsoft .NET Web Deploy only when functionality is integrated within a browser. Please contact the Sales Department at Atalasoft to discuss the specifics of the deployment. Web Deploying an executable (EXE) that uses Atalasoft Software which is not embedded in a browser does not require a Server license. iii. Custom License Agreement Required for Kiosk. Kiosk is defined as a single computer or workstation where a deployed application containing Atalasoft code is installed. The application or the computer itself is configured for multiple users to access and use the application. Kiosk pricing is based upon volume of deployments as well as technology to be implemented in the application. Contact the Atalasoft Sales Department to determine pricing. iv. Quality Assurance(QA)/Testing Server Licenses. QA and Testing Server licenses are available on a case by case basis. Licensees may request a QA or Testing Server license from the Sales Department only after production server licenses have been purchased. QA and Testing Server licenses are never to be used in production. If a QA or Testing Server license has been issued to a licensee, responsibility for any and all upgrades and maintenance for the server license falls upon the licensee. v. COM Callable Wrapper. Atalasoft .NET imaging toolkits are designed to be used from other .NET applications. In the understanding that some licensees need to take advantage of the components using unmanaged code the licensor can accommodate by providing a custom assembly-tied license. This custom license will allow a licensee to call Atalasoft .NET assemblies from non .NET applications by developing a COM Callable Wrapper. This license requires custom development and a license amendment. Contact the Sales Department to determine pricing. vi. Royalty Free Runtime Desktop Distribution. "Desktop" is defined as an "end-user" personal computer (PC) that may have Applications installed that directly, or indirectly, utilize the Software. A single SDK provides for unlimited distribution of Applications utilizing the Software onto Desktop environments. This does not apply for DotImage OCR Expervision Engine, DotImage Advanced Document Cleanup(ADC), DotImage Advanced Photo Effects(APE), DotImage GlyphReader OCR Engine, or DotImage OCR PDF Translator Add-On. 2. GOVERNING LAW. If LICENSEE acquired this Software in the United States then the laws of the Commonwealth of Massachusetts shall govern this Agreement. If this Software was acquired outside the United States then local laws shall apply. THE LICENSEE HEREBY IRREVOCABLY AND UNCONDITIONALLY (A) SUBMITS TO PERSONAL JURISDICTION IN THE COMMONWEALTH OF MASSACHUSETTS OVER ANY SUIT, ACTION OR PROCEEDING ARISING OUT OF OR RELATING TO THIS AGREEMENT AND (B) WAIVES ANY AND ALL PERSONAL RIGHTS UNDER THE LAWS OF ANY STATE (I) TO THE RIGHT, IF ANY, TO TRIAL BY JURY, (II) TO OBJECT TO JURISDICTION WITHIN THE COMMONWEALTH OF MASSACHUSETTS OR VENUE IN ANY

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 11 PARTICULAR FORUM WITHIN THE COMMONWEALTH OF MASSACHUSETTS, AND (III) TO THE RIGHT, IF ANY, TO CLAIM OR RECOVER ANY SPECIAL, EXEMPLARY, PUNITIVE OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES OTHER THAN ACTUAL DAMAGES. THE LICENSEE AGREES THAT, IN ADDITION TO ANY METHODS OF SERVICE OF PROCESS PROVIDED FOR UNDER APPLICABLE LAW, ALL SERVICE OF PROCESS IN ANY SUCH SUIT, ACTION OR PROCEEDING MAY BE MADE BY CERTIFIED OR REGISTERED MAIL, RETURN RECEIPT REQUESTED DIRECTED TO THE LICENSEE AT THE ADDRESS SET FORTH ON PAGE ONE HEREOF, AND SERVICE SO MADE SHALL BE COMPLETE FIVE (5) DAYS AFTER THE SAME SHALL BE SO MAILED. NOTHING CONTAINED HEREIN, HOWEVER, SHALL PREVENT ATALASOFT FROM BRINGING ANY SUIT, ACTION OR PROCEEDING OR EXERCISING ANY RIGHTS AGAINST THE LICENSEE AND AGAINST ANY PROPERTY OF THE LICENSEE, IN ANY OTHER STATE. INITIATING SUCH SUIT, ACTION OR PROCEEDING OR TAKING SUCH ACTION IN ANY STATE SHALL IN NO EVENT CONSTITUTE A WAIVER OF THE AGREEMENT CONTAINED HEREIN THAT THE LAWS OF THE COMMONWEALTH OF MASSACHUSETTS SHALL GOVERN THE RIGHTS AND OBLIGATIONS OF THE LICENSEE AND ATALASOFT HEREUNDER OR THE SUBMISSION HEREIN BY THE LICENSEE TO PERSONAL JURISDICTION WITHIN THE COMMONWEALTH OF MASSACHUSETTS. 3. PROPRIETARY RIGHTS. i. Copyright. All title and copyrights in and to the Software (including, without limitation, any images, photographs, animations, video, audio, music, text, and applets incorporated into the Software), the accompanying media and printed materials, and any copes of the Software are owned by Vendor or its suppliers. Copyrights laws and international treaty provisions protect the Software. Therefore, LICENSEE must treat the Software like any other copyrighted material, subject to the provisions of this Agreement. ii. U.S. Government Restricted Rights. The Software and documentation are provided to the U.S. Government with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restriction as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraph (c)(1) and (2) of the Commercial Computer Software Restricted Rights at 48 C.F.R. 52.227-19, as applicable. Manufacturer for such purpose is Atalasoft, Inc. iii. Submissions. Should LICENSEE decide to transmit to Atalasofts Web site by any means or any materials or other information (including, without limitation, ideas concepts or techniques for new or improved services and products), whether as information, feedback, data, questions, comments, suggestions or the like, LICENSEE agrees such submissions are unrestricted and shall be deemed nonconfidential and LICENSEE automatically grants Atalasoft and its assigns a nonexclusive, royalty-free, worldwide, perpetual irrevocable license, with the right to sublicense, to use, copy, transmit, distribute, create derivative works of, display and perform the same. iv. Reverse Engineering, Decompilation and Disassembly. LICENSEE may not reverse engineer, decompile, or disassemble the Software, except and only to the extent that it is expressly permitted by applicable law notwithstanding this limitation. 4. DISCLAIMER OF WARRANTY. THIS SOFTWARE AND ACCOMPANYING FILES ARE PROVIDED AS IS. ATALASOFT AND ITS SUPPLIERS DO NOT AND CANNOT WARRANT THE PERFORMANCE OR RESULTS YOU MAY OBTAIN BY USING THE SOFTWARE OR SUCH FILES. ATALASOFT AND ITS SUPPLIERS MAKE NO WARRANTIES, EXPRESS OR IMPLIED, AS TO TITLE OR INFRINGEMENT OF THIRD-PARTY RIGHTS, MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE SOFTWARE. ANY LIABILITY OF ATALASOFT FOR A DEFECTIVE COPY OF THE SOFTWARE WILL BE LIMITED EXCLUSIVELY TO REPLACEMENT OF YOUR COPY OF THE SOFTWARE WITH ANOTHER COPY OF REFUND OF THE INITIAL LICENSE FEE ATALASOFT RECEIVED FROM YOU FOR THE DEFECTIVE COPY OF THE SOFTWARE. IN NO EVENT WILL ATALASOFT OR ITS

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 12 SUPPLIERS BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL, OR SPECIAL DAMAGES, INCLUDING ANY LOST PROFITS OR LOST SAVINGS, EVEN IF AN ATALASOFT REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 5. MARKETING. LICENSEE agrees to be identified as a customer of Atalasoft and LICENSEE agrees that Atalasoft may refer to LICENSEE by name, trade name and trademark, if applicable, and may briefly describe LICENSEES business in Atalasoft's marketing materials and Web site. LICENSEE hereby grants Atalasoft a license to use LICENSEES name and any of LICENSEES trade names and trademarks solely in connection with the rights granted to Atalasoft pursuant to this marketing section. However, Licensee agrees not to use the Atalasoft's name, logo, or trademarks to market the Application without prior written approval of Atalasoft. 6. UPGRADES. To use a product identified as an upgrade, LICENSEE must first be licensed for the Software identified by Atalasoft as eligible for the upgrade. After upgrading, LICENSEE may no longer use the Software that formed the basis for LICENSEES upgrade eligibility. 7. ADDITIONAL SOFTWARE. This Agreement applies to updates or supplements to the original Software provided by Atalasoft, unless we provide other terms along with the update or supplement. 8. TERMINATION. Without prejudice to any other rights, Atalasoft may cancel this Agreement if LICENSEE does not abide by the terms and conditions of this Agreement, in which case LICENSEE must destroy all copies of the Software and all of its component parts. 9. CONSENT TO USE OF DATA. LICENSEE agrees that Atalasoft and its affiliates may collect and use technical information LICENSEE provides as a part of the support services related to the Software. Atalasoft agrees not to use this information in a form that personally identifies LICENSEE. 10. SEVERABILITY. If for any reason a court of competent jurisdiction finds any provision of this Agreement or portion thereof to be unenforceable that provision of the Agreement shall be enforced to the maximum extent permissible so as to effect the intent of the parties, and the remainder of this Agreement shall continue in full force and effect. 11. NON-WAIVER. The failure of either party to enforce any rights granted hereunder or to take action against the other party in the event of any breach hereunder shall not be deemed a waiver by that party as to subsequent enforcement of rights or subsequent actions in the event of future breaches. 12. INDEMNIFICATION BY LICENSEE. If LICENSEE distributes the Software in violation of this Agreement, LICENSEE agrees to indemnify, hold harmless and defend Atalasoft and its suppliers from and against any claims or lawsuits, including attorneys fees that arise or result from the use or distribution of the Software in violation of the Agreement. 13. ENTIRE AGREEMENT. This Agreement, including any addendum or amendment to this Agreement which is included with the Software, is the entire agreement between LICENSEE and Atalasoft relating to the Software and the Support Services (if any) and they supersede all prior or contemporaneous oral or written communications, proposals and representations with respect to the Software or any other subject matter covered by this Agreement. To the extent the terms of any Atalasoft policies or programs for Support Services conflict with the terms of this Agreement, the terms of this Agreement shall control.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 13

6 6.1

History What's new in DotTwain 2.1

Atalasoft DotTwain 2.1 adds new functionality and features as outlined below.

6.1.1 New Features

l

An AutoDiscardBlankPages property was added. For drivers that support this feature it will automatically skip scanned pages it believes to be blank. Added LoadXmlParameters and SaveXmlParameters methods. Theses methods can be used to save and restore device settings without the driver needing to support any special capability.

6.1.2 Changes
l

DotTwain now requires distribution of Atalasoft.Shared.dll. Any project that uses DotTwain should also reference this new assembly.

6.2

What's New in DotTwain 2.0

Atalasoft DotTwain 2.0 adds new functionality, features, and add-ons as outlined below.

6.2.1 New Features

l

A low-level class named TwainController has been added to provide more control over the TWAIN session, allowing the developer to obtain more information directly from TWAIN while maintaining an easy to use interface. The TwainController can be used as a standalone object or accessed from the Device.Controller property to allow a mix of upper and lower-level coding. Added over 20 methods to the Device object that provide information on the values supported for specific capabilities. Added Barcode and Patchcode properties to the Device object that allow access to barcode and patchcode detection features supported by the device. Added support for buffered memory transfer. Added SaveParameters and LoadParameters methods that can be used to store device settings between sessions. The device must support the TwainTriplet.CustomDSDataSet capability to use these methods. Added Enable and Disable methods to the Device object that are used to keep the scanner interface displayed between scans. Added a BeforeTwainDataTransfer event that will provide general information on the image about to be scanned. This will allow you to cancel the scan if the image parameters do not meet your requirements. Added the ability to handle processing of the acquired data. This is convenient if the data is a format not supported directly in DotTwain. Added the ability to access custom driver properties that are not part of the TWAIN specification by using the TwainController and ITwainDataStructure interface for defining these capabilities. Added a CanOpen method which can be used to determine if a call to the Open method will succeed. Added a LastReturnCode property and GetConditionCode method which is used to provide more detailed information should setting a Device property fail to change its value. Added an ImageLayout property as an alternative to the Frame property for devices that do not support the DeviceCapability.ICAP_FRAMES. Added the ability to specify multiple frames when acquiring, provided the device has this capability.

l l

l l

6.2.2 Changes
l

Properties in the Acquisition object, such as Manufacturer, Country and Language, have been combined

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 14

into a TwainIdentity class. The Acquisition.ApplicationIdentity property now holds these values for your application and Device.Identity contains this information on the device.
l l l

The DeviceCapabilities enumeration has changed to match the names in the TWAIN specification. Device. GetSupportedCapabilities now returns an array of DeviceCapability instead of string. Renamed ImprinterEndorserTypes to ImprinterEndorserType and the None enumeration value has been removed. Device. GetSupportedPrinters now returns an array of ImprinterEndorserType. Renamed TwainDataImageInfoArgs to TwainDataImageInfoEventArgs. TwainResolution now uses float (Single) values instead of double. The following property types have been changed:

l l l l

Device.Brightness changed from Int32 to Single. Device.Contrast changed from Int32 to Single. Device.Gamma changed from Double to Single. Device.MinimumHeight changed from Double to Single. Device.MinimumWidth changed from Double to Single. Device.PhysicalHeight changed from Double to Single. Device.PhysicalWidth changed from Double to Single. Device.Rotation changed from Double to Single. Device.Shadow changed from Int32 to Single. Device.Threshold changed from Int32 to Single.

AcquireModal has been deprecated. Instead, set the Device.ModalAcquire property to True and use the Acquire method. This means you must handle the ImageAcquired event to get the image. The Acquire overload taking two Boolean parameters ( hideInterface and saveToFile ) has been deprecated. Instead, set the Device.HideInterface and Device.TransferMethod properties to control these parameters. Acquisition.ShowSelectSource will now return null (Nothing) if the dialog is canceled.

6.2.3 Inspector TWAIN

Inspector TWAIN is an application which uses DotTwain 2.0 to inspect TWAIN driver capabilities and optionally perform scan tests. An XML file containing the test result is generated in the same folder as the Inspector TWAIN application. Clicking the Submit button will send the result to Atalasoft and allow us to gather information about these scanners. This information will help us locate issues with drivers and get a feel for which scanners are most popular.

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 15

7 7.1

How To's Acquire a Select Region of the Device

Some scanners allow you to select a rectangular region of the scanning bed that you want to acquire. If you know that you only need a specific area or page size, this can greatly increase your scanning speed. This region is represented by the Frame property of the Device object. Another method is to use the ImageLayout property; in some cases a driver will only support one or the other. The Frame values are in Units , so you need to be aware of the Units property before setting the Frame size. The code examples below assume you have already opened a connection to the device by calling the Open method.

7.1.1 Acquiring a Specific Size

If you only need to specify a standard region size, you can use the FrameSize property instead. [C#] // Make sure the FrameSize property is supported by the device. if (this.device.QueryCapability(DeviceCapability.FrameSize, true) { // Get a list of supported frames and choose the one that fits your needs. StaticFrameType[] frames = this.device.GetSupportedFrameSizes(); foreach (StaticFrameType frame in frames) { if (frame == StaticFrameType.LetterUS) { this.device.FrameSize = frame; break; } } } [Visual Basic] ' Make sure the FrameSize property is supported by the device. If Me.device.QueryCapability(DeviceCapability.FrameSize,True) Then ' Get a list of supported frames and choose the one that fits your needs. Dim frames() As StaticFrameType = Me.device.GetSupportedFrameSizes() Dim frame As StaticFrameType For Each frame In frames If frame = StaticFrameType.LetterUS Then Me.device.FrameSize = frame Exit For End If Next End If

7.1.2 Acquiring any Size and Position

If you need a more control over the size and position, or if the device doesn't support the FrameSize property, you can attempt to set the acquisition area using the Frame property instead. [C#] // Try to use Inches. this.device.Units = UnitType.Inches; if (this.device.Units != UnitType.Inches) return; this.device.Frame = new System.Drawing.RectangleF(0, 0, 8.5, 11); [Visual Basic] ' Try to use Inches. Me.device.Units = UnitType.Inches

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 16

If Me.device.Units <> UnitType.Inches Then Return End If Me.device.Frame = New System.Drawing.RectangleF(0, 0, 8.5, 11)

7.2

Acquire Directly to a File

Some devices allow to you acquire an image and save it directly to a file, instead of returning the image data. While the overall process is simple, there are a few steps you have to take.

7.2.1 Checking for Device Capabilities

The first thing you should do is test the device to make sure it is capable of saving a file. If so, you then need to negotiate the type of file to save. [C#] // Open a connection to the device. this.device.Open(); this.device.TransferMethod = TwainTransferMethod.TWSX_NATIVE; // See if the device supports file transfer. TwainTransferMethod[] methods = this.device.GetSupportedTransferMethods(); foreach (TwainTransferMethod method in methods) { if (method == TwainTransferMethod.TWSX_FILE2) { // Use TWSX_FILE2 when possible. this.device.TransferMethod = method; break; } if (method == TwainTransferMethod.TWSX_FILE) this.device.TransferMethod = method; } // If it's not supported tell stop. if (this.device.TransferMethod == TwainTransferMethod.TWSX_NATIVE) { // Close the connection. this.device.Close(); MessageBox.Show("The current device does not support saving directly to a file."); return; } // Find out which file types the device can save to. SourceImageFormat[] formats = this.device.GetSupportedImageFormats(); // We want to save the image as a TIFF. foreach (SourceImageFormat format in formats) { if (format == SourceImageFormat.Tiff) { // TIFF is supported, so set the FileFormat. this.device.FileFormat = format; // Now lets try to use Group4 or Group3 compression. // We could use GetSupportedCompressionModes, but we // will simply try setting the Compression property instead. this.device.Compression = CompressionMode.Group4; if (this.device.Compression != CompressionMode.Group4) this.device.Compression = CompressionMode.Group3; break; }

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 17

} // Start the acquire process, using the device's interface. this.device.Acquire(); [Visual Basic] ' Open a connection to the device. Me.device.Open() Me.device.TransferMethod = TwainTransferMethod.TWSX_NATIVE ' See if the device supports file transfer. Dim methods() As TwainTransferMethod = Me.device.GetSupportedTransferMethods() Dim method As TwainTransferMethod For Each method In methods If method = TwainTransferMethod.TWSX_FILE2 Then ' Use TWSX_FILE2 when possible. Me.device.TransferMethod = method Exit For End If If method = TwainTransferMethod.TWSX_FILE Then Me.device.TransferMethod = method End If Next ' If it's not supported tell stop. If Me.device.TransferMethod = TwainTransferMethod.TWSX_NATIVE Then ' Close the connection. Me.device.Close() MessageBox.Show("The current device does not support saving directly to a file.") Return End If ' Find out which file types the device can save to. Dim formats() As SourceImageFormat = Me.device.GetSupportedImageFormats() ' We want to save the image as a TIFF. Dim format As SourceImageFormat For Each format In formats If format = SourceImageFormat.Tiff Then ' TIFF is supported, so set the FileFormat. Me.device.FileFormat = format ' Now lets try to use Group4 or Group3 compression. ' We could use GetSupportedCompressionModes, but we ' will simply try setting the Compression property instead. Me.device.Compression = CompressionMode.Group4 If Me.device.Compression <> CompressionMode.Group4 Then Me.device.Compression = CompressionMode.Group3 End If Exit For End If Next ' Start the acquire process, using the device's interface. Me.device.Acquire()

7.2.2 Setting Filenames

During the acquire process, the FileTransfer event will be raised just before each file is acquired. You need to set the FileName property of the FileTransferEventArgs object passed into the event. This will tell the device where the file should be saved. [C#] private void OnFileTransfer(object sender, FileTransferEventArgs e) {

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 18

e.FileName = @"C:\TwainImages\whatever.tif"; }

7.2.3 Closing the Connection

When all of the images have been acquired, the AcquireFinished event will be raised. You should close the connection here. [C#] private void OnAcquireFinished(object sender, System.EventArgs e) { this.device.Close(); }

7.3

Detecting a Camera Device

There may be times when you want to only use a camera device. Unfortunately, TWAIN doesn't provide a direct way of knowing what type of device is being used. However, you can do a little investigating to help pick out a camera from a scanner. Using the QueryCapability method, you can find out if a device supports certain features that are normally only supported by camera devices. Below is a list of capabilities you can check:
l l l l l l l l

Flash Flash2 ExposureTime BatteryMinutes BatteryPercentage CameraPreviewInterface PowerSupply ZoomFactor

7.4

Embed in Internet Explorer

This topic will demonstrates using features built into the .NET Framework to deploy Atalasoft DotTwain over the internet embedded in Internet Explorer.

7.4.1 Embedding DotTwain into Internet Explorer

DotTwain can be used from a WinForms UserControl. This is the preferred method when web deploying as it provides more functionality than using DotTwain directly from Javascript. Once the UserControl has been created ( see our TwainControl demo included in the installation for an example ), simple HTML code will cause the assembly to be downloaded and installed into the download cache of the client's system. This is similar the adding an ActiveX component to a web page. Here is an example:

<object id="Twain" classid="http://siteaddress/MyControl.dll#MyScanObject" width="100" height="100"></ob As you can see, the only real difference is the classid parameter. The first part of that parameter tells the browser where the assembly is located. If you don't use a path, the assembly is assumed to be in the same folder as the web page. This is followed by a hash ( #) symbol and the name of the class object you want to

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 19

create, which in this case is MyScanObject .

7.4.2 Security Issues

Before you can use DotTwain in Internet Explorer, your client must have setup Site permissions to allow the assembly to execute. This can be done using the Microsoft .NET Framework Configuration tool which is installed with the .NET Framework. You may also be able to create an MSI file which will do this automatically. Enterprises can setup a Group Policy to automatically set this up as users log-in to their systems. Normally, you would add a new group to the Machine - All Code section with points to your domain with Full Permission . This will grant all assemblies coming from the domain full access to the client's resources.

7.4.3 Licensing Web Deployment

The Atalasoft.DotTwain.lic file must be in the same folder on your server as the assembly. Your evaluation or normal DotTwain license will work with installations on "localhost" but not in a deployed server environment. You will have to request a special license file in order to use DotTwain on your server (one is available per purchase). This license is tied to the DNS or IP address of the deployment server. Please send your licensing request to [email protected] .

7.4.4 Debugging Assembly Issues

If you're getting an error when trying to use an assembly method, it's most likely because the assembly object wasn't created due to security issues. One thing you can do is check the exception logs created by Internet Explorer. You can find them in the Temporary Internet Files folder named "?FusionBindError! name=Atalasoft.DotTwain.dll Atalasoft.Twain.Acquisition". Drag this file to Internet Explorer to read the exception and trace log. If you use the HttpPost object, it will create it's own exception file as well.

7.5

Upload an Image to a Server

There may be times when you want to send a scanned image to a web server. The HttpPost class was written for this specific purpose.

7.5.1 Uploading the image

Below is an example which sends a single image, along with a username and password to identify the person sending the image, to a server. [C#] private void UploadImage(System.Drawing.Bitmap image) { // Create an instance of HttpPost and use the default image encoder. Atalasoft.Twain.HttpPost post = new Atalasoft.Twain.HttpPost(); // Add the image to the form data collection. post.FormData.Add("image1", image, "filename.png"); // Add data to identify the user posting the image. post.FormData.Add("username", user); post.FormData.Add("password", password); // Post the form data to the server and retrieve a return value. string ret = post.PostData(" http://www.website.com/postImage.aspx"); } [Visual Basic] Private Sub UploadImage(ByVal image As System.Drawing.Bitmap) ' Create an instance of HttpPost and use the default image encoder. Dim post As Atalasoft.Twain.HttpPost = New Atalasoft.Twain.HttpPost() ' Add the image to the form data collection. post.FormData.Add("image1", image, "filename.png") ' Add data to identify the user posting the image. post.FormData.Add("username", user)

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 20

post.FormData.Add("password", password) ' Post the form data to the server and retrieve a return value. Dim ret As String = post.PostData(" http://www.website.com/postImage.aspx") End Sub The first part of the code creates an instance of HttpPost and uses the default image format, which is PNG. The image format determines the file type of the image when saved on the server. We then add the image to the FormDataCollection , which includes the field name, image and filename for the image. It's best to think of HttpPost as an HTML FORM object. The FormData represents the FORM elements; in this case a FILE input box. You can update multiple images by simply adding more to the collection. Just be sure each has a unique field name. Next we add the username and password of the person sending this image. In may cases, you will want to send additional information along with the image in order to perform a specific action on the server. In terms of an HTML FORM, this would be a TEXTBOX field. Finally, the FormData is sent to the server using the PostData method. The return value of PostData is a string that is sent back from the server. Normally this is used to confirm the success of the call.

7.5.2 Saving the image

Once the image has been sent, we save the image to the server using ASP.NET. This code could be modified to store the image in a database instead. [C#] private void Page_Load(object sender, System.EventArgs e) { if (Request.Files.Count == 0) return; // Save the file to the server. string fileName = System.IO.Path.GetFileName(Request.Files[0].FileName); Request.Files[0].SaveAs(GetNewFileName(fileName)); // Return the path to this file. Response.Clear(); Response.Write("success"); Response.End(); } private string GetNewFileName(string fileName) { // Create a unique filename. string path = Server.MapPath("./images") + "\\" + Session.SessionID + fileName; return path; } [Visual Basic] Private Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) If Request.Files.Count = 0 Then Return End If ' Save the file to the server. Dim fileName As String = System.IO.Path.GetFileName(Request.Files(0).FileName) Request.Files(0).SaveAs(GetNewFileName(fileName)) ' Return the path to this file. Response.Clear() Response.Write("success") Response.End() End Sub Private Function GetNewFileName(ByVal fileName As String) As String ' Create a unique filename. Dim path As String = Server.MapPath("./images") + "\\" + Session.SessionID + fileName Return path

Copyright 2000 - 2006, Atalasoft, Inc.

Atalasoft DotTwain 2.1 Developer's Guide | 21

End Function In the code above, we use the SaveAs method to save the image to the server. Notice that we get the FileName property of the posted file. This is the same value that was passed to the FormData.Add method when you added the image. The data written to the Response object is what gets returned by the PostData method. It's a good idea to use the Response.Clear method before adding your return value. Here we just return "success".

Copyright 2000 - 2006, Atalasoft, Inc.