DTWAIN Modal Acquisition Processing

The DTWAIN Modal acquisition-processing allows a TWAIN enabled application to call TWAIN functions without having to adjust the application's message loop to communicate successfully with the TWAIN protocol.  This makes modal processing fit in with languages that do not easily let the programmer hook into the main application loop processing.  This includes programming languages such as Visual Basic, Delphi, Java, and other script-like languages.  In general the application must not alter the application message loop.

Another advantage is that the programmer does not need to set up a 'callback' or 'message filter' to determine when an image has been transferred from the Source to the application.  DTWAIN handles all of those details.  To set this mode, the ::DTWAIN_SetTwainMode( DTWAIN_MODAL ) is called.  By default, DTWAIN always acquires images using the modal acquisition processing, so it is only necessary to call DTWAIN_SetTwainMode if the mode has been changed to modeless processing.

Once the scanner or digital camera starts acquiring images (transitioning back and forth between State 6 to State 7), the DTWAIN Modal processing forces the DTWAIN Acquisition function to return only when the user or your application closes the UI or closes the Source.  Once the UI or Source is closed, the DTWAIN Acquisition process is finished, and the acquired image data is handled by DTWAIN.   DTWAIN can then send these images back to your application, or save them to one of many image formats supported by DTWAIN.  DTWAIN's method of having the DTWAIN Acquisition functions return only when the UI or Source is closed is based on the fact that the user may make a series of acquisitions without closing the Source.

Most likely, the Source UI can be enabled for any amount of time and is closed by the user at any time.  For example, while the UI is enabled, the user can acquire a set of images, acquire another set of images,etc. and then decide to close the Source.  Remember that each time the user acquires one set of images, this may mean multiple pages are acquired.  So it is conceivable that the user can acquire 10 pages, then 8 pages, then 3 pages, meaning that three acquisition attempts occurred, and within each attempt there are 10, 8, and 3 sets of page data, respectively.

DTWAIN handles this scenario by recording each time the user acquire images, and stores each acquisition session in a DTWAIN array.  When the user acquires a set of images, an internal acquisition number is incremented.  Within each element of the acquisition array, lies another DTWAIN array of acquired images (by default, the images are in the form of Device Independent Bitmaps, or DIB for short).   There are DTWAIN that will let your application know exactly how many acquisitions were attempted, and the series of images that were acquired for each acquisition.  The process of encapsulating the entire TWAIN Session within a few function call eases the way a programmer would 'lay out' a program that needs to scan an image.  The code to scan the image is isolated to one area of your program instead of being spread throughout your application.

Many other TWAIN libraries close the Source UI as soon as the first acquisition is done.  This should not be the case for modeless Sources.  The user decides when to close the Source.  DTWAIN encapsulates the whole process within the DTWAIN Acquire set of functions, which allows you application to safely handle cases where the user decides to acquire more than one set of images.

Capturing and handling DTWAIN notifications

There is no need to handle DTWAIN notifications when using the Modal Acquisition Processing, however you can still use it if you decide.  The following topic discusses the Notification Processing:

DTWAIN Notification Processing

Disadvantages of the Modal Acquisition Model

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

The first item is important to remember, since your application is 'suspended' until the Source UI is closed.  In reality, the application is not really suspended (the user can still interact with the application), but the programmer must assume that the application is suspended (this is related to the second item).

The second 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.  The easiest thing to do is to disable your application's main window when acquiring an image, and then enable the main window when the user finally closes the user interface.

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.

The third item is a caution.  Most Sources behave correctly when acquiring in a modal loop.  However, there are a few Sources that do not behave correctly when acquiring in a modal loop.  These Sources are rare, so chances  that you will encounter one is remote.  However if you do get a Source that doesn't behave correctly in modal processing, the only option is to use modeless processing.

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