DTWAIN_SetAcquireStripBuffer

The DTWAIN_SetAcquireStripBuffer allows DTWAIN to use a user-defined buffer when acquiring images using the buffered transfer mode.

DTWAIN_BOOL DTWAIN_SetAcquireStripBuffer (

DTWAIN_SOURCE	Source,
HANDLE	hBuffer );

Parameters

Source

An open TWAIN Source.

hBuffer

Handle to a memory buffer or NULL if a user-defined buffer should not be used.

Return Values

The return value is TRUE if successful. Otherwise FALSE is returned.

Comments

The DTWAIN_SetAcquireStripBuffer function allows DTWAIN to use the buffer hBuffer when acquiring images using the buffered transfer mode. If hBuffer is NULL or 0, no user-defined buffer is used, and DTWAIN is responsible for all memory handling when acquiring images using the buffer transfer mode. By default, no user-defined buffer is used.

The hBuffer must have been previously allocated by the application calling the Windows API GlobalAlloc function using the GHND flag value. Information on GlobalAlloc can be found in all Windows API references.

The size of the buffer should be determined by calling DTWAIN_GetAcquireStripSizes. Since the buffered memory transfer acquires the image in strips (or tiles), each strip/tile is copied to the buffer hBuffer whenever the DTWAIN_TN_TRANSFERSTRIPDONE and DTWAIN_TN_TRANSFERDONE notifications are sent. The application is fully responsible for handling the strips/tiles of data.

Functions such as DTWAIN_SetAcquireStripBuffer should only be used by

1) programmers who are experienced in handling strips of image data and assembling the image from the strips of information, since DTWAIN is no longer responsible for creating the final image once a user-defined buffer has been established, and

2) for acquiring buffered images as tiles instead of strips. DTWAIN does not handle tiled data, thus the application is responsible for all the tiled data that is sent by the Source.

For more information and an example, please read the section in the user manual Using a User-Defined Buffer and Buffered Transfers.

The user-defined buffer is only used when calling the function DTWAIN_AcquireBuffered.

TWAIN State Transitions

The Source must be in State 4. or higher (depending on the capability).

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function