|
For image acquisition, the notifications are sent once a DTWAIN Acquisition function is called, and notifications have been turned on by calling DTWAIN_EnableMsgNotify( TRUE ). The notification codes below are the WPARAM value when DTWAIN sends the message that is equal to DTWAIN_GetRegisteredMsg if using a window handle to retrieve the notification (a callback function set by DTWAIN_SetCallback can also be used to get notifications). The LPARAM value is always the DTWAIN_SOURCE value of the Source that is acquiring.
For any notifications that your application will not process, your application must return TRUE (1), not FALSE (0). If you are not sure what return code to send back to DTWAIN after processing a notification, or the description below does not specify you return a value from a certain notification, always return TRUE (1).
|
DTWAIN_TN_ACQUIRESTARTED
|
DTWAIN has started to acquire images.
|
|
DTWAIN_TN_ACQUIREDONE
|
All pages have been acquired.
|
|
DTWAIN_TN_ACQUIRETERMINATED
|
Sent when all acquisitions have been done.
|
|
DTWAIN_TN_ACQUIREFAILED
|
Acquisition has failed.
|
|
DTWAIN_TN_ACQUIRECANCELLED
|
User cancelled the acquire (usually by clicking'Cancel' in the user interface). This is also sent if the User Interface is closed after acquisition has completed.
|
|
DTWAIN_TN_ACQUIREPAGEDONE
|
A page has been acquired. Same as DTWAIN_TN_TRANSFERDONE (see below)
|
|
DTWAIN_TN_BLANKPAGEDETECTED1
|
Sent when DTWAIN has detected that the acquired page is blank (see DTWAIN_SetBlankPageDetection).
If auto-discard is not used, the application must return 0 to discard the page, or 1 to keep the page.
|
|
DTWAIN_TN_BLANKPAGEDETECTED2
|
Sent when DTWAIN has detected that the acquired page is blank after it has been cropped and resampled by DTWAIN (see DTWAIN_SetBlankPageDetection).
If auto-discard is not used, the application must return 0 to discard the page, or 1 to keep the page.
|
|
DTWAIN_TN_BLANKPAGEDISCARDED1
|
Sent when a blank page has been discarded by DTWAIN.
The page discarded is the original image that was produced by the device
|
|
DTWAIN_TN_BLANKPAGEDISCARDED2
|
Sent when a blank page has been discarded by DTWAIN.
The page discarded is the cropped and resampled page that was produced internally by DTWAIN from the original image.
|
|
DTWAIN_TN_EOJDETECTED
|
The end-of-job marker was detected (patch code, blank paper, etc.). This is only supported for TWAIN devices that support job control.
|
|
DTWAIN_TN_EOJDETECTED_XFERDONE
|
End-of-job marker detected. Unlike DTWAIN_TN_EOJDETECTED, this message is sent right after a page has been acquired, and before it is saved to an image file (if saving to a file was requested by calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx).
|
|
DTWAIN_TN_FILENAMECHANGING
|
Sent before a file is to be saved using DTWAIN_AcquireFile or DTWAIN_AcquireFileEx. Use this notification to optionally change the name of the file by calling DTWAIN_SetSaveFileName during the notification. Also, DTWAIN_GetSaveFileName can be used to retrieve the current file name that will be saved during this notification.
|
|
DTWAIN_TN_FILEPAGESAVEERROR
|
There was an error saving a page for a multi-page image file. See DTWAIN_TN_FILESAVEERROR for more information.
|
|
DTWAIN_TN_FILEPAGESAVING
|
Sent before a page of an multi-page image file is being saved. Use this notification to prepare any processing that your application may do before the page has been saved.
|
|
DTWAIN_TN_FILEPAGESAVEOK
|
The image for a page in a multi-page image file has been saved succesfully. This notification is sent for multi-page image files when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx specifies a multi-page image file.
|
|
DTWAIN_TN_FILESAVECANCELLED
|
The user decided not to save the image file. This is sent when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx is called with the DTWAIN_USEPROMPT flag, and the user closes the File Save dialog without saving the file.
|
|
DTWAIN_TN_FILESAVEERROR
|
Sent when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx cannot save the image file successfully. Probable causes for this notification is either the file name is invalid, there is no room on the drive to save the file, the directory is write-protected, or the file exists and cannot be overwritten.
|
|
DTWAIN_TN_FILESAVEOK
|
Sent when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx successfully saves the image file. For a multi-page image file, this notification is sent after all pages have been saved.
|
|
DTWAIN_TN_INVALIDIMAGEFORMAT
|
Sent when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx attempts to save an acquired image to a file, and the image format is invalid for the file type. The reason for this error is more than likely a problem with the bit-depth of the image that was acquired, and attempting to save to a format that doesn't support the bit-depth.
|
|
DTWAIN_TN_PAGEFAILED
|
A page failed to be acquired. If application returns 0, the acquisitions and any pending transfers are stopped. If the application returns 1, the failed page can be re-tried by the user to be scanned. If the application returns 2, the DTWAIN_GetMaxRetryAttempts will determine whether the acquisition will be terminated or the page acquisition will be tried again. Usually low memory conditions or paper jams are the cause of this notification to be sent.
|
|
DTWAIN_TN_PAGECANCELLED
|
User cancelled page acquire.
|
|
|
Sent when a page is to be acquired. If application returns non-zero
acquisition continues (see Responding to DTWAIN Notifications below) If application returns 0, the acquisition stops.
|
|
DTWAIN_PN_PAGEDISCARDED
|
Sent if on DTWAIN_TN_QUERYPAGEDISCARD, application returned 0 (do not save the page).
|
|
DTWAIN_TN_PROCESSEDDIB
|
Sent when the Device Independent Bitmap has been acquired from the device and before it has been cropped, scaled, or saved to a file by DTWAIN.
Use this notification to retrieve the image data as soon as it is acquired from the device. The application must return either 0 to indicate that the image should not be further processed by DTWAIN, or 1 for DTWAIN to continue processing the image (cropping, resizing, etc.).
See DTWAIN_GetCurrentAcquiredImage for more information.
|
|
DTWAIN_TN_PROCESSEDDIBFINAL
|
Sent when the Device Independent Bitmap has been acquired from the device and after it has been cropped and scaled, but before it has been saved to a file by DTWAIN.
This notification is sent after the DTWAIN_TN_PROCESSEDDIB notification has been sent.
Use this notification to retrieve the image data as soon as it is acquired from the device. The application must return either 0 to indicate that the image should not be further processed by DTWAIN, or 1 for DTWAIN to continue processing the image (cropping, resizing, etc.).
See DTWAIN_GetCurrentAcquiredImage for more information.
|
|
DTWAIN_TN_QUERYPAGEDISCARD
|
Sent before a page is saved to a file when calling DTWAIN_AcquireFile and DTWAIN_AcquireFileEx calls, or before the image will be saved to the image acquisition array using DTWAIN_AcquireNative, DTWAIN_AcquireNativeEx, DTWAIN_AcquireBuffered and DTWAIN_AcquireBufferedEx call.
If the application returns 0 when receiving this notification, the page will either not be saved to the image file, or will not be saved to the resulting image acquisition array, depending on the DTWAIN Acquisition function that was called.
You can use this notification to retrieve the image data and determine if the image is acceptable or not. See DTWAIN_GetCurrentAcquiredImage for more information.
|
|
DTWAIN_TN_TWAINPAGECANCELLED
|
Sent if the TWAIN driver has detected that a "cancel" operation has been requested.
|
|
DTWAIN_TN_TWAINPAGEFAILED
|
Sent if the TWAIN driver has detected that a failure has occurred when acquiring a page.
|
|
DTWAIN_TN_UIOPENED
|
Sent after the Source's User Interface is displayed (transition from
State 4 to State 5).
|
|
|
Sent when the Source's User Interface is about to be closed after the acquisition has been completed, or the user selects the 'Close' or
'Finish' button if the Source's User Interface uses a modeless dialog box.
|
|
|
Sent when the Source's User Interface has been closed after the acquisition has been completed, or the user selects the 'Close' or
'Finish' button if the Source's User Interface uses a modeless dialog box.
|
The following two messages can be used by experienced TWAIN programmers who need to perform pre and post Source functions (possibly set special device capabilities) during image acquisition:
|
|
Sent when the Source initially enters TWAIN State 6. If the application returns a value of 0 for this notification, the acquisition stops before the page is acquired.
|
|
|
Sent when the Source goes from State 7 to State 6
|
|
DTWAIN_TN_TRANSFERSTRIPREADY
|
|
|
Sent when a strip of data is about to be sent from the Source to the application. Called only for buffered transfers
(DTWAIN_AcquireBuffered)
|
|
DTWAIN_TN_TRANSFERSTRIPDONE
|
|
|
Sent when a strip of data has been sent from the Source to the application. Called only for buffered transfers
(DTWAIN_AcquireBuffered)
|
|
DTWAIN_TN_TRANSFERTILEREADY
|
Sent when a tile of data is about to be sent from the Source to the application. Called only for buffered transfers using tiles.
|
|
DTWAIN_TN_TRANSFERTILEDONE
|
Sent when a tile of data has been sent from the source to the application. Similar to DTWAIN_TN_TRANSFERTILEREADY, this notification is only sent for buffered, tiled transfers
|
The following notifications are used during Manual Duplex Scanning Mode:
|
DTWAIN_TN_MANDUPSIDE1START
|
Side 1 will be acquired.
|
|
DTWAIN_TN_MANDUPSIDE2START
|
Side 2 will be acquired.
|
|
DTWAIN_TN_MANDUPSIDE1DONE
|
Finished acquiring Side 1.
|
|
DTWAIN_TN_MANDUPSIDE2DONE
|
Finished acquiring Side 2.
|
Responding to DTWAIN Notifications
You can either respond to the DTWAIN messages and notifications when all pages have been acquired, after each individual page has been acquired, or both. For any unprocessed DTWAIN notifications, your application must return TRUE.
Following are descriptions of each scenario, and what your application needs to do to respond to the notification in the proper way.
Processing when the acquisition starts:
If the DTWAIN notification is DTWAIN_TN_ACQUIRESTARTED, the acquisition has been successfully started. In addition, a DTWAIN_TN_TRANSFERREADY will be sent to your application. When this notification is sent, your application has the option of stopping the acquisition process by returning FALSE, or continuing with the acquisition by returning TRUE.
Processing when all pages have been acquired:
If the DTWAIN notificastion is DTWAIN_TN_ACQUIREDONE, acquisition of all pages has been successful. From this point, you should call any of the DIB Retrieval functions to get all of the DIBs that have been acquired. This is the only message that your application should use to determine when to retrieve all acquired images. Attempting to access all of the the acquired image data by using any other notification (except for possibly DTWAIN_TN_ACQUIREPAGEDONE) may result in undefined behavior.
Processing when each page has been acquired:
When the DTWAIN notification equals DTWAIN_TN_ACQUIREDONE, you can still get the handle to the current DIB as well as any DIBs created from pages that were acquired within the same acquisition session by calling DTWAIN_GetAcquiredImage or DTWAIN_GetAcquiredImageArray, exactly as if all DIBs were acquired. The last dib in DTWAIN_GetAcquiredImageArray is always the last DIB that was acquired.
Processing after each page has been acquired:
If the acquisition will involve multiple pages, DTWAIN will send the DTWAIN_TN_PAGECONTINUE notification before the next page is to be retrieved. This notification allows your application to continue retrieving pages or halt the acquisition altogether. The DTWAIN message window procedure or callback function must return one of the follwing values back to DTWAIN:
Return Value Definition
0 Stop Acquiring Pages
1 Continue Acquiring Pages
2 Stop Document Feeder, but continue acquiring pages
A return value of 0 stops all acquisitions. A return value of 1 continues the acquisition process if there are more pages to acquire. If a return value of 2 is used, a device that is using the document feeder will stop the feeder, but will be in the acquiring state ready to acquire the next set of pages..
It is imperative that your DTWAIN message window procedure always returns TRUE, and never FALSE for unprocessed notifications. If not, your application will be erratic when it comes to multiple page acquisitions, since the return value will be a random value (this is especially important for C and C++ programmers to take note of!). Also, a return value of FALSE for the DTWAIN_TN_TRANSFERREADY notification will halt the acquisition process.
Processing if an error has occurs:
DTWAIN will either send the DTWAIN_TN_ACQUIREFAILED notification if the acquisition failed, or the DTWAIN_TN_PAGEFAILED if the acquisition of a certain page in a multiple page acquisition has failed.
If the notification is DTWAIN_TN_ACQUIREFAILED there could be many reasons for this, however you can use the DTWAIN_GetLastError function to get an idea of what may have caused the problem. Almost all of the time the problem is TWAIN related, such as a corrupted Source, a device capability was set to an unreasonable value that the Source didn't try to check until the acquisition was attempted, out of memory conditions, etc.
If the notification is DTWAIN_TN_PAGEFAILED, The DTWAIN message window procedure or callback function must return one of the follwing values back to DTWAIN:
Return Value Definition
0 Stop Acquiring Pages
1 Retry failed page and continue
2 Either stop acquiring or retry the page,
depending on DTWAIN_SetMaxRetryAttempts
|