DTWAIN_RangeGetPos

The DTWAIN_RangeGetPos function gets the position of the value if the range is expanded.

DTWAIN_BOOL DTWAIN_RangeGetPos (

DTWAIN_RANGE	Range,
LPVOID	lpValue,
LPLONG	lpPosition );

Parameters

Range

A valid DTWAIN_RANGE type.

lpValue

Address of value to determine the position of.

lpPosition

Address of where the position will be copied.

Return Values

TRUE if successful, FALSE otherwise. If the function returns FALSE, call DTWAIN_GetLastError() to get extended information.

Comments

The DTWAIN_RangeGetPos gets the position of the value lpValue within a range Range if the range is expanded. The lpPosition will be filled in with the position of the value.

The range does not need to be physically expanded (see DTWAIN_RangeExpand) to determine the position of the value.

Note that lpValue is the address of the value to use. Since DTWAIN_RANGEs can differ in data types, the caller to this function is responsible in seeing that the data type residing at lpValue matches the data type stored in Range.

In short, range expansion is the act of taking a range and generating all of the numbers that the range defines. The minimum, maximum, and step sizes determine the expanded numbers. For example if the DTWAIN_RANGE has the following characteristics:

Minimum Value = -10

Maximum Value = 10

Step size = 2

The expanded range will consist of the following values

-10, -8, -6, -4, -2, 0, 2, 4, 6, 8, 10

In the example above, the position of the value -4 would be at index 3 (the position is 0-based), the position of 8 would be at index 9, etc.

The small example below shows this scenario:

// Create the range

DTWAIN_RANGE range = DTWAIN_RangeCreate( DTWAIN_RANGELONG );

DTWAIN_RangeSetAllLong(range, -10, 10, 2, -10, -10);

// Get the position of the -4

LONG position;

LONG searchposition = -4;

DTWAIN_RangeGetPos(range, &searchposition, &position);

// position should be equal to 3

printf("The position of -4 is at index %d", position);

If the value is not found in the range, lpPosition will return the "closest" index to the number.

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize