Getting Started with ImageMan.Net Twain - ComponentSource · 2017. 2. 19. · 4 Getting Started ImageMan.Net Twain Developer Guide | 6. Several sample applications are included in

Getting Started with ImageMan.Net TwainVersion 1.0

ImageMan.Net Twain Developer Guide | 1

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 8-10

7. Using the TwainGUI Control 11-13

8. Using the controls in Internet Explorer 14-16

9. Uploading Images from Client Side Applications 17-18

10. Handling Uploaded Images on the Server Side 19

11. Obtaining Support 20

12. Contacting Data Techniques 21

13. License Agreement 22


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.

n 100% Managed Controls support x-copy deployment

n Object oriented controls simplify development of scanner enabled applications

n Supports Version 1.9 of the Twain specification

n TwainGui control provides a Device independent customizable scanner interface

n Support for client-side use in Internet Explorer

n HTTPUpload class supports uploading images from client side applications

n Support for querying supported scanner capabilities

n Automatic Document Feeder (ADF) and Duplex scanner support

n Context Sensitive Online Help and Documentation

n Support for setting scanner capabilities

n Returns scanned image data as .NET Image objects for compatibility with other classes

n Backed up by Data Techniques professional support staff

1 Welcome


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.

2 Using the Trial Edition


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*.

*Excludes any shipping cost, applies only to product purchased directly from Data Techniques.

3 Ordering Information

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.


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.

4 Getting Started


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 2003.

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.

5 Sample Applications

Sample Description

csDemoIllustrates using the TwainControl in a C# application as well as saving scanned images as TIFF files.

csGuiDemoIllustrates 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.

vbDemoIllustrates using the TwainControl in a VB.Net application as well as saving scanned images as TIFF files.

vbGuiDemoIllustrates 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.

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.


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 ScanAllmethods. When using the ScanPage method properties and capabilties can also be set and/or queried between calls to ScanPage.

6.2

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

6 Using the Twain control

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.


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 pagestwain.MaxPages = 999;twain.ScanAll(); // Our event handlersprivate 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 = 999twain.ScanAll()

Private Sub twain_PageScanned(ByVal sender As Object, ByVal e As DTI.ImageMan.Twain.PageScannedEventArgs) Handles twain.PageScanned

' e.ScanImage contains the scanned imageEnd Sub Private Sub twain_ScanCanceled(ByVal sender As Object, ByVal e As System.EventArgs) Handles twain.ScanCanceledEnd Sub Private Sub twain_ScanComplete(ByVal sender As Object, ByVal e As System.EventArgs) Handles twain.ScanCompleteEnd 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();


[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 listboxlstBox.Add( id.ProductName );

} [Visual Basic]Dim id As IdentityFor Each id In TwainControl1.Sources

Console.WriteLine(id.ProductName)Next


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 Addmethod 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#]

7 Using the TwainGUI Control


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 optionsTwainGui1.LoadOptions(); // Load previously saved optionsTwainGui1.LoadOptions("MyOptions.bin"); [Visual Basic]' Load the default set of optionsTwainGui1.LoadOptions() ' Load a previously saved set of optionsTwainGui1.LoadOptions( "MyOptions.bin" )

7.2 Scanning with the Control

The TwainGui control includes a TwainControl instance which can be referenced via the Twainproperty. 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 viewTwainGui1.LoadCapabilities(); // Start our scanimg = TwainGui1.Twain.ScanPage();TwainGui1.Twain.CloseSource(); [Visual Basic]' Initialize the TwainControl with the settings from the tree viewTwainGui1.LoadCapabilities() // Start our scanimg = TwainGui1.Twain.ScanPage()TwainGui1.Twain.CloseSource()


7.3 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 scannerTwainGui1.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 StringDim newsourcefile As Stringoldsourcefile = 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.SourceIf (TwainGui1.LoadOptions(newsourcefile) = False) Then

TwainGui1.LoadOptions()End Ife.Handled = True

End Sub


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

l Internet Explorer Version 6.0 or greater

l .Net Framework V 1.0 +

l 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.

8 Using the controls in Internet Explorer


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 scanup.Items.AddImage( img ); img = twain.ScanPage();

}

if( up.Items.Count > 0 ) { window.status = 'Uploading Images...'; var bUplOk = up.Post(http://www.myserver.com/nettwain/testup.aspx); up.Items.Clear(); window.status = 'Images Uploaded...'; if( bUplOk ) // If the server processed the images then display its response in the

specified DIV tagdocument.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...

4. 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


http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconGeneralSecurityPolicyAdministration.asp 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 800-955-8015 or 828-682-4111 or via email at [email protected].


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(http://www.data-tech.com/nettwain/scanup.aspx); up.Items.Clear(); window.status = 'Images Uploaded...';

9 Uploading Images from Client Side Applications


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.


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 tickcountstring fileName = DateTime.Now.Ticks.ToString() + ".png";//Save the image in the specified directoryf.SaveAs( ConfigurationSettings.AppSettings["ImageDir"] + @"\" + fileName );

}

10 Handling Uploaded Images on the Server Side

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. .


The ImageMan.Net Twain toolkit includes 60 days of free phone and email 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.

11.1 Contacting Support

Phone

You may call our support engineers at 828-682-0161 between the hours of 9-5 EST (GMT-5).

Email

You can email your questions to us at [email protected]

Online

You can post your questions on our website's support forums at http://www.data-tech.com/forums.

11 Obtaining Support

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.


Data Techniques, Inc.

58 Blue Ridge Lane

Burnsville, NC 28714

Sales

Phone: 800-955-8015 or 828-682-4111

Fax: 828-682-0025

Email: [email protected]

Technical Support

Phone: 828-682-0161

Email: [email protected]

12 Contacting Data Techniques


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.

13 License Agreement


Documents

Getting Started with ImageMan.Net Twain - ComponentSource · 2017. 2. 19. · 4 Getting Started ImageMan.Net Twain Developer Guide | 6. Several sample applications are included in