DTWAIN_AcquireNative
|
The DTWAIN_AcquireNative function starts the acquisition of images from a TWAIN Source using the Native Transfer mode.
DTWAIN_ARRAY DTWAIN_AcquireNative (
Parameters Source Specifies a selected TWAIN Source.
PixelType Specifies the pixel type of the image
NumPages Specifies the number of pages to acquire.
bShowUI Specifies whether the Source displays the default User Interface.
bCloseSource Specifies whether the Source should be automatically closed when the User Interface is closed.
pStatus Points to a variable that will be filled in with an error status value or NULL if no error status is desired.
Return Values If the function succeeds and the Twain Mode is DTWAIN_MODAL, a DTWAIN_ARRAY describing the attempted acquisitions is returned. If the function succeeds and the Twain mode is DTWAIN_MODELESS, a non-zero value is returned. If the function fails or if no images are acquired, NULL is returned.
Comments The DTWAIN_AcquireNative function starts the image acquisition device and acquires images using the TWAIN Native transfer mode. When this function is called, the TWAIN Source, Source, will be ready to transfer images from the device. If the Source is not opened, DTWAIN_AcquireNative automatically opens the Source.
Setting the Pixel Type correct in conjunction with Bit Depth The PixelType parameter determines the pixel type, or color of the acquired images. The values defined in DTWAIN Pixel Type Constants denote the possible values that can be used. If the PixelType is DTWAIN_PT_DEFAULT, the currently selected pixel type and bit depth for the Source is used. To select a pixel type and bit depth, the application must make a call to either DTWAIN_SetPixelType or DTWAIN_SetBitDepth to ensure that the correct pixel type and bit depth are used if the PixelType parameter is DTWAIN_PT_DEFAULT
If you specify any other value for PixelType (a value different than DTWAIN_PT_DEFAULT), the pixel type is used, but only the default bit-depth is used. For example, if you specify DTWAIN_PT_RGB as the pixel type, the default bit depth is used. This could be 1, 8, 24, etc. depending on what the Source determines is the default bit depth for DTWAIN_PT_RGB. Usually there is only one bit depth for each pixel type, but this may not be the case for all Sources.
If internally the Source has a current pixel type that is not the same as PixelType, then DTWAIN will attempt to set the current pixel type of the Source to PixelType. If DTWAIN needs to set the current pixel type, then the default bit-depth for that pixel type is used.
If PixelType is not supported by the Source, DTWAIN_PT_DEFAULT will be used. Your application can query whether the pixel type is supported by calling DTWAIN_IsPixelTypeSupported.
In general, it is always the best practice for your code to manually set the pixel type and bit depth by calling DTWAIN_SetPixelType or DTWAIN_SetBitDepth, and then specifying DTWAIN_PT_DEFAULT as the PixelType argument. This ensures that DTWAIN will use the proper pixel type and bit depth when acquiring an image
Note that some Twain Source's will not return an image that matches the PixelType argument. This behavior is the responsibility of the Source and not of DTWAIN. There are Sources that are not fully TWAIN compliant and will ignore the bit-depth settings made by an external application.
The NumPages parameter determines the maximum number of pages to acquire per acquisition request. When the Source's user interface is enabled, the user may make more than one request to acquire images before closing the user interface. Within each attempt, the Source may acquire multiple pages. The NumPages parameter controls the maximum number of pages that each of these requests should handle. The NumPages parameter must be greater than zero, or the value DTWAIN_ACQUIREALL. If the image device is equipped with an automatic document feeder (ADF), DTWAIN_ACQUIREALL will automatically acquire all of the pages that are in the document feeder (see Multi-Page Acquisitions ). For single page acquisitions, NumPages should be 1 (if the device does not have an ADF, NumPages can also be DTWAIN_ACQUIREALL).
The bShowUI parameter denotes whether the Source's user interface (UI) is shown. If bShowUI is TRUE, the Source's UI is displayed. If bShowUI is FALSE, the Source's UI will only be turned off only if the Source allows it. By disabling the Source's UI, this also allows a custom interface to be used in place of the Source UI (See Implementing a Custom Source UI for more information). If bShowUI is FALSE, DTWAIN will acquire only one set of images each time a DTWAIN Acquisition function is called. Basically this means that DTWAIN automatically sets the maximum number of acquisition attempts to 1 when no UI is used (see DTWAIN_SetMaxAcquisitions.). Since there is no User Interface, it does not make sense to keep a non-existing User Interface opened for more than one acquisition.
The bCloseSource parameter determines whether the Source is to remain opened or closed when the Source's UI is closed. For fast operation, your application can set the bCloseSource to FALSE, however it should be emphasized: Many Sources only operate correctly when the Source is closed after the UI is closed, therefore it is always safe to set bCloseSource to TRUE!. Your application should always set this parameter to TRUE unless you are sure that the Source operates correctly if it is allowed to stay open after the UI is closed.
The pStatus parameter is either the address of a LONG variable, or NULL. If the value is not NULL, the location pointed by pStatus will be set to one of the following:
Note that if DTWAIN_AcquireNative returns NULL, this could indicate that the user closed the device's user interface without acquiring any images, thus is not necessarily an error. In this case, your application should check pStatus for a value of DTWAIN_TN_ACQUIRECANCELED to confirm that the user interface was closed without acquiring any images. When DTWAIN_AcquireNative is called, your application can process DTWAIN notificationss to check the status of an acquisition.
The following section discusses briefly the steps in retrieving the acquired DIBs. The Twain Mode used is very important in understanding the differences in how DTWAIN_AcquireNative performs.
To set the Twain mode, call DTWAIN_SetTwainMode.
DTWAIN_MODAL processing For most applications, DTWAIN_MODAL will be used to start and process Twain messages. On return of DTWAIN_AcquireNative, the DTWAIN_ARRAY describes all of the acquisition attempts made. The following sequence of calls should be done to obtain the images (device independent bitmaps) that were acquired successfully:
//... DTWAIN_ARRAY Acquisitions; LONG Count; HANDLE hDib, hDib2; Acquisitions = DTWAIN_AcquireNative( ...parameters... ); //... hDib =DTWAIN_GetAcquiredImage (Acquisitions, 0, 0); // Acquisition 1, page 1 hDib2 = DTWAIN_GetAcquiredImage(Acquisitions, 0, 1); // Acquisition 1, page 2 hDib3 = DTWAIN_GetAcquiredImage(Acquisitions, 1, 0); // Acquisition 2, page 1 //... DTWAIN_DestroyAcquisitionArray( Acquisitions, FALSE ); // destroy the array, but do not destroy the image data
Note that the function DTWAIN_GetAcquiredImage was called to retrieve the DIB for the particular page that was acquired. The returned DIB is an unlocked HANDLE type, and the user application must be responsible for handling the DIB by calling the Windows API function GlobalLock( ), and then ultimately freeing the memory by calling the Windows API functions GlobalUnlock( ) and GlobalFree( ). Alternately, an application can call DTWAIN_DestroyAcquisitionArray to destroy the DTWAIN_ARRAY plus the image data (this way, there is no need to call GlobalUnlock and GlobalFree).
DTWAIN_MODELESS processing If the DTWAIN_MODELESS processing is being used, the returned DIBs must be retrieved during DTWAIN Notification processing. Since the DTWAIN_AcquireNative function returns immediately when called when DTWAIN_MODELESS mode is chosen, the only way to retrieve the DIBs is by having the user application to use DTWAIN Notification Processing . Please review the DTWAIN Notification Processing section to understand retrieving DIBs. In general, your application should trap the DTWAIN_TN_ACQUIREDONE notification to retrieve the acquired DIBs. The DTWAIN_GetSourceAcquisitions function is used to get all of the acquired DIBs from the Source.
TWAIN State Transitions State 4 (if Source is not already opened) State 4 (if Source is closed after UI is closed)
Prerequisite Function Call(s)
See Also
|