DTWAIN_RangeGetNearestValue

The DTWAIN_RangeGetNearestValue function gets the range value that is closest to a given value.

DTWAIN_BOOL DTWAIN_RangeGetNearestValue (

DTWAIN_RANGE	Range,
LPVOID	pValueIn,
LPVOID	pValueOut,
LONG	RoundType );

Parameters

Range

A valid DTWAIN_RANGE type.

pValueIn

Address of value to search for. This must be the address of a LONG or DTWAIN_FLOAT variable

pValueOut

Address where nearest value will be stored on return of DTWAIN_RangeGetNearestValue.

RoundType

Determines whether to round to the nearest range value, round up to the next range value, or round down to the previous range value.

Return Values

If the function succeeds, TRUE is returned. If the function fails FALSE is returned.

Comments

DTWAIN_RangeGetNearestValue gets the range value that is closest in value to the given value stored at the address pValueIn. On return of DTWAIN_RangeGetNearestValue, the nearest range value is copied to the address denoted by pValueOut. The pValueIn and pValueOut parameters must be pointers to LONG or DTWAIN_FLOAT variables, and pValueIn and pValueOut must be of the same type.

The RoundType argument determines whether to round up, down, or to the nearest range value. RoundType can be one of the following:

RoundType	Meaning
DTWAIN_ROUNDNEAREST	Rounds to the nearest range value
DTWAIN_ROUNDUP	Rounds to the next highest number in the range
DTWAIN_ROUNDDOWN	Rounds to the previous lowest number in the range.

If the value located at address pValueIn is less than the minimum value defined by the range, the minimum value of the range is returned in pValueOut. If the value located at address pValueIn is greater than the maximum value defined by the range, the maximum value of the range is returned in pValueOut..

An example is as follows:

If the DTWAIN_RANGE has the following characteristics:

minimum = -10

Maximum Value = 30

Step size = 5

The expanded range will consist of the following values

-10, -5, 0, 5, 10, 15, 20, 25, 30

void SomeFunction( )

{

LONG aLong[5] = {-10, 30, 5, 0, 0 };

LONG InVal = 12, OutVal;

DTWAIN_RANGE Range;

/* Create a range */

Range = DTWAIN_RangeCreate( DTWAIN_RANGELONG );

DTWAIN_RangeSetAll( Range, &aLong[0], &aLong[1], &aLong[2], &aLong[3], &aLong[4] );

/* Get the closest range value to 12 */

DTWAIN_RangeGetNearestValue( Range, &InVal, &OutVal, DTWAIN_ROUNDNEAREST );

/* OutVal is now 10 */

}

A call to DTWAIN_RangeGetNearestValue( ) will return 10 in OutVal, since 12 is closest to the range value 10, and the RoundType is DTWAIN_ROUNDNEAREST.

Uses for DTWAIN_RangeGetNearestValue:

This function is very useful for device capability value setting. If a capability returns a range of values, and your application must choose a value within the range, DTWAIN_RangeGetNearestValue will return a valid number in the range. This allows your application to set a capability with a valid value. For example, many Sources use a range to define the valid settings for the DTWAIN_CV_ICAPCONTRAST capability (the contrast setting). If your application needs to set the contrast, you must provide a valid number defined by the range. DTWAIN_RangeGetNearestValue will always return a valid number that is closest to the given number.

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize