DTWAIN_GetCapValues
|
The DTWAIN_GetCapValues function gets the capability value(s) for a Source.
DTWAIN_BOOL DTWAIN_GetCapValues (
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:
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 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.
TWAIN State Transitions The Source must be in State 4 or higher (depending on the capability).
Prerequisite Function Call(s) DTWAIN Source Selection Function
See Also |