Setting and Getting Device Capabilities

Top  Previous  Next

To set the Source's device capabilities, the following functions are used:

DTWAIN_SetCapValues

DTWAIN_SetCapValuesEx

DTWAIN_SetCapValuesEx2

 

To retrieve a device's capability setting, the following functions are used:

DTWAIN_GetCapValues

DTWAIN_GetCapValuesEx

DTWAIN_GetCapValuesEx2

 

To check if a capability exists for a particular Source, the following functions are used:

DTWAIN_EnumSupportedCaps

DTWAIN_EnumExtendedCaps

DTWAIN_EnumCustomCaps

DTWAIN_IsCapSupported

 

In addition, you can get or set any capability using the low-level DTWAIN_CallDSMFunction using the DG_CONTROL/DAT_CAPABILITY/MSG_xxxx TWAIN triplet.  Please note that this function should only be used by persons familiar with TWAIN triplets and setting up the TWAIN triplet mechanism when making calls to the Data Source Manager.

 

Detailed steps in setting or retrieving capability values:

In general, the requirements to set or retrieve capability values with DTWAIN are as follows:

 

Determine the proper capability constant.
Check if the capability is supported by the Source.
Call DTWAIN_SetCapValues or DTWAIN_SetCapValuesEx to set the capability.  Call DTWAIN_GetCapValues, DTWAIN_GetCapValuesEx, or DTWAIN_GetCapValuesEx2_ to get capability values.

 

Determine the proper capability constant:

This requires the application programmer to decide which capability that needs to be set or retrieved.   For example, if the application needs to query the current unit of measure used by the Source, the capability constant to use would be DTWAIN_CV_ICAPUNITS.  A list of the capabilities and their data types are found here

 

Check if the capability is supported by the Source:

The next step is to determine if the capability constant is supported by the Source.   There are some capabilities that will not be supported by the Source, so the application may want to check if the capability is supported before proceeding to set or get capability values.  By default, DTWAIN always does a check for capability support whenever the DTWAIN_GetCapValues or DTWAIN_SetCapValues is called, but letting your application do the check results in faster code.  To check for capability support the DTWAIN_IsCapSupported function is used.

 

Now you must either set or get the capability values:

 

Setting Capability Values

a) Call DTWAIN_ArrayCreateFromCap to create the appropriate DTWAIN_ARRAY that matches the same data type as the capability.

b) Add the desired values to the DTWAIN_ARRAY that you want to set the capability to.

c) Call DTWAIN_SetCapValues to complete the process of setting the device's capability to your DTWAIN_ARRAY's values.

 

Getting Capability Values

a) Determine the data type for the capability values.  Use the DTWAIN_GetCapDataType function to get the correct data type.  The data types may be LONG's, DTWAIN_FLOAT's, etc.

b) Declare a DTWAIN_ARRAY. Do not call DTWAIN_ArrayCreateFromCap.

c) Call DTWAIN_GetCapValues to get the device capability values.  This function requires that the address of the DTWAIN_ARRAY from step 2) is passed as a parameter.

d) You can now extract the capability values from the DTWAIN_ARRAY declared in step 2 using the DTWAIN_ArrayGetAt function.  The data type that the extracted values are to be stored in was determined by step 1.

 

'C' Example of Getting Capabilities

'C' Example of Setting Capabilities