DTWAIN_SetCapValuesEx

The DTWAIN_SetCapValuesEx function sets the capability value(s) for a Source while specifying the TWAIN container type to use.

DTWAIN_BOOL DTWAIN_SetCapValuesEx (

DTWAIN_SOURCE	Source,
LONG	Capability,
LONG	SetType,
LONG	Container,
DTWAIN_ARRAY	CapValues );

Parameters

Source

An open TWAIN Source.

Capability

The capability that is to be set.

SetType

Indicates whether to set the capability or to the default capability value.

Container

Indicates the TWAIN container to use

CapValues

A DTWAIN_ARRAY containing the values to set for the capability or NULL.

Return Values

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

Comments

The DTWAIN_SetCapValuesEx function sets a Source's device capability The difference between DTWAIN_SetCapValues and DTWAIN_SetCapValuesEx is that DTWAIN_SetCapVaueEx relies on the programmer to specify the TWAIN container to use.

Depending on the TWAIN container, values must be placed in the container in a certain way when setting capability values. The TWAIN container is not used explicitly by the application. The only two entities that use the containers are DTWAIN and TWAIN. The only structure that the application will use to place the values is the DTWAIN_ARRAY CapValues.

Basically, DTWAIN extracts the values out of CapValues, places them in the container specified by Container and passes on the values to TWAIN and the Source.

To specify the container to use, Container should be one of the following values (the constants below define each container and their TWAIN equivalents):

DTWAIN_Container	Value	TWAIN Equivalent
DTWAIN_CONTARRAY	8	TW_ARRAY
DTWAIN_CONTENUMERATION	16	TW_ENUMERATION
DTWAIN_CONTONEVALUE	32	TW_ONEVALUE
DTWAIN_CONTRANGE	64	TW_RANGE

Note: DTWAIN_CONTONEVALUE, DTWAIN_CONTARRAY, and DTWAIN_CONTENUMERATION, uses a DTWAIN_ARRAY of the actual values that are to be set. The only odd one is the DTWAIN_CONTRANGE, where the elements in the DTWAIN_ARRAY are to be setup by using the special DTWAIN Range functions.

It is imperative that you understand the difference in the container types. DTWAIN simplifies the matter of setting up the containers internally; all you have to do is specify to DTWAIN which one to use, and DTWAIN does the job For an explanation of the container types, you can get the TWAIN specification from here.

Caution:

DTWAIN_SetCapValuesEx is an advanced function and should be used only to test a Source and how it handles setting a capability given different container types. Some Sources will not behave correctly and corrupt the operating system if given the wrong container type to use. If all that is desired is to set the capability values in the safest manner, use the DTWAIN_SetCapValues function.

For more information on parameter definitions see DTWAIN_SetCapValues.

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