DTWAIN_AcquireToClipboard

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

DTWAIN SOURCE	Source,
LONG	PixelType,
LONG	NumPages,
LONG	TransferMode,
DTWAIN_BOOL	bDiscardImages,
DTWAIN_BOOL	bShowUI,
DTWAIN_BOOL	bCloseSource,
LPLONG	pStatus );

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

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

Points to a variable that will be filled in with an error status value or NULL if no error status is desired.

If the function succeeds, a DTWAIN_ARRAY describing the attempted acquisitions is returned. If the function fails, NULL is returned.

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.