DTWAIN_SetTwainLog

The DTWAIN_SetTwainLog allows a DTWAIN application to log calls to the DTWAIN DLL and to the TWAIN Data Source Manager.

DTWAIN_BOOL DTWAIN_SetTwainLog(

               LONG LogFlags,

               LPCSTR  lpszFile

               );

Parameters

LogFlags

   Specifies the various log flags that can be used (see Comments).

lpszFile

   Optional log file to use to store the log

Return Values

If the function succeeds, TRUE is returned.  If unsuccessful, FALSE is returned.

Comments

DTWAIN_SetTwainLog allows a DTWAIN application to log calls to the DTWAIN DLL and to the TWAIN Data Source Manager.  Usually, the log session is setup using the DTWAIN INI file, however, this allows a program to do this by calling a function.  If your program wants to log custom messages, the DTWAIN_LogMessage function is used.

If the DTWAIN_SetTwainLog function is called, the settings in the [DSMErrorLogging] section in the DTWAIN INI file are overridden.  Any calls to the Twain Data Source Manager (DSM) are fully decoded.

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 DTWAIN_CallDSMProc function is an example of calling the DSM directly.  Note that there are six arguments to DTWAIN_CallDSMProc, and this is exactly what will be written to the log anytime DTWAIN calls the DSM.

The LogFlag can be a combination (boolean OR-ing) of the following values:

DTWAIN_LOG_DECODE_SOURCE

Allows full information of the first argument (TW_IDENTITY1) to the Twain Data Source Manager to be recorded in the log.  This is equivalent to the DecodeIdentity1= setting in the DTWAIN Initialization file.

DTWAIN_LOG_DECODE_DEST

Allows full information of the second argument (TW_IDENTITY2)  to the Twain Data Source Manager to be recorded in the log.  This is equivalent to the DecodeIdentity2= setting in the DTWAIN Initialization file.

DTWAIN_LOG_DECODE_TWMEMREF

This option allows the TW_MEMREF data to be decoded and expanded in the log to show all values. With this option set, 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)

DTWAIN_LOG_DECODE_TWEVENT

When a Twain Source is displaying the user interface (State 5), many TW_EVENT messages are sent to the application.  There may be thousands of TW_EVENT messages being sent at a rapid pace to the application.  This option allows these events to be recorded in the log.   It is wise to turn off this option,  unless it is deemed necessary to log them.

DTWAIN_LOG_USEFILE

This option allows logged messages to go to the file specified by the lpszFile parameter.

DTWAIN_LOG_USEBUFFER

Allows DTWAIN to buffer a user-defined number of error messages.  This is useful if you want to collect the last n errors that have occurred.  See functions DTWAIN_GetErrorBuffer, DTWAIN_SetErrorBufferThreshold, DTWAIN_GetErrorBufferThreshold, and DTWAIN_ClearErrorBuffer for more information.  If the DTWAIN_LOG_USEBUFFER flag is set, but no error buffer has been established by calling DTWAIN_SetErrorBufferThreshold, the number of errors buffered is 50.

DTWAIN_LOG_CALLSTACK

Allows the calls to DTWAIN DLL to be written to the log.  These calls consist of any calls an application makes to DTWAIN, whether or not they directly call the DSM.  For example DTWAIN_SelectSource would be written to the log if this call was made by the application or internally by DTWAIN.  

Lines with the following will appear in the log:

Entering DTWAIN Function     xxx

Exiting DTWAIN Function     xxx

DTWAIN_LOG_ERRORMSGBOX

Allows all the DTWAIN errors to be displayed automatically in a message box.  This mode is useful if you wish to run your DTWAIN application and automatically report errors interactively.

DTWAIN_LOG_SHOWEXCEPTIONS

Allows all exception errors (errors that could have possibly caused your program to halt unexpectedly) to be displayed in a message box.  If an exception error occurs, you should attempt to diagnose the problem quickly, since they most likely would have caused your program to crash unexpectedly.  Reasons for exception errors are invalid pointers, writing or reading to memory that doesn't belong to the application, etc.

DTWAIN_LOG_INITFAILURE

Allows the logging of calls that fail due to the DTWAIN library not being properly initialized.  By default, DTWAIN initialization failures are not logged, since the logging facility in DTWAIN relies on a properly initialized library.  By setting the DTWAIN_LOG_INITFAILURE flag, the initialization failure is displayed as a message box, indicating that the call failed due to an improperly initialized library.

DTWAIN_LOG_FILEAPPEND

Appends to the log file specified by lpszFile.

To enable all of these options, the DTWAIN_LOG_ALL value can be used.   When specifying the LogFlags value, all of the above options can be used added or subtracted to turn off or on logging options, respectively.  For example, if you want to set all the options except for DTWAIN_LOG_CALLSTACK, you can set the LogFlags to the following:

DTWAIN_LOG_ALL -  DTWAIN_LOG_CALLSTACK

This sets all the logging turned on (except for DTWAIN_LOG_FILEAPPEND), and turns off DTWAIN_LOG_CALLSTACK.

The lpszFile argument is recognized only if the DTWAIN_LOG_USEFILE or DTWAIN_LOG_FILEAPPEND options are set. This option allows logged messages to go to the file specified by lpszFile. DTWAIN does not check if lpszFile already exists.  If the file cannot be opened, the logging automatically goes to the current debug monitor window using the OutputDebugString() Windows API function..

If lpszFile is NULL, or the DTWAIN_LOG_USEFILE flag is not set, all the output goes to the current Debug Monitor window.  This is usually the compiler's 'Output Window' when you run your application in the compiler's environment, but it also can be any program that is set up to capture messages sent using the Windows API OutputDebugString function.  Such a program is DebugView, which is free and is available at http://www.sysinternals.com.

DTWAIN_SetTwainLog is a very powerful debugging tool when used correctly.  Note that everything discussed in DTWAIN_SetTwainLog can be accomplished by setting the [DSMErrorLogging] section in the DTWAIN INI file, however having the ability to do this programatically has advantages over setting values in the INI file.