Version 2.0 Overview

Version 2.0 uses the following C++ coding paradigms:

Therefore a compiler that supports these C++ features could be used for Version 2.0 of the DTWAIN C++ classes.  It is best that the compiler supports all of the above, however namespace support is optional (as discussed in the initial setup).  However what is not optional is that your compiler must support the std::string and std::vector classes, and templates.  Usually any compiler with modest support for templates and STL will compile the DTWAIN C++ classes with no problems.

Tested compilers have been:

Visual C++ 6.0, 7.x, 8.0 (Visual Studio 2005)

Borland C++ Builder 5.0, 6.0

Metrowerks CodeWarrior 7.0, 8.0

g++ version 3.x, 4.x (Bloodshed Dev-C++, MingW, etc.)

Digital Mars 8.3x (Must use STLPort 4.5.3)

Compilers that should work (since namespaces, STL, and templates are supported) but have not been tested are:

IBM VisualAge 8.0

Intel C++ compiler

Comeau C++

To use the classes successfully, you must have knowledge of usage of the standard C++ string class (std::string), and some usage of the STL std::vector class.   Usage of these classes eliminate (or greatly reduce) the reliance on the usage of pointers and dynamically allocated memory to communicate with the DTWAIN classes.  Memory allocation and cleanup is automatically done by these classes, which greatly reduces the chance of any memory-related bugs.

If you are not familiar with std::vector or std::string, a look at the example programs in the Examples section of this manual, along with references in almost any C++ book or tutorial.

Usage of std::string to store image data

The DTWAIN C++ classes use the std::string to store the acquired image data whenever an "advanced memory buffer transfer" is invoked (see Example 7).  The std::string class, despite its name, is fully capable of storing binary data, including data that has embedded null bytes.  To retrieve the image data from a std::string type, you should use the std::string::data( ) or std::string::c_str( ) function.  To retrieve the length of the image data, use std::string::size( ) or std::string::length( ).

Note that since the data is binary data, and null bytes may be present in the image data, you cannot use the traditional 'C' functions such as strcpy( ) to manipulate the image data, since these functions only work for null-terminated strings.  If you are not familiar with std::string, it is the standard C++ string class, and all the compilers mentioned above support this type.

The DTwainStringArray, DTwainDoubleArray, DTwainLongArray, and DTwainFrameArray are STL vector classes, therefore they are fully compatible with the std::vector interface (for example, std::sort( ), std::find( ), push_back( ), size( ), resize( ), etc. can be used on these types).

Version 2.0 of the C++ interface is also fully compatible with usage of the DYDTWAIN code.  The DYDTWAIN code allows programmers to use run-time linkage to the DTWAIN DLL using LoadLibrary( ) instead of linking to DTWAIN32.LIB.  Also, the library is fully compatible with the DTWAIN static libraries.  The DYDTWAIN code can be found in the DYDTWAIN directory of your DTWAIN installation.

Function call chaining:

Note that many of the classes in the DTWAIN C++ interface have member functions that return a reference to the current object.  This allows an application to optionally use function chaining to initialize and set various attributes of the object.  Function chaining allows you to specify various options using the member functions of the object, where all the functions are "chained" together using the C++ '.' operator.

Below is an example using the DTwainAcquirer object:

DTwainSource Source;

// Assume Source has been initialized correctly

//..

DTwainAcquirer Acq( Source ).

                      SetUIMode( false ).

                      SetColorType( COLORTYPE_BW ).

                      SetMaxPages( DTWAIN_ACQUIREALL ).

                      SetMultiPageFileMode(true).

                      Acquire( "TEST.TIF", FILETYPE_TIFFG3 );

The code above does the following:

Note that the Acquire( ) function is last in the function chain.  This indicates that the last process that will occur is the call to Acquire( ), effectively starting the acquisition process.

Function chaining is completely optional.  You can achieve the same results using the traditional C++ method of calling the functions individually:

DTwainAcquirer Acq( Source );

Acq.SetUIMode( false );

Acq.SetColorType( COLORTYPE_BW );

Acq.SetMaxPages( DTWAIN_ACQUIREALL );

Acq.SetMultiPageFileMode(true);

Acq.Acquire( "TEST.TIF", FILETYPE_TIFFG3 );