DTWAIN_EnumMaxBuffers

The DTWAIN_EnumMaxBuffers function gets all of the possible values that the Source can use to set the maximum number of pages to buffer when aquiring images.

LONG DTWAIN_EnumMaxBuffers (

DTWAIN_SOURCE	Source,
LPDTWAIN_ARRAY	pArray,
DTWAIN_BOOL	bExpandRange );

Parameters

Source

An open TWAIN Source.

pArray

Address of a DTWAIN_ARRAY (an LPDTWAIN_ARRAY) that will store the Source's possible values for the maximum number of pages that can be buffered when acquiring images, or NULL.

bExpandRange

Flag that determines whether the values will be expanded if the Source stores them in a TW_RANGE.

Return Values

The return value is the number of possible values supported by the Source when specifying the maximum number of pages that can be buffered when acquiring images. If there is an error, or if the Source does not support buffering pages, 0 is returned.

Comments

The DTWAIN_EnumMaxBuffers function gets all of the available values that can be used when requesting that the Source buffer pages when acquiring images. On return, lpMaxBuffers will be filled with all of the available values. Note that your application does not send a DTWAIN_ARRAY, but an LPDTWAIN_ARRAY (a pointer to a DTWAIN_ARRAY). The data type of the returned DTWAIN_ARRAY is LONG. If lpMaxBuffers is NULL or 0, no array is returned and only the number of values is returned.

If the Source stores the buffer values in a range type (a DTWAIN_RANGE), then the bExpandRange argument determines whether the values will be expanded into lpMaxBuffers before returning. If bExpandRange is TRUE, then DTWAIN_RANGE values will be expanded into a DTWAIN_ARRAY and lpMaxBuffers will be a regular DTWAIN_ARRAY. If bExpandRange is FALSE, the range is not expanded and lpMaxBuffers will be a DTWAIN_RANGE type. Note that bExpandRange is meaningful only if the Source uses a TW_RANGE to store the values, otherwise a regular DTWAIN_ARRAY is always used. To determine if the Source uses a range to store the values, call

DTWAIN_GetCapContainer(Source, DTWAIN_CV_CAPMAXBATCHBUFFERS, DTWAIN_CAPGET);

and check for a DTWAIN_CONTRANGE return value.

Many Sources store the values in terms of a range, since there could be hundreds, or possibly thousands of values. Expanding the range into array values will cause more storage to be used, slowing down DTWAIN_EnumMaxBuffers during expansion.

Note that not all Sources support page buffer setting. To determine if a Source supports page buffering, call DTWAIN_IsMaxBuffersSupported.

Example:

#include "dtwain.h"

void SomeCode( )

{

DTWAIN_ARRAY EnumArray;

LONG Count;

DTWAIN_SOURCE Source;

DTWAIN_FLOAT Value;

LONG Count2;

LONG ContainerType;

DTWAIN_BOOL Expand;

/* ... */

/* Assume Source has been opened */

/* ... */

/* Test if Source uses a range. We will handle the expansion ourselves */

Expand = TRUE;

ContainerType = DTWAIN_GetCapContainer( Source, DTWAIN_CV_CAPMAXBATCHBUFFERS, DTWAIN_CAPGET );

if ( ContainerType == DTWAIN_CONTRANGE )

Expand = FALSE;

/* Get the actual values, no expansion if Source uses a range */

Count = DTWAIN_EnumMaxBuffers( Source, &EnumArray, Expand );

if ( Count > 0 )

{

/* Print each contrast value */

for (Count2 = 0; Count2 < Count; Count2++ )

{

if ( Expand == FALSE )

/* This is a normal DTWAIN_ARRAY */

DTWAIN_ArrayGetAt( EnumArray, Count2, &Value );

else

/* This is an unexpanded DTWAIN_RANGE, so use DTWAIN_RANGE functions */

DTWAIN_RangeGetExpValue( EnumArray, Count2, &Value );

printf( "Page value %d is %lf\n", Count, Value);

}

/* Destroy values. Note that a DTWAIN_RANGE is a DTWAIN_ARRAY, so you can call

any DTWAIN_ARRAY functions on a DTWAIN_RANGE */

DTWAIN_ArrayDestroy( EnumArray );

}

TWAIN State Transitions

The Source must be in State 4 or higher

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function