DTWAIN_EnumResolutionValues

The DTWAIN_EnumResolutionValues function gets all of the possible resolution settings available for the current Source.

LONG DTWAIN_EnumResolutionValues (

DTWAIN_SOURCE	Source,
LPDTWAIN_ARRAY	lpResolutionVals,
DTWAIN_BOOL	bExpandRange );

Parameters

Source

An open TWAIN Source.

lpBitDepth

Address of a DTWAIN_ARRAY (an LPDTWAIN_ARRAY) that will store the Source's resolution values, 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 resolution values supported by the Source. If there is an error, or if the Source does not support resolution values, 0 is returned.

Comments

The DTWAIN_EnumResolutionValues function gets all of the resolution values supported by the TWAIN Source, Source. On return, lpResolutionVals will be filled with all of the available resolution 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 DTWAIN_FLOAT. If lpResolutionVals is NULL or 0, no array is returned and only the number of resolution values is returned.

If the Source stores the resolution values in a range type (a DTWAIN_RANGE), then the bExpandRange argument determines whether the values will be expanded into lpResolutionVals before returning. If bExpandRange is TRUE, then DTWAIN_RANGE values will be expanded into a DTWAIN_ARRAY and lpResolutionVals will be a regular DTWAIN_ARRAY. If bExpandRange is FALSE, the range is not expanded and lpResolutionVals will be a DTWAIN_RANGE type. Note that bExpandRange is meaningful only if the Source uses a TW_RANGE to store the resolution values, otherwise a regular DTWAIN_ARRAY is always used. To determine if the Source uses a range to store the resolution values, call DTWAIN_GetCapContainer(Source, DTWAIN_CV_ICAPXRESOLUTION, DTWAIN_CAPGET) and check for a DTWAIN_CONTRANGE return value.

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

Note that not all Sources support resolution settings. To determine if a Source supports resolution, call DTWAIN_IsCapSupported(Source, DTWAIN_CV_ICAPXRESOLUTION).

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_ICAPXRESOLUTION, DTWAIN_CAPGET );

if ( ContainerType == DTWAIN_CONTRANGE )

Expand = FALSE;

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

Count = DTWAIN_EnumResolutionValues( Source, &EnumArray, FALSE );

if ( Count > 0 )

{

/* Print each resolution value */

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

{

if ( Expand )

DTWAIN_ArrayGetAt( EnumArray, Count2, &Value );

else

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

DTWAIN_RangeGetExpValue( EnumArray, Count2, &Value );

printf( "Resolution 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