DTWAIN_AcquireToClipboard

Top  Previous  Next

The DTWAIN_AcquireToClipboard starts the image acquisition from a Source and transfers the image to the Windows Clipboard.

 

DTWAIN_ARRAY  DTWAIN_AcquireToClipboard (

DTWAIN SOURCE

Source,

LONG

PixelType,

LONG

NumPages,

LONG

TransferMode,

DTWAIN_BOOL

bDiscardImages,

DTWAIN_BOOL

bShowUI,

DTWAIN_BOOL

bCloseSource,

LPLONG

pStatus );

 

Parameters

Source

Specifies a selected TWAIN Source.

 

PixelType

Specifies the pixel type of the image

 

NumPages

Specifies the number of pages to acquire.

 

TransferMode

 

Specifies which transfer mode to use.

 

 

bDiscardImages

  Specifies whether images are destroyed instead of saved in returned DTWAIN_ARRAY.

 

bShowUI

Specifies whether the Source displays the default User Interface.

 

bCloseSource

   Specifies whether the Source should be closed after the User Interface is shut down.

 

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, a DTWAIN_ARRAY describing the attempted acquisitions is returned.  If the function fails, NULL is returned.

 

Comments:

Starts the image acquisition from a TWAIN device and saves the acquired image(s) to the Windows Clipboard.  This allows an application to simply use the "Paste" function to retrieve the image data (if the image is a Device Independent Bitmap).  Most applications implement "Paste" as retrieving data from the Clipboard.

 

The bDiscardImages flag determines whether the images that are acquired, except for the last image acquired are to be discarded.  If the value of bDiscardImages is TRUE, no images are saved within the returned DTWAIN_ARRAY, and the returned DTWAIN_ARRAY is equal to 1 on success.  If bDiscardImages is FALSE, the returned DTWAIN_ARRAY is an array of acquisitions attempted, along with the array of images (see the return value to DTWAIN_AcquireNative).

 

Note that this behavior of the bDiscardImages flag is only valid if the TWAIN mode is DTWAIN_MODAL (see DTWAIN_SetTwainMode).  If the TWAIN mode is DTWAIN_MODELESS, all of the images are saved, and it is the responsibility of the application to discard the image memory.

 

Regardless of the state of the bDiscardImages parameter, only the last page of the acquisition is saved to the clipboard if multiple pages are acquired, or if the program allows more than one acquisition to be attempted per open Source session.

 

The arguments PixelType, Source, MaxPage, bShowUI and pStatus all have the same definitions as DTWAIN_AcquireNative.

 

The TransferMode determines whether the native or buffered mode will be used to acquire the image(s).  To control which image transfer mode the Source will use, the TransferMode must be one of the following values

Transfer Mode

Value

Definition

DTWAIN_USENATIVE

1

Use the Native Transfer Mode.

DTWAIN_USEBUFFERED

2

Use the Buffered Transfer Mode.

 

It is advised that you should be familiar with the Window's API Clipboard functions.  You will need to use them if you want to retrieve the DIBs from the clipboard successfully. The data that is stored in the clipboard is of type CF_DIB.

 

This function is suitable for Visual Basic programmers who are familiar with handling the Clipboard object.  A call to Clipboard.GetData using the vbCFDIB data format is all that is required for a VB program to copy and display the data in an image or picture control.

 

Note: If multiple pages are desired using the clipboard, the application must be set up to capture DTWAIN notifications that indicate when a page has been transferred successfully, since each new page saved to the clipboard will overwrite any previous page.  If this is not done, only the last page from a multi-page acquire will be saved to the clipboard when the Source UI is closed.

 

TWAIN State Transitions

State 4(if Source is not opened)

State 5, 6, 7

 

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function

 

See Also

DTWAIN_AcquireBuffered, DTWAIN_AcquireNative, DTWAIN_AcquireFile