How to Start using DTWAIN

DTWAIN has so many functions, where do I start?

There are two paths that you can take to start using DTWAIN.

Path 1: Using the low-level DTWAIN API functions

The first path is to start using DTWAIN is to try a very simple example using the low-level API functions.   Even though the functions are low-level, you just need a few calls to get a workable TWAIN-enabled program up and running.

Once you are comfortable with an easy example, you can progress to the other aspects of DTWAIN such as setting device capabilities, setting the contrast/brightness/resolution, define the area of acquisition, using the document feeder, and other aspects that the simple example doesn't address.

DTWAIN Detailed Information describes all of the "advanced" topics.

The following illustrates a very simple example of a function that acquires a single page to a BMP file.

C/C++ Example

Visual Basic Example

Visual Basic .NET Example

Borland Delphi Example

C# Example

XBase++ Example

Perl Example

Python Example

Macro Scheduler Example

WinBatch Example

Note that if your language is not one of the ones listed above, DTWAIN will still work for you if the language that you're using has the ability to call exported DLL functions.  Most Microsoft Windows-based languages have the ability to do this.  Please consult your programmer's manual for more information.

Note that the example is very simple in terms of function calls (acquiring a single page to a BMP file), and should be enough to get you started.  However, in the simple example, there is a lot of power in those few function calls.  The difference in the amount of programming code and time to implement the simple example and what you would have to write if not using DTWAIN, is enormous.

The example just scratches the surface of what DTWAIN can do.  For example, if you want to acquire to a multipage TIFF file, no problem.  Just use the example program and change the file type to one of the multipage TIFF types (for example DTWAIN_TIFFLZWMULTI), change the number of pages to acquire to DTWAIN_ACQUIREALL instead of 1, and that's it.

If you wanted to acquire an image so that you can use the image data for some purpose (maybe you have your own imaging library), just change the call from DTWAIN_AcquireFile to DTWAIN_AcquireNative or DTWAIN_AcquireBuffered, for example, and you can then process the raw image data in the form of a memory block of information.  If you want to acquire the image to the Windows clipboard, you have DTWAIN_AcquireToClipboard (there are more acquisition functions to choose from that will surely fit your needs).

Of course you can set various aspects of the TWAIN device such as resolution, contrast, brightness, and any capability supported by the TWAIN device.

Note that in the simple sample program there is no check for error return values.  This is done for brevity, however your application should check for potential error return values from the DTWAIN functions.

For more advanced examples, the DTWAIN installation contains samples of more advanced DTWAIN processing.  Also see DTWAIN Advanced Topics for a thorough rundown and explanation of each of the aspects of using DTWAIN to its fullest potential.

Path 2: Using a command string (Use TwainSave technology)

 
The second path is to use the DTWAIN_TwainSave function.  This function is called using a single parameter -- a string that denotes the commands to use to acquire images and save the images to files.

The DTWAIN_TwainSave  function mimics what the standalone product from DynaRithmic Software, TwainSave, does, only that you now can do what TwainSave does with a function call.  DTWAIN_TwainSave allows you to open any TWAIN device, start acquiring images, and save these images to files.

Which path should I choose?

The choice of whether you should use the base API functions, or the DTWAIN_TwainSave command options depends on what type of TWAIN image processing you will be doing.

If you merely want to select a TWAIN device, and save the acquired bitmaps to a file, it is highly recommended to use the DTWAIN_TwainSave, since it is very easy to use, and it only takes one function call to start the entire process of TWAIN device selection, image acquisition, and saving the images to a file.  There are many options that DTWAIN_TwainSave offers, such as job control, paper sizing, etc.  A list of all of the options are found in the DTWAIN_TwainSave command overview.

If you desire more control of the device, for example:

(The list above is not an exhaustive list as the low-level DTWAIN API can do practically anything that is allowed by the current TWAIN specification 1.9)

then it is recommended you use the base DTWAIN API functions defined above in Path 1.

Also, please note that whatever DTWAIN_TwainSave can do, the low-level DTWAIN API functions can also do, with the exception that it requires a more coding to achieve what DTWAIN_TwainSave can do using the base API.