Twain Containers and Capabilities Explained

Capability

A Twain capability is simply a setting the scanner supports. The thought process is, “Is a scanning device capable of … (Fill in the blank).” If so, then it supports that capability. I’m only guessing at the origin, but that sounds pretty close.

Each scanning device supports different capabilities. There are only five that are required to be supported in the Twain Specification:

• CAP_XFERCOUNT
  
• ICAP_COMPRESSION
  
• ICAP_PIXELTYPE
  
• ICAP_UNITS
  
• ICAP_XFERMECH

Each of these, along with all the other standard capabilities, are defined in the Twain Specification under Chapter 9. The specification tells you what the possible values are for each capability and what each capabilty’s datatype is.

Some manufacturers will define their own capabilities that are specific for their devices. These capabilities are referred to as custom capabilities. For documentation on these types of capabilities you will need to consult the manufacturer’s help files.

LEADTOOLS has the ability to obtain the current value, default value, or all possible values for any capability (custom or standard).

Containers (Getting and Setting Capabilities)

There are four Twain containers:

1. One Value
   
2. Enumeration
   
3. Array
   
4. Range

Each hold the value(s) of a capability and are used with both standard and custom capabilities.

LEADTOOLS provides functions to retrieve information about a capability and to set value(s) to the capability.

The TwainSession.GetCapability function allows you retrieve information about any capability. You can retrieve the current value, the default value, or all possible values the capability supports.

When you retrieve either the current or default value for a capability, there will simply be one value that is returned, so the Twain driver will deliver this to you in a One Value container.

When you retrieve all possible values they will be returned to you in a Range, Array, or Enumeration container.

The Enumeration container provides a list of values and tells you what the default and current value is from the list. When you query all possible values for the ICAP_PIXELTYPE capability this is typically returned in an Enumeration container. It tells you the color format(s) the device supports (eg. Rgb, Gray, Black and White, etc). It tells you which format is currently being used, and which format is the default (or startup setting) format.

The ICAP_XRESOLUTION capability is typically returned in a Range Container. This container will tell you the minimum and maximum values for the capability and the step size (or incremental value). Add the step size to the minimum value to find the next value in the range. You can do this up to the maximum value. This container also tells you the current and default values for this capability.

The Array container is similar to the Enumeration container except it does not contain a current and default value. This is because the capability does not actually do anything other than provide a list of values. The ICAP_SUPPORTEDCAPS is one such capability. This simply list for you all the capabilities the driver supports.

Note that if the driver only supports one value (such as only being able to acquire in Black and White) then when you ask for all possible values, it may only return a One Value container because it only has one value to return.

The TwainSession.SetCapability function is typically used to alter the current value of a capability. You may use it to adjust the current value for the ICAP_PIXELTYPE, going from Black and White to RGB, or you may use to adjust the ICAP_XRESOLUTION, going from 150 to 300. In all cases, you are simply wanting to adjust one value. So in all cases you would use the One Value container to adjust that one value.

There are some cases where the scanner offers more options than you would like for your users to have. For instance, some scanners may support scanning at resolutions as high as 1200 DPI. While this is impressive, you will quickly fill up your available space scanning at such a high resolution if a user were to accidently choose this option.

You can tell the device to show a subset of its supported values using the SetCapability function and either the Enumeration container or the Range container.
Let’s say the device returned a Range container with the following values for the ICAP_XRESOLUTION capability:

• MinimumValue = 50
  
• MaximumValue = 1200
  
• StepSize = 1
  
• CurrentValue = 100
  
• DefaultValue = 100

You can modify these values to be:

• MinimumValue = 100
  
• MaximumValue = 300
  
• StepSize = 100
  
• CurrentValue = 300
  
• DefaultValue = 300

You can then call SetCapability with these values. When the scanner’s UI is shown or the next time you call GetCapability asking for all possible values, these will be the only values returned or listed.

To reset the capability back to its original values, you would use SetCapabiilty passing the Reset flag.

Note: You must use the container the driver returns to you. If you ask the driver to give you all the values it supports for ICAP_XRESOLUTION and it gives you an Enumeration container, you cannot use a Range container to then limit the values displayed.

Note: You cannot use values outside the range of values the driver supports. In the above example you cannot set the maximum value to be any greater than 1200 or the minimum value to be any less than 50. You can only limit the driver to a subset of the values it supports.

You can use the Enumeration container to do this as well. Let’s say you ask the driver for all possible values for the ICAP_PIXELTYPE capability and it returns to you an enumeration container containing the list:

• TWPT_BW
  
• TWPT_RGB
  
• TWPT_PALETTE
  
• TWPT_GRAY

You can adjust this list to only include TWPT_BW and TWPT_RGB. You must also adjust the current and default values to be one of the values in your new list as well.
After setting this list, the driver will only return these values in the list until SetCapability is called with the Reset flag.

Chapter 9 of the Twain specification will also let you know which containers could possibly be returned for each standard capability and which ones you could use to set the capability with. Most scanners will only return one of the possible containers in the list when asking for all possible values. You must use that same container to limit the possible values displayed as well. All capabilities should support the One Value container for both retrieving and setting the current value (unless the capability is a read only capability, which is also detailed in Chapter 9 of the specification.)

Be aware, however, that some drivers will not return a One Value container when the current flag is used and may instead return one of the other containers. It is best to always check the container type before processing the returned value.

Edited by moderator Tuesday, March 13, 2018 9:40:52 AM(UTC)  | Reason: Updated hyperlinks/formatting