DTWAIN_GetCapValuesEx2
|
The DTWAIN_GetCapValuesEx2 function gets the capability value(s) for a Source while specifying the TWAIN container type and TWAIN data type to use.
DTWAIN_BOOL DTWAIN_GetCapValuesEx2 (
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
TwainDataType Indicates the TWAIN data type to use.
CapValues 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_GetCapValuesEx2 function sets a Source's device capability.
Caution: DTWAIN_GetCapValuesEx2 is an advanced function and should be used only if you have full information (data type, container type, etc.) about a capability. Calling DTWAIN_GetCapValuesEx2 with the wrong data type or container type will result in undefined behavior (the application may crash, the TWAIN Source Manager may go in an infinite loop, etc.)
The difference between DTWAIN_GetCapValues and DTWAIN_GetCapValuesEx2 is that DTWAIN_GetCapValuesEx2 relies on the programmer to specify the TWAIN container to use and the TWAIN data type. The difference between DTWAIN_GetCapValuesEx and DTWAIN_GetCapValuesEx2 is that DTWAIN_GetCapValuesEx only allows you to specify the container type to use (DTWAIN determines the data type automatically).
Sometimes DTWAIN cannot determine the data type of certain capabilities, so DTWAIN_GetCapValuesEx2 is used for those programmers who have full information on how to retrieve a certain capability's values (usually this information concerning how to get the custom capability's values is given to the programmer by the manufacturer of the device).
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):
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.
The TwainDataType argument must be one of the following:
Integer-based types
TWTY_INT8 TWTY_UINT8 TWTY_BOOL TWTY_INT16 TWTY_INT32 TWTY_UINT16 TWTY_UINT32
String-based types
TWTY_STR32 TWTY_STR64 TWTY_STR128 TWTY_STR255 TWTY_STR1024
Floating-point type
TWTY_FIX32
Frame type
TWTY_FRAME
For the TwainDataType, the array type that will be created to store the return values depends on the TwainDataType that is specified. A table of the TwainDataType and the type of DTWAIN_ARRAY that will store the returned capability values is as follows:
For more information on parameter definitions see DTWAIN_GetCapValues.
Example:
The manufacturer of a TWAIN driver has given you the following information to get a custom capability that controls the padding within the image data:
Capability Name: ICAP_IMAGEPADDING Capability number: 0x8012 Capability Data Type : TW_UINT16 Capability Container Types: TW_ENUMERATION (get all values), TW_ONEVALUE (get current value and default value) Possible Values: 0 - Use Byte padding 1 - Use Word padding 2 - Use 8-byte padding (only supported for driver version 4.0) 3 - Use no padding 4 - Automatically determine padding
Assume we want to get all the possible values for this capability (and also assume we are running version 3.0 of the manufacturer's driver). First, we note that the capability number is 0x8012 (a hexadecimal number). The equivalent decimal number is 32786.
The next thing we note is that the capability's data type is TW_UINT16. This means that the DTWAIN_ARRAY that will be returned to us after DTWAIN_GetCapValuesEx2 is called will consist of LONG values (a DTWAIN_ARRAYLONG will be created).
Next, we note that the container type to use to retrieve all values is TW_ENUMERATION. This means that the DTWAIN_ARRAY will have one or more values within it.
Since we want to get all the values, the correct "get" type we use is DTWAIN_CAPGET.
Given this information to call DTWAIN_GetCapValuesEx2 to set the capability to get all the values is the following (C/C++ example): DTWAIN_SOURCE theSource; //... // Assume that theSource is pointing to a valid TWAIN Data Source... DTWAIN_ARRAY theValues; //... BOOL bOK = DTWAIN_GetCapValuesEx2( Source, 0x8012, DTWAIN_CAPGET, DTWAIN_CONTENUMERATION, DTWAIN_TWTY_UINT16, &theValues );
if ( bOK ) // values retrieved successfully { // output each value LONG value; LONG i; LONG nValues = DTWAIN_ArrayGetCount( theValues ); for ( i = 0; i < nValues; ++i ) { DTWAIN_ArrayGetAtLong( theValues, i, &value ); printf("%d\n", value); } //... DTWAIN_ArrayDestroy( theValues ); }
The code snippet above should output the following:
0 1 3 4
Note that '2' is missing from the output, since we are running version 3.0 of the manufacturer's driver, and the documentation from the manufacturer stated that '2' only exists for version 4.0 of the driver.
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 |