DTWAIN_GetCapValuesEx2

Top  Previous  Next

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 (

DTWAIN_SOURCE

Source,

LONG

Capability,

LONG

GetType,

LONG

Container,

LONG

TwainDataType,

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.

 

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):

 

DTWAIN_Container

Value

TWAIN Equivalent

DTWAIN_CONTARRAY

8        

TW_ARRAY

DTWAIN_CONTENUMERATION

16        

TW_ENUMERATION

DTWAIN_CONTONVALUE

32        

TW_ONEVALUE

DTWAIN_CONTENUMERATION

64        

TW_RANGE

 

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:

 

TwainDataType

DTWAIN Data Type

DTWAIN_ARRAY type

 

TW_INT8

TW_UINT8

TW_BOOL

TW_INT16

TW_INT32

TW_UINT16

TW_UINT32

DTWAIN_TWTY_INT8

DTWAIN_TWTY_UINT8

DTWAIN_TWTY_BOOL

DTWAIN_TWTY_INT16

DTWAIN_TWTY_INT32

DTWAIN_TWTY_UINT16

DTWAIN_TWTY_UINT32

 

DTWAIN_ARRAYLONG

 

TW_STR32

TW_STR64

TW_STR128

TW_STR255

TW_STR1024

 

DTWAIN_TWTY_STR32

DTWAIN_TWTY_STR64

DTWAIN_TWTY_STR128

DTWAIN_TWTY_STR255

DTWAIN_TWTY_STR1024

 

DTWAIN_ARRAYSTRING

 

TW_FIX32

 

DTWAIN_TWTY_FIX32

 

DTWAIN_ARRAYFLOAT

 

TW_FRAME

 

DTWAIN_TWTY_FRAME

 

DTWAIN_ARRAYFRAME

 

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_SysInitialize

 

DTWAIN Source Selection Function

 

 

See Also

Setting / Getting Twain Capabilities