DTWAIN_GetCapValuesEx

Top Previous Next

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

DTWAIN_BOOL DTWAIN_GetCapValues (

DTWAIN_SOURCE	Source,
LONG	Capability,
LONG	GetType,
LONG	Container,
LPDTWAIN_ARRAY	pCapValues );

Parameters

Source

An open TWAIN Source.

Capability

The capability that is to be retrieved.

GetType

Indicates which type of retrieval to do.

Container

Indicates the TWAIN container to use

PCapValues

Address of a DTWAIN_ARRAY containing the values retrieved.

Return Values

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

Comments

The DTWAIN_GetCapValuesEx function sets a Source's device capability

Caution:

The TWAIN specification explicitly does not allow an application to determine the container for getting capability values. Therefore, DTWAIN_GetCapValuesEx is an advanced function and should be used only to test a Source and how it handles getting capability values 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 get the capability values in the safest manner, use the DTWAIN_GetCapValues function.

The difference between DTWAIN_GetCapValues and DTWAIN_GetCapValuesEx is that DTWAIN_GetCapValuesEx 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 retrieving 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 read the retrieved values is the DTWAIN_ARRAY pCapValues.

Basically, DTWAIN extracts the values from the Source by telling TWAIN to use the container specified by Container, and if successful, places the value retrieved from the Source into the DTWAIN_ARRAY specified by pCapValues.

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_CONTONEVALUE	1	TW_ONEVALUE
DTWAIN_CONTARRAY	2	TW_ARRAY
DTWAIN_CONTRANGE	4	TW_RANGE
DTWAIN_CONTENUMERATION	8	TW_ENUMERATION

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 read 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.

For more information on parameter definitions see DTWAIN_GetCapValues.

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