DTWAIN_SetCapValues

Top Previous Next

The DTWAIN_SetCapValues function sets the capability value(s) for a Source.

DTWAIN_BOOL DTWAIN_SetCapValues (

DTWAIN_SOURCE	Source,
LONG	Capability,
LONG	SetType,
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.

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_SetCapValues function sets a Source's device capability

The Source Source must be selected using one of the Source Selection Functions. The capability Capability is the Source's capability that is to be set. A list of the capabilities as well as the capabilities data type can be found in the topic DTWAIN Capability Constants.

Please note: If you are setting the value(s) of

1) a custom capability, or

2) not one of the standard TWAIN capabilities, or

3) a capability that the DTWAIN library has no previous knowledge of (for example, a recently added capability from a new TWAIN standard),

and you have full information on the capability (number, type of container to use, etc.), use the DTWAIN_SetCapValuesEx2 function instead of DTWAIN_SetCapValues.

The SetType determines whether the capability will be set to new values or to the default capability value(s). The values of SetType can be one of the following:

SetType	Definition
DTWAIN_CAPSET	Sets the current value of the capability (single value only)
DTWAIN_CAPSETCURRENT	Sets the current values of the capability.(multiple values)
DTWAIN_CAPSETCONSTRAINT	Sets the current values of the capability (multiple values) (supported for TWAIN 2.x sources)
DTWAIN_CAPRESET	Sets the capability to the device's default value(s).

If SetType is DTWAIN_CAPSET, only a single value is used to set the capability. This is usually the case, since setting multiple values is usually not done. However, DTWAIN supports setting of multiple values using the DTWAIN_CAPSETCURRENT or DTWAIN_CAPSETCONSTRAINT constant. The capability will be set to the new value(s) found in the DTWAIN_ARRAY CapValues. If SetType is DTWAIN_CAPRESET the CapValues argument is ignored and should be NULL. The device's default values are usually the 'power-on' values for the device, but there really is no hard rule as to what the 'default' values really are.

The DTWAIN_ARRAY CapValues must be initialized before storing values by calling the DTWAIN_ArrayCreateFromCap function or DTWAIN_ArrayCreate function. The data type of CapValues must match the data type that Capability uses. For example, if Capability accepts LONGs, CapValues must be of type DTWAIN_ARRAYLONG. To ensure that CapValues is of the correct type, the DTWAIN_ArrayCreateFromCap function should be used to create a DTWAIN_ARRAY that will be of the correct data type for Capability. Alternately, you can initialize a DTWAIN_ARRAY with DTWAIN_ArrayCreate using the correct data type.

DTWAIN_SetCapValues always uses the 'safest' TWAIN Container when setting the values. If you desire to use a different TWAIN container type, use DTWAIN_SetCapValuesEx.

For the DTWAIN_SetCapValues function to return TRUE, the following must take place:

•	The Source must be opened.

•	The Source supports the capability and support setting current or available values. Some Sources allow setting current values, but not available values.

•	The values used to set the capability are valid (the values are processed by the Source).

•	The data type for the capability must be known by DTWAIN.

The DTWAIN_GetCapDataType function can be used to test if DTWAIN was successful in determining the data type of the capability when the TWAIN Source was initially opened. If DTWAIN_GetCapDataType returns a negative number, then you must use DTWAIN_SetCapValuesEx2, or set the data type in the DTWAIN32.INI file for the capability.

All standard TWAIN capabilities defined by the TWAIN 1.9 specification will have their data types known by DTWAIN. However, custom capabilities defined solely by the manufacturer of the TWAIN driver may or may not have their data types known to DTWAIN when the TWAIN Source is opened. Therefore DTWAIN_SetCapValuesEx2 should be used in this case, or use the low-level DTWAIN_CallDSMProc to set the capability.

The DTWAIN function DTWAIN_IsSourceOpen can be used to test the first condition.

The DTWAIN_IsCapSupported function can be used to test if the capability is supported. DTWAIN always checks if the capability is supported when the DTWAIN_SetCapValues function is called, however if the application knows beforehand that the capability is not supported, this will result in faster performance.

Example

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