Device Capabilities Questions

Q: I need to check if the Source supports a certain device capability.  How do I do this?

A: Use either the DTWAIN_IsCapSupported or DTWAIN_EnumSupportedCapsfunctions.

Q: TWAIN defines different container types such as TW_ONEVALUE, TW_RANGE, etc.  Using DTWAIN, should I get involved in knowing how to use the various types?

A: With DTWAIN, your application does not deal with the various TWAIN container types.  All capability values are stored in DTWAIN_ARRAY's, whether the values are being sent to the Source or retrieved from the Source (the TW_RANGE container type is mimicked by using DTWAIN_ARRAY's).

Q: I am calling DTWAIN_GetCapValues for a capability that returns multiple values if supported.  How do you get the values with DTWAIN?

A: All returned capability values are returned in the DTWAIN_ARRAY that your application provides to the DTWAIN_GetCapValues function.   To get the values use the various DTWAIN Array functions that are available such as DTWAIN_ArrayGetAt

Q: How do I know if the returned DTWAIN_ARRAY values from DTWAIN_GetCapValues represents a range instead of a list of values?

A: Call DTWAIN_GetCapContainer.  This function will return DTWAIN_CONTRANGE if the capability stores values as a TW_RANGE.  If the container used for the capability is TW_RANGE, the DTWAIN Range functions can be used on the returned DTWAIN_ARRAY.

Q: I want to call DTWAIN_SetCapValues, however the capability will be determined at runtime.  How do I know what type of data a certain capability will have so that I can set up the DTWAIN_ARRAY correctly?

A: Use the DTWAIN_ArrayCreateFromCap function to create a DTWAIN_ARRAY of the correct type:

DTWAIN_ARRAY CapValues;

...

CapValues = DTWAIN_ArrayCreateFromCap(DTWAIN_CV_CAPAUTHOR);

...

DTWAIN_SetCapValue(Source, AnyCap, DTWAIN_CAPSETCURRENT, CapValues);

Q: Why doesn't DTWAIN have separate functions for setting / getting each capability?

A: Two reasons. The first is that the DTWAIN library (DLL) will become extremely large if there were functions created to get or set every single TWAIN capability.  DTWAIN compensates for this by providing four functions: DTWAIN_GetCapValues, DTWAIN_GetCapValuesEx and DTWAIN_SetCapValues, DTWAIN_SetCapValuesEx.  This way, the library size is kept to a minimum.

The other reason is that the TWAIN specification is constantly changing.  If you are using an older version of DTWAIN, the ability to set or get a new capability defined by TWAIN will still be possible.  All you would have to do is use the appropriate TWAIN constant for the capability (Example :ICAP_XRESOLUTION), create the appropriate DTWAIN array to store/get the values, and call the appropriate DTWAIN_GetCap... or DTWAIN_SetCap... function.

Overall, it is not difficult to add functions on your own that get or set certain capabilities:

/* Assume that Source is an open Source.

  Set the Gamma value (which is a floating point value) */

DTWAIN_BOOL SetGammaValue(DTWAIN_FLOAT NewValue)

         DTWAIN_ARRAY NewValue;

         DTWAIN_BOOL bResult;

         /* return FALSE if not supported */

         if ( !DTWAIN_IsCapSupported(Source, DTWAIN_CV_ICAPGAMMA))

                         return FALSE;

         /* Create the array and assign the value to array */

         GammaValue = DTWAIN_ArrayCreateFromCap(DTWAIN_CV_ICAPGAMMA, 1);

         /* Set the gamma value in array */

         DTWAIN_ArraySetAt(GammaValue, 0, &NewValue);

         /* Set the cap */

         bResult = DTWAIN_SetCapValue(Source, DTWAIN_CV_ICAPGAMMA,

                                         DTWAIN_CAPSET, GammaValue);

         /* Destroy array and return */

         DTWAIN_ArrayDestroy(GammaValue);

         return bResult;

Q: The TWAIN specification defines a data type called TW_FIX32.  What is the equivalent DTWAIN type?

A: DTWAIN_FLOAT.  DTWAIN handles all translation issues from a regular floating-point number and the TW_FIX32 type defined by TWAIN.

Q: I need to set up a capability, but the data type that the capability supports is the TW_FRAME type.  How do I set up this type in DTWAIN?

A: Use the DTWAIN_FRAME type to define a TW_FRAME. If the capability supports multiple values, use the DTWAIN_ARRAYFRAME type to store/retrieve the DTWAIN_FRAMEs.

Q: I need to set a capability while the Source is in State 6or State 7 (currently acquiring an image).  When do I get a chance to call DTWAIN_SetCapValues or DTWAIN_GetCapValues in this case?

A: Capture the DTWAIN_TN_TRANSFERREADY (Source will transition from State 6 to State 7) and the DTWAIN_TN_TRANSFERDONE (Source will transition from State 7 to State 6) notifications. You can then call the appropriate DTWAIN Capability function within your handler.

Q: When calling DTWAIN_EnumSupportedCaps, the Source UI was enabled.  Why?

A: Some Sources do not have the ability to query the supported capabilities without going through an exhaustive search.  If DTWAIN has to do an exhaustive search for the supported capabilities, the Source UI may become enabled, but is immediately disabled when the Search terminates.

Q: I would like to set every supported capability to their default values.  How do I do this?

A: Call DTWAIN_SetAllCapsToDefault.

Q: I have written a Source, and I now want to thoroughly test the Source to check for bugs when setting or getting device capabilities.  To do this, I need to try different container types to check the Source's error handling.  Can DTWAIN allow the application to choose the TWAIN container to use?

A: Yes.  The DTWAIN_SetCapValuesEx and DTWAIN_GetCapValuesEx allow you to specify the container to use for the capability values.  These functions can be used for these purposes.  Note that these functions are advanced functions made for those who are sure of the container types to use for a particular capability. Specifying the wrong container type when setting or getting a capability in a Source that you did not develop may result in a General Protection Fault or throw an exception, so be very careful!

Q: I have a Source that supports custom device capabilities (capabilities greater than 16384).  Can DTWAIN allow setting and getting the values for custom capabilities?

A: Yes. Be aware that these capabilities are dependent on the manufacturer of the device.