Initial Setup

Step 1 is very important.  You will not successfully compile any modules that use the DTWAIN classes if step 1 is not followed.

1) Namespaces

The namespace is C++'s way of separating names into separate "blocks" so that there are no naming conflicts with your own variable names. By default, all of the DTWAIN C++ interface functions, classes, and constants are defined in the DTWAIN namespace.  For example, to declare a DTwainAppInfo object:

#include "cdtwain.h"

using namespace DTWAIN;

DTwainAppInfo AppInfo;

OR

#include "cdtwain.h"

DTWAIN::DTwainAppInfo AppInfo;

OR

#include "cdtwain.h"

using DTWAIN::DTwainAppInfo;

DTwainAppInfo AppInfo;

If you get strange compiler errors on any definition of a DTWAIN C++ function or class, always look to see if you have informed the compiler you are using the DTWAIN namespace.

If there is a chance that you have an application that has already defined the DTWAIN namespace for your own purposes (very rare), then you will need to change the source to CDTWAIN.H to use a different namespace.

Also available is the ability to turn off the namespace when compiling.  To do this, the DTWAIN_NO_NAMESPACE preprocessor constant should be defined.  Note that this should be done only if the compiler does not support namespaces.  This documentation assumes you are using the DTWAIN namespace.

2) Set the "typename" flag.

The C++ language requires that declarations within templates that use use typenames be preceeded with the typename qualifier.  For example, iterators that are declared in templates must use the typename qualifier.

Example:

#include <vector>

template <class T>

class foo

{

   std::vector<int>::iterator m_iter;  // Error

};

The code above will give an error for an ANSI compliant C++ compiler.  The reason being that the compiler believes that "iterator" is a static member of std::vector, when it isn't.  The compiler then sees "m_iter" and emits an error.  The way to tell the compiler that "iterator" is a typename and not a static member variable is to use the typename qualifer:

Example:

#include <vector>

template <class T>

class foo

{

  typename std::vector<int>::iterator m_iter;  // OK

};

By default, the C++ classes assume that the typename qualifier is available.  However, there are some compilers that are not ANSI standard enough to recognize the typename qualifier.  If when you compile the DTWAIN C++ classes, you get an error that "typename" is invalid, or you get some sort of a "parse error" when compiling, you can turn off the typename by specifying DTWAIN_NO_TYPENAME.

3) include the "cdtwain.h" file in any source module where you will be calling the DTWAIN C++ routines.

4) Very important!!! Your application must include the following CPP files:

BUFTRANS.CPP

CDTWAIN.CPP

CACQUIRE.CPP

CEXTINFO.CPP

If these files are not part of the project, you will in all likelihood get linker errors.

The header files that are in the C++ DTWAIN interface are as follows:

CDTWAIN.H

CDTENUM.H

CAPINT.INL

CAPSTR.INL

CAPFRM.INL

CAPSALL.INL

Also. the TWAIN.H header file must also be available (this is one of the files in the DTWAIN installation's INCLUDE directory), plus the stock DTWAIN header files should also be available (DTWAIN.H, DTWAINC.H, DTWAINX.H, etc and supporting files that come with the base version of DTWAIN).  The

5) If using the DYNDTWAIN classes please read:

If you are using the DYNDTWAIN interface (which allows DTWAIN32.DLL or DTWAIN64.DLL to be loaded at run-time using LoadLibrary), you must define the pre-processor constant DTWAIN_USEDYNDTWAIN before building your application.  You should define DTWAIN_USEDYNDTWAIN as a preprocessor symbol in your project settings, or on the command-line (usually the option is the -D compile option).  Please consult your compiler's help documentation for this matter.

By default, DTWAIN_USEDYNDTWAIN is not defined, therefore the application will assume that the import library DTWAIN32.LIB (or some other import library that has the DTWAIN definitions defined) will be linked into your application or your application is linking to the DTWAIN static libraries (not the import libraries).  See the main DTWAIN help manual for usage of the DYNDTWAIN interface to DTWAIN, as well as the usage of the DTWAIN static libraries.

If you do define DTWAIN_USEDYNDTWAIN, you must also have as part of your project, the file DTWIMPL.CPP.  Without this file, you will get linker errors when building the application.  For the DTWAIN 2.0 C++ classes, to use DYNDTWAIN only requires you to define the DTWAIN_USEDYNDTWAIN constant.  There is no need to explicitly call LoadLibrary, InitDTWAINInterface, FreeLibrary, etc as in the usual manner described in the Dynamically Loading DTWAIN DLL at runtime section.  All of these details are taken care of by the DTWAIN C++ classes.

Do not define DTWAIN_USEDYNDTWAIN if you are linking to the DTWAIN static libraries -- there is no DTWAIN32.DLL when using the static libraries, so usage of DYNDTWAIN is not possible.

Summary

So to summarize, a typical C++ application that uses the DTWAIN C++ classes will have the following source files included:

YourFile1.cpp

YourFile2.cpp

// some more user files

//...

CDTwain.cpp

CAcquire.cpp

CExtInfo.cpp

Buftrans.cpp

a) The YourFile1.cpp and YourFile2.cpp are dummy names to represent your own C++ source files that are not part of DTWAIN.

b) If you define the symbol DTWAIN_USEDYNDTWAIN, then you must also include the file DTWIMPL.CPP in your project.

c) The names of the DTWAIN C++ functions, classes, and constants are in the DTWAIN namespace.