DTWAIN_GetCapValues

Top Previous Next

The DTWAIN_GetCapValues function gets the capability value(s) for a Source.

DTWAIN_BOOL DTWAIN_GetCapValues (

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

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_GetCapValues function gets a Source's device capability setting. On successful return, the values for the capability are stored in the DTWAIN_ARRAY located at the address pCapValues.

Please note: If you are getting the value(s) supported from

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_GetCapValuesEx2 function instead of DTWAIN_GetCapValues.

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 retrieved. A list of the capabilities as well as the capabilities data type can be found in the topic DTWAIN Capability Constants.

The GetType determines whether the capability value that will be retrieved is the current value, default value, or all the values supported by the capability. The values of GetType can be one of the following:

SetType	Definition
DTWAIN_CAPGET	Gets the value(s) of the capability.
DTWAIN_CAPGETCURRENT	Gets the current value of the capability.
DTWAIN_CAPGETDEFAULT	Gets the default value of the capability.

The DTWAIN_ARRAY located at address pCapValues will be initialized and filled with the returned capability values. The DTWAIN_ARRAY does not have to be initialized created with DTWAIN_ArrayCreate. If the DTWAIN_ARRAY located at pCapValues has been created and contains values prior to calling DTWAIN_GetCapValues, the elements will be destroyed.

On return, the application must check the type of data that the DTWAIN_ARRAY holds to make sure that the values are extracted to the proper data type. To get the data type, use the DTWAIN_ArrayGetType function.

DTWAIN_GetCapValues always uses the 'safest' TWAIN Container when getting the values. If you desire to use a different TWAIN container type, use the DTWAIN_GetCapValuesEx function.

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

•	The Source must be opened.

•	The Source supports 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_GetCapValues 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