|
All of the event functions (except OnDefaultHandler) have the following prototype:
virtual LRESULT Onxxxxxx( DTwainSource& Source, LONG UserParam);
The Onxxxxxx would be the name of the DTwainListener function. The Source parameter is the current DTwainSource that the listener is associated with. The UserParam is a user-defined parameter set by calling DTwainListener::SetUserParam.
There is one special function, OnDefaultHandler, that does not have the same prototype as the other event functions:
virtual LRESULT OnDefaultHandler( DTwainSource& Source, WPARAM wParam, LPARAM lParam, LONG UserParam);
The OnDefaultHandler( ) function is called if the event isn't one of the event functions defined below. This allows the programmer to track events that do not have a corresponding event handler function. This allows your application to adapt to any events that the DTWAIN interface may send in future versions of DTWAIN.
When you derive from DTwainListener, the following functions are available that you can override in your derived class. Below is a table of these functions, and when they will be triggered. Also illustrated is the equivalent DTWAIN notification.
Event functions associated with acquisition start, stop, and failure.
Event Function Definition Equivalent DTWAIN Notification
OnAcqureCancelled
|
Called when an acquisition has been cancelled.
|
DTWAIN_TN_ACQUIRECANCELLED
|
OnAcquireDone
|
Called when acquisition has been completed
|
DTWAIN_TN_ACQUIREDONE
|
OnAcquireFailed
|
Called when there is a failure to acquire an image.
|
DTWAIN_TN_ACQUIREFAILED
|
OnAcquireStarted
|
Called when an acquisition has started
|
DTWAIN_TN_ACQUIRESTARTED
|
OnAcquireTerminated
|
Called when an acquisition has terminated (called regardless of whether acquistion is successful or not)
|
DTWAIN_TN_ACQUIRETERMINATED
|
Event functions associated with acquiring a page from a set of pages.
Event Function Definition Equivalent DTWAIN Notification
OnPageCancelled
|
Called when an acquired page has not been processed (program terminated the page acquisition).
|
DTWAIN_TN_PAGECANCELLED
|
OnPageContinue
|
Called after a page has been acquired from a multi-page acquisition.
|
DTWAIN_TN_PAGECONTINUE
|
OnPageFailed
|
Called when there is a failure acquiring a page.
|
DTWAIN_TN_PAGEFAILED
|
Even functions associated with the Source user interface
Event Function Definition Equivalent DTWAIN Notification
OnUIClosed
|
The Source user interface has been closed.
|
DTWAIN_TN_UICLOSED
|
OnUIClosing
|
The Source user interface is about to be closed.
|
DTWAIN_TN_UICLOSING
|
OnUIOpened
|
The Source user interface is opened.
|
DTWAIN_TN_UIOPENED
|
Event functions called while an image is being transferred between the device and DTWAIN:
Event Function Definition Equivalent DTWAIN Notification
OnTransferCancelled
|
Called when the transferring of an image from the device to DTWAIN has been cancelled.
|
DTWAIN_TN_TRANSFERCANCELLED
|
OnTransferDone
|
Called when transferring of an image from the device has been completed successfully.
|
DTWAIN_TN_TRANSFERDONE
|
OnTransferReady
|
Called when the transferring of data from the device to DTWAIN is about to start (transferring the image has not started).
|
DTWAIN_TN_TRANSFERREADY
|
OnTransferStripReady
|
Called during buffered transfer, before each strip of image data is acquired from the device.
|
DTWAIN_TN_TRANSFERSTRIPREADY
|
OnTransferStripDone
|
Called during buffered transfer, after a strip of image data has been acquired successfully.
|
DTWAIN_TN_TRANSFERSTRIPDONE
|
OnTransferStripFailed
|
Called during buffered transfer, the strip of image data has not been acquired due to cancellation by the user.
|
DTWAIN_TN_TRANSFERSTRIPFAILED
|
Event functions called when during file acquisition processing:
Event Function Definition Equivalent DTWAIN Notification
OnFilePageSaveOk
|
One particular page of the image file has been processed successfully.
|
DTWAIN_TN_FILEPAGESAVEOK
|
OnFilePageSaveError
|
Error in saving one a page to an image file. Called when either a single page or if a
|
DTWAIN_TN_FILEPAGESAVEERROR
|
OnFileSaveOk
|
Called when the entire image file (multi-page or single page image file) has been saved successfully.
|
DTWAIN_TN_FILESAVEOK
|
OnFileSaveError
|
Error in saving the image file (multi-page or single page file).
|
DTWAIN_TN_FILESAVEERROR
|
OnFileSaveCancelled
|
User cancelled the saving of the image file.
|
DTWAIN_TN_FILESAVECANCELLED
|
OnInvalidImageFormat
|
Called if an image has an invalid format (invalid bit depth, for example)
|
DTWAIN_TN_INVALIDIMAGEFORMAT
|
Event function called when an external device event is triggered:
Event Function Definition Equivalent DTWAIN Notification
OnDeviceEvent
|
External device event has been triggered.
|
DTWAIN_TN_DEVICEEVENT
|
Events when blank page is detected:
Event Function Definition Equivalent DTWAIN Notification
OnBlankPageDetected1
|
Blank page generated by TWAIN device has been detected
|
DTWAIN_TN_BLANKPAGEDETECTED1
|
OnBlankPageDetected2
|
Blank page generated by DTWAIN after processing original page from device
|
DTWAIN_TN_BLANKPAGEDETECTED2
|
OnBlankPageDiscarded1
|
Blank page has been discarded by application (generated from OnBlankPageDetected1).
|
DTWAIN_TN_BLANKPAGEDISCARDED1
|
OnBlankPageDiscarded2
|
Blank page has been discarded by application (generated from OnBlankPageDetected2)
|
DTWAIN_TN_BLANKPAGEDISCARDED2
|
Events when an end-of-job page is detected:
Event Function Definition Equivalent DTWAIN Notification
OnEOJDetected
|
An end-of-job page was detected.
|
DTWAIN_TN_EOJDETECTED
|
OnEOJDectectedTransferDone
|
An end-of-job page was detected after it has been transferred.
|
DTWAIN_TN_EOJDETECTEDTRANSFERDONE
|
All of the event functions, if not overridden in the derived class, return a value of 1. On some of the event functions, alternate return values are accepted if overridden by the derived class. For example if OnPageContinue is overridden, a return value of 0 will terminate the acquisition. Please refer to DTWAIN Notification processing to check for special return codes.
|