DTWAIN_SetCapValuesEx2
|
The DTWAIN_SetCapValuesEx2 function sets the capability value(s) for a Source while specifying the TWAIN container type and TWAIN data type to use.
DTWAIN_BOOL DTWAIN_SetCapValuesEx2 (
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.
Container Indicates the TWAIN container to use
TwainDataType Indicates the TWAIN data type to use.
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_SetCapValuesEx2 function sets a Source's device capability.
Caution: DTWAIN_SetCapValuesEx2 is an advanced function and should be used only if you have full information (data type, container type, etc.) about a capability. Calling DTWAIN_SetCapValuesEx2 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_SetCapValues and DTWAIN_SetCapValuesEx2 is that DTWAIN_SetCapValuesEx2 relies on the programmer to specify the TWAIN container to use and the TWAIN data type. The difference between DTWAIN_SetCapValuesEx and DTWAIN_SetCapValuesEx2 is that DTWAIN_SetCapValuesEx 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 custom capabilities, so DTWAIN_SetCapValuesEx2 is used for those programmers who have full information on how to set a certain capability's values (usually this information concerning how to set the capability's values is given to the programmer by the manufacturer of the device in the form of a C/C++ header file or some other documentation).
The arguments to DTWAIN_SetCapValuesEx2 are the same as DTWAIN_SetCapValuesEx, with the following additional parameter, TwainDataType.
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 set the capability's values depends on the TwainDataType that is specified. A table of the TwainDataType and the type of DTWAIN_ARRAY that must be created by the application is as follows:
Please note that the TwainDataType and the DTWAIN Data Type can be used interchangeably, since the values are equivalent.
For more information on parameter definitions see DTWAIN_SetCapValues.
Example:
The manufacturer of a TWAIN driver has given you the following information to set 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 Type: TW_ONEVALUE Possible Values: 0 - Use Byte padding 1 - Use Word padding 2 - Use 8-byte padding 3 - Use no padding 4 - Automatically determine padding
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 we will need to use to set our values will be one of type DTWAIN_ARRAYLONG.
Next, we note that the container type is a TW_ONEVALUE. This means that the capability can only be set with a single value, therefore our DTWAIN_ARRAY will have only one item in it. That item will be one of the possible values listed in the "Possible Values" section.
Given this information to call DTWAIN_SetCapValuesEx2 to set the capability to use no padding (value = 3): DTWAIN_SOURCE theSource; //... // Assume that theSource is pointing to a valid TWAIN Data Source... // create a DTWAIN_ARRAY that will store long values. Also, create it with room for one item. DTWAIN_ARRAY theValues = DTWAIN_ArrayCreate(DTWAIN_ARRAYLONG, 1);
// Now set the item in the DTWAIN_ARRAY to 3 DTWAIN_ArraySetAtLong( theValues, 0, 3 );
// Call function to set the capability BOOL bOK = DTWAIN_SetCapValuesEx2( Source, 0x8012, DTWAIN_CAPSET, DTWAIN_CONTONEVALUE, DTWAIN_TWTY_UINT16, theValues );
if ( bOK ) // value set successfully { // The value was set successfully } // Dispose of the array DTWAIN_ArrayDestroy( theValues );
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 |