|
DTWAIN_StartTwainSession |
Top Previous Next |
|
The DTWAIN_StartTwainSession function starts a TWAIN Session.
DTWAIN_BOOL DTWAIN_StartTwainSession (
Parameters hWndSession Handle to TWAIN message window or NULL
szDLLName Points to a null-terminated string identifying the TWAIN DLL or NULL.
Return Values If the function succeeds, TRUE is returned. If the function fails FALSE is returned.
Character specific version
Comments The DTWAIN_StartTwainSession function starts a TWAIN session. When a TWAIN session is started, DTWAIN obtains the ability to interact with the TWAIN Data Source Manager (DSM).
Note that DTWAIN_StartTwainSession is not a mandatory function. If a TWAIN session has not been started by the application, DTWAIN will start a TWAIN session whenever the first Source Selection function is executed. However, there are cases where a TWAIN session should be started explicitly by the application, which is described in the hWndSession description below.
Only one TWAIN session can be started at any one time. There is no harm in calling DTWAIN_StartTwainSession if the session is already started. If this is the case, DTWAIN ignores the request to start another session and uses the original session. To end a session, call DTWAIN_EndTwainSession
The first parameter, hWndSession is a handle to the window that will handle DTWAIN messages and notifications if notifications are enabled (see DTWAIN_EnableMsgNotify), and will also serve as the parent window to other TWAIN related user interface windows (for example, many TWAIN Source user interface's rely on the position of hWndSession to position their own windows).
The hWndSession window will be sent DTWAIN notifications whenever acquisition of an image is being done. If hWndSession is NULL, then no notification window is used. If hWndSession is not NULL, the window must be opened for the lifetime of the session, since DTWAIN will be sending notifications to it for the lifetime of the acquisition. To ensure that the window will be available, it is always wise to use the main application window handle.
Since a non-NULL hWndSession will be used for notifications, it is important that any unprocessed DTWAIN messages sent to the the window return TRUE (1) by default. A failure to do this will result in erratic behavior.
Example (assume WndProc is the window procedure for the notification window):
LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam) { if ( msg == DTWAIN_GetRegisteredMsg( ) ) { // This is a DTWAIN message return TRUE; // for unprocessed DTWAIN messages } ... }
The second parameter, szDLLName is the name of the TWAIN DSM file or NULL (0). If the default name is desired, szDLLName should be NULL or empty string (a null-terminated string with no characters). It is recommended that you call this function specifying NULL or null-terminated empty string as the szDLLName value. Specifying an explicit name is reserved only for diagnostic purposes.
If the DTWAIN_SetTwainDSM function is called prior to DTWAIN_StartTwainSession, the DSM file used is the one specified by the DTWAIN_SetTwainDSM function, otherwise the DSM file is TWAIN_32.DLL for 32-bit applications, and TWAINDSM.DLL for 64-bit applications.
If DTWAIN needs to start a TWAIN session automatically, DTWAIN calls DTWAIN_StartTwainSession with both hWndSession and szDLLName set to NULL.
If a TWAIN session has not been started prior to DTWAIN_StartTwainSession being called, and the szDLLName is NULL, DTWAIN will search for the TWAIN_32.DLL or TWAINDSM.DLL file on the system using the search order specified by the DTWAIN_GetDSMSearchOrder function.
Note: A TWAIN session must not be terminated if a Source is currently acquiring an image. To ensure that this scenario does not happen, use the DTWAIN Source Status functions to check the acquisition status of the Source.
TWAIN State Transitions
Prerequisite Function Call(s)
See Also |