DTWAIN_SetTwainLog
|
The DTWAIN_SetTwainLog allows a DTWAIN application to log calls to and from the DTWAIN DLL and to the TWAIN Data Source Manager.
DTWAIN_BOOL DTWAIN_SetTwainLog (
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.
Character specific version
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.
The LogFlags describes what TWAIN messages will be logged, as well as where the log will be created/shown.
The lpszFile is the path to the logfile if LogFlags has the DTWAIN_LOG_USEFILE flag set.
To turn off logging, LogFlags must be set to 0 (in this case, the lpszFile parameter is ignored).
If your application wants to do custom processing with the logged message (write to an alternate file, or sent to the console for example), then please see the DTWAIN_SetLoggerCallback function for custom processing.
Logging Basics and LogFlags usage
The DTWAIN_SetTwainLog can log all calls made by your application to the DTWAIN DLL. This includes parameter information and return values. Also, DTWAIN_SetTwainLog can log any and all calls made by the DTWAIN DLL internally to the TWAIN Data Source Manager (DSM). The LogFlags parameter determines how DTWAIN_SetTwainLog will behave.
Logging TWAIN DSM calls Basically, a call to the TWAIN 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.
LogFlags Usage
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 (example below uses DTWAIN_SelectSource call):
===>>>Entering DTWAIN_SelectSource( ) ... <<<===Exiting DTWAIN_SelectSource( ) -- returning value of xxxxxxxx
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. |