Logging TWAIN Activity with DTWAIN

When running an application using DTWAIN, DTWAIN has the ability to log all calls made to the TWAIN Data Source Manager (DSM).  This allows you to view all TWAIN traffic that is being sent and returned from the DSM that DTWAIN is making, and is a great debugging aid if something goes wrong.  You should be somewhat familiar to the Twain specification to use the log efficiently. Regardless, the log attempts to lay out as simple as possible what is going on internally.

Note that starting with DTWAIN 1.1.0.9, you can set these values programatically using the DTWAIN_SetTwainLog function.

When a call is made to the DSM, there are five components that you should be aware of:

A call to the DSM has the form of the following (this is pseudo-code):

Return Value = CallTwainDSM(TW_IDENTITY1, TW_IDENTITY2, DG, DAT, MSG, TW_MEMREF Data)

The TW_IDENTITY1 and TW_IDENTITY2 components represent the Origin and Destination TW_IDENTITY pointers, respectively, that are passed to the DSM when a call is made to the DSM.

The following describes the breakdown of the TW_IDENTITY structure  (From the TWAIN.H header file):

*************************************************************************

TW_UINT32  Id;                    /* Unique number. In Windows, application hWnd */

TW_VERSION Version;                /* Identifies the piece of code              */

TW_UINT16  ProtocolMajor;          /* Application and DS must set to TWON_PROTOCOLMAJOR */

TW_UINT16  ProtocolMinor;          /* Application and DS must set to TWON_PROTOCOLMINOR */

TW_UINT32  SupportedGroups; /* Bit field OR combination of DG_ constants */

TW_STR32   Manufacturer;          /* Manufacturer name, e.g. "Hewlett-Packard" */

TW_STR32   ProductFamily;          /* Product family name, e.g. "ScanJet"       */

TW_STR32   ProductName;            /* Product name, e.g. "ScanJet Plus"         */

****************************************************************************

The DG, DAT, and MSG make up the components of the Twain triplet that is sent to the DSM when the call is made.  The definition of the DG, DAT, and MSG parameters is defined by the Twain specification (see the description of DTWAIN_CallDSMProc above for more info).

The TW_MEMREF Data is the data that is sent to the DSM.  The data that is sent depends on the value of DG / DAT / MSG.  The data can be the form of a structure, value, NULL, etc.  If you read the Twain.h header file, this data is represented as a void pointer.  Even though this is a void pointer, the DTWAIN logging facility has the ability to decode the void pointer and display exactly what the structure being sent is, as well as the values.

The Return Value represents the return code from the call to the DSM.  This is either 0, meaning the call was successful, or a TWAIN failure code.

The [DSMErrorLogging] section is responsible for setting the DTWAIN error logging.  With the DTWAIN logging feature, you can customize how much information you want displayed in the log by setting certain parameters within the  [DSMErrorLogging] section.

The following can be placed in the [DSMErrorLogging] section:

File=filename

This option allows logged messages to go to the file specified by "filename". DTWAIN does not check if "filename" already exists, so you must be careful! If the file cannot be opened, the logging automatically goes to the current debug monitor window using the OutputDebugString() Windows API function.

DecodeIdentity1=

This option allows the TW_IDENTITY1 structure to be expanded in the log to show all values.  The valid values that DecodeIdentity1 can use is "0" (no expansion) or "1" (expand).  By default, no expansion is done.

DecodeIdentity2=

This option allows the TW_IDENTITY2 structure to be expanded in the log to show all values.  The valid values that DecodeIdentity2 can use is "0" (no expansion) or "1" (expand).  By default, no expansion is done.

DecodeData=

This option allows the TW_MEMREF data to be decoded and expanded in the log to show all values.  The valid values that DecodeData can use is "0" (no expansion) or "1" (expand).  By default, no expansion is done.  With this option set to "1", you can see exactly what structure and values were sent, instead of just a void pointer (which is what the TW_MEMREF data is sent as)

DecodeEvents=

When a Twain Source is displaying the user interface (State 5), many TW_EVENT messages are sent to the application.  There may be hundreds of TW_EVENT messages being sent at a rapid pace to the application.  The DecodeEvents option allows these events to be recorded in the log. The valid values that DecodeEvents can use are "0" for no logged TW_EVENTs, "1" for full logging of TW_EVENTs.  By default, the value is "0".  It is wise to turn off this option, (DebugEvents=0) unless it is deemed necessary to log them.  The log can get very large with this option turned on!

EnableAll=

This option is a shortcut that allows you to enable all of the options above (DecodeIdentity1, DecodeIdentity2, DecodeData, and DecodeEvents).  The valid values that EnableAll can use is "1" (enable all options) or "0" (do not enable all options; just use the options that are specified).  By default, the value is "0".

EnableNone=

This option is a shortcut that allows you to disable all of the options above (DecodeIdentity1, DecodeIdentity2, and DecodeData).  The valid values that EnableNone can use is "1" (disable all options) or "0" (do not disable all options; use the options that are specified).  By default, the value is "0". If EnableAll and EnableNone are specified, the EnableAll takes precedence.

CallStack=

This option will log DTWAIN calls internally.  When this option is turned on, entries in the log are created that shows the program flow of the DTWAIN library.  Lines starting with either

Entering DTWAIN Function     xxx

or

Exiting DTWAIN Functions     xxx

will appear in the log file ('    xx' is a name of a DTWAIN function).  This option is very useful to see the flow of the DTWAIN calls within the program. The valid values that CallStack can use are "1" (enable) or "0" (disable).  By default, the value is "0".

ShowExceptions=

This option will display any exception errors in a message box that may occur when you run your DTWAIN applications.  Exception errors are errors that can crash your application.  If this value is set to 1, the exception errors are displayed.

DisplayLibErrors=

This option will display any DTWAIN errors in a message box that may occur when you run your DTWAIN applications.

Example of DTWAIN.INI file setting