DTWAIN Modeless Acquisition Processing

The DTWAIN Modeless acquisition-processing allows a TWAIN enabled application to call TWAIN functions with an adjusted message loop that will control the TWAIN messaging.  .The modeless acquisition-processing model has many advantages.  One advantage is that the application can more easily and safely process acquiring images while the application can do other tasks. Another advantage is that the modeless model is what the TWAIN specification endorses.  This means that there is less likely to be any problems when implementing DTWAIN acquisitions using the modeless model than with the modal model.   To set this mode, DTWAIN_SetTwainMode (DTWAIN_MODELESS) is called.

Once the scanner or digital camera starts acquiring images, TWAIN will start sending messages to your main application loop.  These messages must be processed by your application properly and efficiently.  To accomplish this, your main application's message loop must be adjusted.

The other main difference between modeless and modal acquisition processing is the way that the DTWAIN Acquisition functions work.  If modeless processing is done, the DTWAIN acquisition functions return immediately when they are called.  Unlike modal processing, the application will get an immediate return from any call to the acquisition functions. This is why the application must have its message loop altered.  TWAIN is using your application message queue to place messages, so it's the responsibility of your application to handle them correctly

The following topic discusses how to alter the application loop for modeless processing (don't worry, this is nothing like the normal TWAIN message loop processing. DTWAIN practically does all of the work in deciding what to do with the messages)

Altering the Main Application Loop

Capturing and handling DTWAIN notifications

The other thing that is done is when the acquisition process starts, DTWAIN will start sending the application notifications and messages to your application's TWAIN session window, and/or the callback function set by calling DTWAIN_SetCallback.  The TWAIN session window is the HWND parameter in the call to the DTWAIN_StartTwainSession function.

Your application will look for notifications that tell you when an image has been acquired, when the Source or UI is closed, when an acquisition starts, if the acquisition was cancelled, etc.  If you programmed a traditional TWAIN application, this approach will be familiar to you.  The only difference is that DTWAIN filters out a lot of the noise that TWAIN sends to your session window and/or callback function and sends important information in terms of what the acquisition is doing.

DTWAIN sends a message to the session window, along with the traditional word and long parameters (WPARAM and LPARAM) letting your application know what is happening.  If you are intercepting the notifications using a window, the message that is sent is always equal to the value returned by DTWAIN_GetRegisteredMsg.  This message number is guaranteed to be unique throughout your application, and the Windows system altogether.  The WPARAM and LPARAM values will vary.  For more information on DTWAIN notification processing, see DTWAIN Notification Processing

Retrieving the Acquired Image Data

To retrieve the DIBs or image data in modeless mode, the DTWAIN_GetSourceAcquisitions function can be used when the DTWAIN_TN_ACQUIREDONE notification is sent to your notification window.  The DTWAIN_GetSourceAcquisitions function is used to retrieve the array of acquisitions, and is analogous to the return value when acquiring images using DTWAIN Modal processing.

If you want to retrieve each image as it's being acquired, call DTWAIN_GetCurrentAcquiredImage when the DTWAIN_TN_TRANSFERDONE notification is sent.  Anytime a 'page' is acquired successfully, the DTWAIN_TN_TRANSFERDONE notification is always sent.

Disadvantages of the Modeless Acquisition Model

There are disadvantages to the modeless acquisition model.  Here is a list of them:

The first item means that the language that you are programming with must be able to adjust the main application lop.  If you program using C or C++, you can alter the application loop with ease (especially if you program using the straight Windows API).

The second item is necessary to capture the image data and to monitor the progress of the acquisition.

The third item is to be adhered to regardless of whether the acquisition model used is modeless or modal.  Basically, the application must make sure that the user interaction (or programming action) does not do anything that may interfere with the acquisition of images.  Things such as attempting to open a TWAIN Source while acquiring from the Source, closing a Source while acquiring, starting another TWAIN session, etc.  should not be done while DTWAIN is acquiring images.  This may mean that your application will have to disable menu items, buttons, dialogs, etc.  that may have anything to do with acquiring an image while an image is currently being acquired, and enable the items once the UI is closed.

DTWAIN guards against the programmer from making these types of mistakes by checking if a Source can be opened, a session can be started or closed, etc.  Additionally, DTWAIN provides functions that let your application know whether a Source is acquiring an image.  This allows you to know when or when not to enable/disable certain items in your application.  This extra level of protection is a great help to many who are novices at TWAIN and want to get an application that is not prone to the many fatal errors that TWAIN can produce if not handled correctly.

Controlling the Maximum number of Acquisitions

The maximum number of acquisition attempts can be controlled by the application.  If there is a maximum count as to the number of acquisitions that the user or application can make (usually the maximum is 1), DTWAIN will close the Source automatically and return the DTWAIN_ARRAY that was generated.  This overrides the default behavior.  The function to set the maximum number of acquisitions allowed is DTWAIN_SetMaxAcquisitions.