DTWAIN_SysDestroy
|
The DTWAIN_SysDestroy function is called to release any resources used by the DTWAIN DLL and close the TWAIN session down safely.
DTWAIN_BOOL DTWAIN_SysDestroy( );
Parameters None.
Return Values TRUE if successful, FALSE otherwise. If the function returns FALSE, call DTWAIN_GetLastError() to get extended information.
Comments The DTWAIN_SysDestroy function must be called whenever the application no longer needs to call DTWAIN functions. This function cleans up any resources that DTWAIN allocated to your application, as well as close any open Sources, destroys any DTWAIN_ARRAYs and other structures that were internally allocated by DTWAIN, and ends a started TWAIN session (if one has been started). You must call DTWAIN_SysInitialize once again to reset the DTWAIN DLL structures if you have called DTWAIN_SysDestroy.
If a Source is currently acquiring an image (this includes merely showing the Source's user-interface), DTWAIN_SysDestroy will always return FALSE, and the TWAIN sub-system is not shutdown. This ensures that the TWAIN sub-system is as stable as possible, since shutting down TWAIN when a Source is acquiring an image or showing the user-interface is not safe.
Basically, the application should not try to shut down if a Source is currently acquiring an image. Since DTWAIN has no control over how you've written your application, DTWAIN cannot stop you from closing the application prematurely without calling DTWAIN_SysDestroy. However shutting down the application without calling DTWAIN_SysDestroy can lead to undefined behavior, driver instabilities in other TWAIN applications, etc. In the cases where the application needs to ensure that a Source is not acquiring data, the DTWAIN_IsAcquiring and DTWAIN_IsSourceAcquiring functions can be used to see if it is safe to close the application down (for example, the user decides to close the application while acquisitions are being done -- your application should check at the point where the user is "forcing the application to close", and inform the user that the application cannot close due to the Source is still actively acquiring images). To ensure that DTWAIN_SysDestroy is called, the safest place to call DTWAIN_SysDestroy is on application shutdown (usually when the main window is destroyed).
Please note that if the process you're running detaches from the DTWAIN DLL, DTWAIN will automatically shut down by internally calling DTWAIN_SysDestroy. For example, if your application has loaded DTWAIN DLL using the Windows LoadLibrary( ) function, if your application then calls FreeLibrary( ) without calling DTWAIN_SysDestroy, DTWAIN will internally call DTWAIN_SysDestroy.
TWAIN State Transitions
Prerequisite Calls None.
Optional Prerequisite Calls None.
See Also |