DTWAIN Notification Codes

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.

DTWAIN_TN_PAGECONTINUE

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.

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).

DTWAIN_TN_UICLOSING

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.

DTWAIN_TN_UICLOSED

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:

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.

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.

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.

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.

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:

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.

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: