Getting Started with ImageMan.Net Twain

Transcription

1 ImageMan.Net Twain Developer Guide 1 Getting Started with ImageMan.Net Twain Version 1.0

2 ImageMan.Net Twain Developer Guide 2 Table Of Contents 1. Welcome 3 2. Using the Trial Edition 4 3. Ordering Information 5 4. Getting Started 6 5. Sample Applications 7 6. Using the Twain control Using the TwainGUI Control Using the controls in Internet Explorer Uploading Images from Client Side Applications Handling Uploaded Images on the Server Side Obtaining Support Contacting Data Techniques License Agreement 22

3 ImageMan.Net Twain Developer Guide 3 1 Welcome The ImageMan.Net Twain toolkit includes 3 fully managed.net components which provide a rich interface to TWAIN compatible devices such as scanners, digital cameras and frame grabbers. 100% Managed Controls support x-copy deployment Object oriented controls simplify development of scanner enabled applications Supports Version 1.9 of the Twain specification TwainGui control provides a Device independent customizable scanner interface Support for client-side use in Internet Explorer HTTPUpload class supports uploading images from client side applications Support for querying supported scanner capabilities Automatic Document Feeder (ADF) and Duplex scanner support Context Sensitive Online Help and Documentation Support for setting scanner capabilities Returns scanned image data as.net Image objects for compatibility with other classes Backed up by Data Techniques professional support staff

4 ImageMan.Net Twain Developer Guide 4 2 Using the Trial Edition The trial edition of the ImageMan.Net Twain toolkit is fully functional and includes controls with a 30 day trial limit and a watermark added to scanned images. After the 30 day trial period the controls will no longer instantiate and will display a trial expired dialog. At that time you may register the controls by entering your license key from our online ordering system. Upon registration, the time limit and watermark will be removed.

5 ImageMan.Net Twain Developer Guide 5 3 Ordering Information You may purchase the ImageMan.Net Twain toolkit directly from Data Techniques or from one of our many US or International resellers. Online ordering is available on the Data Techniques website and allows you to order and download the product in minutes using your Visa, MasterCard or American Express credit card. Products purchased directly from Data Techniques are covered by our 60 day money back guarantee*. The ImageMan.Net Twain toolkit is royalty free and licensed per developer. You must have a license for each developer using the toolkit. Our Team License pack includes licenses for up to 5 developers at a cost only twice that of our single user license. Each license includes royalty-free runtime distribution of the controls with Winforms applications and includes 1 server distribution license. To run your application(s) on more than 1 web server you'll need additional licenses which can be obtained from our website. *Excludes any shipping cost, applies only to product purchased directly from Data Techniques.

6 ImageMan.Net Twain Developer Guide 6 4 Getting Started 4.1 Adding the ImageMan.Net Twain controls to the Visual Studio Toolbar 1. Display the Toolbox window 2. Right click and select Add/Remove Items 3. Click the check boxes next to the TwainControl and TwainGui entries in the.net Framework Components tab. 4. Click OK. 4.2 Adding the controls to your form With the form open, you can double click on the control in the toolbar or drag the control onto your form. 4.3 Deciding which control use The ImageMan.Net Twain toolkit includes 3 components, the TwainControl encapsulates the TWAIN interface in a non visual control, the TwainGui control provides a device independent visual interface for controlling the scanner capabilities and the HttpUpload class to support uploading images from a client side application. The TwainGui control provides a visual wrapper on top of the TwainControl and exposes all its functionality as well as providing a Tree based view of the configured device settings. 4.4 Basic Scanning Sequence 1. Setup the scan parameters by setting properties such as Resolution, Duplex, etc or by calling the NegotiateCapability, GetCapability or SetCapability methods. 2. Call the ScanPage method once for each page you wish to acquire or create event handlers for the PageScanned, ScanComplete and ScanCancelled events and then use the ScanAll method to initiate scanning. 3. Call the CloseSource method to indicate you are done with the scanner.

7 ImageMan.Net Twain Developer Guide 7 5 Sample Applications Several sample applications are included in the ImageMan.Net Twain installation to help illustrate using various controls in C#, VB.Net and Internet Explorer applications. Shortcuts to the solution files are added to the Program's menu and solutions are included for Visual Studio 2002 and Visual Studio Sample csdemo csguidemo Description Illustrates using the TwainControl in a C# application as well as saving scanned images as TIFF files. Illustrates using the TwainGUI control in a C# application as well as saving scanned images as TIFF files. cscustdemo Illustrates using and customizing the TwainGUI control in a C# application. vbdemo vbguidemo Illustrates using the TwainControl in a VB.Net application as well as saving scanned images as TIFF files. Illustrates using the TwainGUI control in a VB.Net application as well as saving scanned images as TIFF files. vbcustdemo Illustrates using and customizing the TwainGUI control in a VB.Net application. ASP.Net The ImgManNet sample application is installed on systems with IIS installed and includes a sample application which illustrates using the TwainControl and HTTPUpload class in a client side Internet Explorer application along with an ASP.NET backend application which saves the uploaded images, creates thumbnails and returns them in a page after scanning. Prior to running the sample application from the provided link you must grant the local ASP_NET account WRITE access to the <installdir>\imgmannet\imgs directory so the sample can write the uploaded image files.

8 ImageMan.Net Twain Developer Guide 8 6 Using the Twain control 6.1 Specifying the Scan parameters The TwainControl includes properties that can be used to set common attributes such as the PixelType, Resolution, Duplex, and more. In addition to this high level support, the control also provides access to the complete set of Twain capabilties which a device can implement using the NegotiateCapability, GetCapability and SetCapability methods. Setting of Properties or capability negotiation should be done prior to calling the ScanPage or ScanAll methods. When using the ScanPage method properties and capabilties can also be set and/or queried between calls to ScanPage. 6.2 If you set properties but do not call ScanPage or ScanAll then you still must call CloseSource afterward to indicate your application is finished with the Twain device. Failure to do so will cause the device to be unavailable to other applications. Scanning without Events To scan a page use the ScanPage method which will initiate a scan and return an Image object. After calling ScanPage you should call the CloseSource method to tell the control you are done with the current device. Not calling this method will mean other applications will not be able to use the scanner until the control is destroyed. [C#] System.Drawing.Image img = twaincontrol1.scanpage(); twaincontrol1.closesource(); [Visual Basic] Dim img As Image = twaincontrol1.scanpage() twaincontrol1.closesource() The ScanPage method can be called multiple times to get all the documents in an ADF for instance. When no pages remain to be scanned the method will return null. [C#] System.Drawing.Image img; img = twaincontrol1.scanpage(); while( img!= null ) { // Save the img img = twaincontrol1.scanpage(); twaincontrol1.closesource(); [Visual Basic] Dim img As Image img = twaincontrol1.scanpage() While Not (img is Nothing) ' Save the image img = twaincontrol1.scanpage() End While twaincontrol1.closesource() 6.3 Scanning with Events

9 ImageMan.Net Twain Developer Guide 9 The ScanAll method scans up to the number of pages specified by the MaxPages property and fires the PageScanned event for each page obtained. When no pages remain to be scanned the control will fire the ScanComplete event. In the event the user clicks the scanner's Cancel button the control will fire the ScanCanceled event. [C#] // Scan up to 999 pages twain.maxpages = 999; twain.scanall(); // Our event handlers private void twain_scancomplete(object sender, EventArgs e) { Console.WriteLine( "ScanComplete Fired"); private void twain_scancanceled(object sender, EventArgs e) { Console.WriteLine( "ScanCanceled Fired"); private void twain_pagescanned(object sender, PageScannedEventArgs e) { Console.WriteLine( "PageScanned Fired"); [Visual Basic] Friend WithEvents twain As DTI.ImageMan.Twain.TwainControl twain.maxpages = 999 twain.scanall() Private Sub twain_pagescanned(byval sender As Object, ByVal e As DTI.ImageMan.Twain.PageScannedEventArgs) Handles twain.pagescanned ' e.scanimage contains the scanned image End Sub Private Sub twain_scancanceled(byval sender As Object, ByVal e As System.EventArgs) Handles twain.scancanceled End Sub Private Sub twain_scancomplete(byval sender As Object, ByVal e As System.EventArgs) Handles twain.scancomplete End Sub 6.4 Displaying the Select Scanner Dialog Calling the SelectScanner method will display the Twain Select scanner dialog to allow the user to specify the default scanner. The CurrentSource property will contain an Identity object which describes the default scanner selected by the user. [C#] twaincontrol1.selectscanner();

10 ImageMan.Net Twain Developer Guide 10 [Visual Basic] twaincontrol1.selectscanner() 6.5 Programmatically selecting a Scanner In addition to displaying the Select Scanner dialog, a scanner can be selected programmatically using the CurrentSource property. Setting this property to one of the Identity objects returned from the Sources property will set the default scanner to that device. The Sources property returns a collection of Identity objects which describe each Twain device found on the system. [C#] foreach( Identity id in twaincontrol1.sources ) { // Add the name of the scanner to our listbox lstbox.add( id.productname ); [Visual Basic] Dim id As Identity For Each id In TwainControl1.Sources Console.WriteLine(id.ProductName) Next

11 ImageMan.Net Twain Developer Guide 11 7 Using the TwainGUI Control The TwainGui control provides a customizable tree view based control that supports displaying and changing the configured Twain capabilities. The control is built upon the base Twain control and exposes an instance as a property which can be used to further customize applications. 7.1 Configuring the control's Appearance By default, no options are displayed in the TwainGui control, you can add specific options using the Add method of the Options collection or using the LoadOptions method to load a default set or to load options from a previously saved options file. When adding options to the tree view you can specify the Capability to be added, which category it will appear under, how the capability should be handled and also an initial value. The text which appears at the root of the tree can be configured using the control's Text property. Adding items using the Options collection The desired capabilities can be added to the tree view by creating an Option object and then adding it to the Options collection. There are several constructors for the Option object which simplify creating options. The simplest constructor requires only the Capability to be added and will add it to a default category. There is also a constructor which allows you to specify the capability and the category into which the capability should be added. Additional constructors allow you to specify the default value for the capability and also how the capability should be handled. [C#]

12 ImageMan.Net Twain Developer Guide 12 TwainGui1.Options.Add(new Option(Capabilities.Orientation, Option.Categories.Paper)); [Visual Basic] TwainGui1.Options.Add(new Option(Capabilities.Orientation, Option.Categories.Paper)) Using LoadOptions The LoadOptions method can be used to load either a default set of options or to load an options file which has been created by calling the SaveOptions method. [C#] // Load the default set of options TwainGui1.LoadOptions(); // Load previously saved options TwainGui1.LoadOptions("MyOptions.bin"); [Visual Basic] ' Load the default set of options TwainGui1.LoadOptions() ' Load a previously saved set of options TwainGui1.LoadOptions( "MyOptions.bin" ) 7.2 Scanning with the Control The TwainGui control includes a TwainControl instance which can be referenced via the Twain property. Use the TwainControl methods and properties exposed by this property to scan or acquire images. Prior to calling the ScanPage or ScanAll methods, the LoadCapabilities method should be called to initialize the TwainControl with the options the user has selected in the tree view. [C#] // Initialize the TwainControl with the settings from the tree view TwainGui1.LoadCapabilities(); // Start our scan img = TwainGui1.Twain.ScanPage(); TwainGui1.Twain.CloseSource(); [Visual Basic] ' Initialize the TwainControl with the settings from the tree view TwainGui1.LoadCapabilities() // Start our scan img = TwainGui1.Twain.ScanPage() TwainGui1.Twain.CloseSource()

13 ImageMan.Net Twain Developer Guide SourceChanging Event and Saving Selected Options The SourceChanging event is fired when the user selects a new Scanner from the tree view and can be used to save the options for the current scanner and load any options for the newly selected scanner. The current options and values can be saved to a file using the SaveOptions method. [C#] private void TwainGui1_SourceChanging(object sender, DTI.ImageMan.Twain.SourceChangingEventArgs e) { string oldsourcefile; string newsourcefile; oldsourcefile = System.AppDomain.CurrentDomain.BaseDirectory + TwainGui1.Twain.CurrentSource.ProductName + ".bin"; newsourcefile = System.AppDomain.CurrentDomain.BaseDirectory + e.source.productname + ".bin"; // Save the options for the currently selected scanner TwainGui1.SaveOptions(oldsourcefile); // just in case file isn't available select current source so defaults // are initialized correctly. TwainGui1.Twain.CurrentSource = e.source; if (!(TwainGui1.LoadOptions(newsourcefile))) TwainGui1.LoadOptions(); e.handled = true; [Visual Basic] Private Sub TwainGui1_SourceChanging(ByVal sender As Object, ByVal e As DTI.ImageMan.Twain.SourceChangingEventArgs) Handles TwainGui1.SourceChanging Dim oldsourcefile As String Dim newsourcefile As String oldsourcefile = System.AppDomain.CurrentDomain.BaseDirectory() & TwainGui1.Twain.CurrentSource.ProductName & ".bin" newsourcefile = System.AppDomain.CurrentDomain.BaseDirectory() & e.source.productname & ".bin" ' TwainGui1.SaveOptions(oldsourcefile) ' just in case file isn't available select current source so defaults ' are initialized correctly. TwainGui1.Twain.CurrentSource = e.source If (TwainGui1.LoadOptions(newsourcefile) = False) Then TwainGui1.LoadOptions() End If e.handled = True End Sub

14 ImageMan.Net Twain Developer Guide 14 8 Using the controls in Internet Explorer In addition to being used in Windows Forms applications the Twain controls can be hosted in Internet Explorer based web applications. By utlizing the automatic download support in Internet Explorer its possible to run aplications on the client machine without having to install the software manually. In addition to the Twain and TwainGui controls the ImageMan.Net Twain product includes an HttpUpload class which can be used to upload the scanned images to a server side application. A complete sample application which illustrates using the controls and uploading scanned images to an ASP.Net server application is included in the ImageMan.Net Twain installation. A shortcut to the application is installed in your program's menu. 8.1 Client Side Requirements Internet Explorer Version 6.0 or greater.net Framework V Security settings on the client to allow the assembly to be loaded and executed 8.2 Instantiating the Controls The controls are instantiated in an HTML page using the <object...> tag and then manipulated using either VB.Script or Javascript in the html page. The tag to instantiate the Twain and HttpUpload controls looks like: <object id="twain" height=1 width=1 classid="dti.imageman.twain.dll#dti.imageman.twain.twaincontrol"></object> <object id="up" height=1 width=1 classid="dti.imageman.twain.dll#dti.imageman.twain.httpupload"></object> The id parameter specifies the name used to reference the object in your client-side javascript or vb.script code. The classid specifies the name of the assembly to use, a "#" character and then the fully qualified name of the class to be created. If the assembly name doesn't include a path it will be assumed to be located in the same directory as the page. 8.3 Using the controls from client side script As events aren't supported in the client script technologies the ScanPage method must be used for scanning. With the exception of the Scan method all the other properties and methods are available to your application. Internet Explorer doesnt display any error messages if a users security settings havent been updated to allow the Imageman.Net Twain control to be loaded so its important to check the validity of the references to the object so your code can gracefully handle that situation and perhaps provide the user with information on properly configuring their system. The code below displays an alert if the objects haven't been created: if( up.items == null twain.maxpages == null ) alert("your.net Framework Security settings must be configured to run the components in your browser."); Once you have determined the objects are instantiated you can use the TwainControl or TwainGui controls to initiate scanner selection and scanning.

15 ImageMan.Net Twain Developer Guide 15 The code below will scan all the pages in the scanner and then upload them to the specified URL: function Scan() { var img; if(!checkforcontrols() ) return; up.items.clear(); twain.maxpages = -1; img = twain.scanpage(); while( img!= null ) { // Keep scanning pages and adding them to the upload list until there are no more to scan up.items.addimage( img ); img = twain.scanpage(); if( up.items.count > 0 ) { window.status = 'Uploading Images...'; var buplok = up.post( up.items.clear(); window.status = 'Images Uploaded...'; if( buplok ) // If the server processed the images then display its response in the specified DIV tag document.getelementbyid('res').innerhtml = up.response; else alert( up.lasterror ); twain.closesource(); 8.4 Modifying the client.net Framework Security settings By default the.net Framework security configuration will not allow the controls to be instantiated in Internet Explorer. The Site Policy can be updated automatically using an MSI file that the client must run or it can be manually updated using the following steps. 1. Open the.net Framework Configuration tool which is located in the Control Panel/Administrative Tools folder. 2. Select the Runtime Security Policy/Machine/Code Groups/All_Code options 3. Right click on the All_Code item and select New Enter a Name and Description for this Policy ie ImageMan.Net Controls 5. Select Site from the Code Group dropdown list 6. Enter the name of the site containing the controls ie the site where you application will be running from. 7. Select Use Existing Permission Set and Full Trust. 8. Click Finish and the Policy will be created. For additional information on creating an MSI file for to configure a site Policy see

16 ImageMan.Net Twain Developer Guide 16 on the MSDN website. 8.5 Licensing for Web Applications The ImageMan.Net Twain controls includes a royalty free runtime distribution when distributed with desktop applications. For web based applications a deployment license is required for each server on which the application will be run. The server deployment license file must be named dti.imageman.twain.dll.lic and be located in the same directory as the ImageMan.Net Twain assembly. If the license file isnt located the client applications will run in trial mode which will include a trial watermark in each scanned image. For additional information or to purchase a deployment license please contact our sales department at or or via at sales@data-tech.com.

17 ImageMan.Net Twain Developer Guide 17 9 Uploading Images from Client Side Applications 9.1 Uploading Images to the Server The HttpUpload class is used to upload images from the client side application to a url on a server. The image data is PNG compressed and uploaded to the server as Multi-Part mime encoded data allowing it to be easily handled by the serverside application. In ASP.Net applications, the uploaded files can be accessed using the HttpRequest.Files collection and saved to a local drive for further processing. 9.2 Client-side Code The HttpUpload class provides a simple way to upload scanned images and other form data to a remote server. After each image is scanned it can be added to the list of images to be uploaded by calling the Items.AddImage method. Two versions of the AddImage method are available, the first takes an image object and automatically compresses the image as a PNG image and gives it a default name when uploaded, the 2nd overload allows you to name the image object in the upload and also specify the filename associated with the image when it's uploaded. The Items collection of UploadItems objects is used to keep a list of the images and form fields to be uploaded when the Post method is called. The following javascript code could easily be attached to a button handler and scans each page in the scanner, adds the image to the upload list and when all the images have been scanned will upload the images to the server. The response from the server application is then displayed in a DIV element otherwise the Error information is displayed in an alert. <object id="twain" height=1 width=1 classid="dti.imageman.twain.dll#dti.imageman.twain.twaincontrol"></object> <object id="up" height=1 width=1 classid="dti.imageman.twain.dll#dti.imageman.twain.httpupload"></object>... function Scan() { var img; if(!checkforcontrols() ) return; up.items.clear(); twain.maxpages = -1; img = twain.scanpage(); while( img!= null ) { up.items.addimage( img ); img = twain.scanpage(); if( up.items.count > 0 ) { window.status = 'Uploading Images...'; var buplok = up.post( up.items.clear(); window.status = 'Images Uploaded...';

18 ImageMan.Net Twain Developer Guide 18 if( buplok ) document.getelementbyid('res').innerhtml = up.response; else alert( up.lasterror ); twain.closesource(); Form data can also be uploaded along with the Image data using the AddFormField method. This allows the client-side application to include other application specific data with the uploaded image data.

19 ImageMan.Net Twain Developer Guide Handling Uploaded Images on the Server Side 10.1 Using ASP.Net to handle uploaded files The HttpUpload class uploads the image data as Multi-Part Mime encoded data which can be accessed using the HttpRequest.Files collection in the serverside application. The following code could be located in the Page_Load event and saves each uploaded image to a local file. foreach( string file in Request.Files ) { HttpPostedFile f = Request.Files[ file ]; // Create a unique local filename using the current tickcount string filename = DateTime.Now.Ticks.ToString() + ".png"; //Save the image in the specified directory f.saveas( ConfigurationSettings.AppSettings["ImageDir"] + filename ); By default, the ASP.Net limits the maximum size of uploaded files to 4096K. This can be overridden by setting the maxrequestlength property in your web.config file and specifying a larger value. Add: <httpruntime maxrequestlength="128000" /> under the line <system.web> in your application's web.config file. The maxrequestlength property specifies the maximum size in kilobytes..

20 ImageMan.Net Twain Developer Guide Obtaining Support The ImageMan.Net Twain toolkit includes 60 days of free phone and support from the time of the first call. After that period several plans are available depending on the level of support required. Visit our Online Support Center for additional information on the available plans Contacting Support Phone You may call our support engineers at between the hours of 9-5 EST (GMT-5). You can your questions to us at Online You can post your questions on our website's support forums at When contacting support please be sure to include your serial number, development environment and as many details about the issue as possible. Doing so will help us to resolve your issue in the fastest manner possible.

21 ImageMan.Net Twain Developer Guide Contacting Data Techniques Data Techniques, Inc. 58 Blue Ridge Lane Burnsville, NC Sales Phone: or Fax: Technical Support Phone:

22 ImageMan.Net Twain Developer Guide License Agreement ImageMan.Net Twain LICENSE AGREEMENT 1. IMPORTANT NOTICE This is a legal agreement between Data Techniques and you, the licensee. 2. ON ONE COMPUTER Data Techniques licenses this product for use on a single CPU only. You must obtain a licensed copy (or special license) for each programmer or workstation on a network on which the product is used, whether in source or object format. 3. LICENSE TO REPRODUCE, USE AND DISTRIBUTE You may distribute only the ImageMan.Net files listed as Redistributable in the Online Help and Documentation with your end-user applications. You may not distribute any ImageMan.Net files not listed as Redistributable. You may distribute an unlimited number of copies of the controls with your Windows Forms applications with no royalties. Applications which run on Web Servers require a server license. One server license is included with each developer license, additional licenses can be purchased from Data Techniques. You may only use the ImageMan.Net software in end-user software that does not provide the end-user any development capability or ability to further redistribute the licensed code. You also may not use the ImageMan.Net code in a product which is competitive with the ImageMan.Net product including but not limited to a developer toolkit or similar product. 4. OWNERSHIP, COPYRIGHT AND TRANSFER All copies of ImageMan.Net are owned by Data Techniques, Inc. or its suppliers and are protected by United States copyright laws and international treaty provisions. You must treat Data Techniques, Inc. software products as any other copyrighted material (e.g., book or musical recording), except that you may make a reasonable number of backups for archival purposes, provided that you have only one working copy at a time for each copy of the product licensed to you. You may not transfer, sublicense, rent, lease or assign any of the above license or any Data Techniques, Inc. software. 5. TERM AND TERMINATION You may terminate the above license at any time by returning or destroying all copies of ImageMan.Net in your possession and notifying Data Techniques, Inc. The above license will terminate immediately if you infringe upon Data Techniques, Inc. s copyrights or breach this agreement. 6. LIMITED WARRANTY Data Techniques provides a 60-day money-back guarantee for the ImageMan.Net product. You may return the version of ImageMan.Net at any time within 60 days of the date of purchase for any reason whatsoever by calling Data Techniques, Inc. and obtaining a return authorization number (RMA). Under no circumstances will Data Techniques, Inc. accept a returned product without an RMA, or a package in which the source diskette envelope has been opened. 7. NO LIABILITY FOR CONSEQUENTIAL DAMAGES IN NO EVENT SHALL DATA TECHNIQUES, INC. OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER STEMMING FROM THE USE OR MISUSE OF THIS PRODUCT, EVEN IF DATA TECHNIQUES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.