DTWAIN_GetAcquiredImage

The DTWAIN_GetAcquiredImage function returns the handle to the image that is generated when the acquisition is completed.

DTWAIN_ARRAY	AcqArray,
LONG	WhichAcquire,
LONG	WhichImage );

Specifies the image that will be retrieved from the acquisition number specified by WhichAcquire.

If the function succeeds, an image block is returned. If the function fails, NULL is returned.

If DTWAIN_AcquireNative or DTWAIN_AcquireBuffered is called, you will need to get the images that were created for the pages that were acquired. The returned value from DTWAIN_GetAcquiredImage is the image that was generated for the acquisition attempt WhichAcquire and for page WhichImage. For most acquisitions the returned handle describes a Device Independent Bitmap (DIB). If DTWAIN_AcquireBuffered is called and DTWAIN_GetCompressionType is not DTWAIN_CP_NONE, the returned memory is raw, uncompressed data. Regardless of whether a DIB or an uncompressed image is returned, DTWAIN_GetAcquiredImage is used for both types.

The AcqArray argument is the DTWAIN_ARRAY that was returned when DTWAIN_AcquireNative or DTWAIN_AcquireBuffered was called. Remember that these acquisition functions return an array denoting the acquisitions and the array of images within each acquisition.

The next argument WhichAcquire denotes the acquisition number. The reason for the acquisition number is that the user may have started the acquisition process multiple times before actually closing the Source UI.

Since it is possible (and most likely) that a Source will be implemented as a modeless dialog, a user may attempt to acquire images many times before actually closing the UI. Each time the user requests to acquire images using the Source UI, a brand new set of images are generated. DTWAIN does not replace any previously acquired images; instead DTWAIN saves them in an array.

The acquisition number denotes the set of images generated for an acquisition started by the user. The acquisition number starts at 0, and is increased by 1 each time the user selects to acquire an image during a single call to each of the DTWAIN Acquisition functions. When the user or the program closes the Source UI, any subsequent call to a DTWAIN Acquisition function will start the acquisition number back to 0.

The last argument, WhichImage denotes which image within the acquisition to retrieve. This is the image that is returned from DTWAIN_GetAcquiredImage. This argument starts at 0 and has a limit to the number of acquired images within the acquisition minus one.

If the application decides to use Modal TWAIN acquisition processing, the following two scenarios illustrate the point of using DTWAIN_GetAcquiredImage:

A document scanner that will acquire images is equipped with an automatic document feeder (ADF). The user has placed five pages in the feeder and desires to scan all of the pages. Your application will call DTWAIN_AcquireNative to acquire all of the pages. Since the feeder contains five pages, there will be five images generated, one image per page. The TWAIN Source UI for the scanner is implemented as a modal dialog, which means that the Source UI will be closed automatically by DTWAIN whenever the acquisition has been completed.

Your application calls DTWAIN_AcquireNative, which initially displays the Source's user interface. The user then initiates the acquisition from the Source UI, which then scans all five pages. The Source UI is closed automatically by DTWAIN and DTWAIN_AcquireNative returns with the DTWAIN_ARRAY. There has been one acquisition, with five images existing for the acquisition. The WhichAcquire value for the DTWAIN_ARRAY is 0 (the first acquisition), and the images are numbered from 0 to 4 (pages 1 through 5).

The scanner that will be used to acquire an image is equipped with an automatic document feeder (ADF). The user has initially placed three pages in the feeder and desires to scan all of the pages. Your application will call DTWAIN_AcquireBuffered to acquire all of the pages. Since the feeder contains three pages, there will be three images generated, one image per page. The TWAIN Source UI for the scanner is implemented as a modeless dialog, which means that the Source UI will not be closed automatically by DTWAIN whenever the acquisition has been completed. The only entity that will close the Source UI is the user (there are ways to force closure of the Source UI programmatically; this topic explains more).

Your application calls DTWAIN_AcquireBuffered, which initially displays the Source's UI. The user then initiates the acquisition from the Source UI, which then scans all three pages. The Source UI remains opened. The user now places ten pages in the feeder and again initiates another acquisition. Again all ten pages are scanned successfully. The user decides to close the Source UI and DTWAIN_AcquireBuffered finally returns. There have been two acquisitions, the first acquired three pages, and the second acquired ten pages. The WhichAcquire can be either 1 (the first acquisition) or 2 (the second acquisition). Since the first acquisition generated three pages WhichImage can range from 1 to 3. Similarly, the second acquisition generated ten pages, so WhichImage can range from 1 to 10.

If the application decides to use Modeless TWAIN acquisition processing, the DTWAIN_GetAcquiredImage function returns the last set of successful images that were acquired. The modeless model does not 'store' all of the acquisition information as the Modal model does.

With each subsequent call to DTWAIN_AcquireBuffered or DTWAIN_AcquireNative, the acquisition count is reset to zero 0.