Set Capabilities

Capabilities can only be modified, or set, after a TWAIN Session has been opened (OpenSession), and prior to initiating the scanning session (StartSession).

Identifying Capabilities

TWAIN specifies some capabilities to be basic (Capability) and some to be advanced (AdvancedCapability). TwainPRO™ methods are overloaded to support both. An overload is also provided to enable the application to access a capability that is not enumerated in the TwainPRO interface, by specifying an integer value.

Check that the Capability is supported by the Data Source

To determine whether the capability of interest is supported by the TWAIN device, call IsCapabilitySupported.

Set the Capability

If the capability is supported by the TWAIN device, call SetCapability. TWAIN defines four types of containers used to negotiate values between the application and the source device:

One Value: The current value is returned.
Enum: A list of legal values along with the current and default values are returned.
Range: A range of legal values along with the current and default values are returned.
Array: A list of values is returned.

The SetCapability method takes as a parameter a CapabilityContainer object. The CapabilityContainerOneValue, CapabilityContainerEnum, CapabilityContainerRange, and CapabilityContainerArray objects can be filled with information and passed to this method to set the value of the container.

C# Example	Copy Code
// This code demonstrates setting a single value using the TWON_ONEVALUE container Accusoft.TwainProSdk.CapabilityContainerOneValueFloat myCap = new CapabilityContainerOneValueFloat(Capability.TwonBitDepth); myCap.Value = (float)CapabilityConstants.TwptBW; twainDevice.SetCapability(myCap);

C# Example

Copy Code

// This code demonstrates setting a single value using the TWON_ONEVALUE container
Accusoft.TwainProSdk.CapabilityContainerOneValueFloat myCap = new CapabilityContainerOneValueFloat(Capability.TwonBitDepth);
myCap.Value = (float)CapabilityConstants.TwptBW;
twainDevice.SetCapability(myCap);

The other containers can be used to set a new range or set of legal values for a capability. These can be used to restrict the choices available to a user when the UI is presented.

C# Example	Copy Code
// This code demonstrates how to request that the Data Source only allow resolutions in the range of 100 to 400 dpi (assuming the ICAP_UNITS capability is set to inches) Accusoft.TwainProSdk.CapabilityContainerRange myCap = new CapabilityContainerRange(Capability.IcapXResolution); myCap.Value = 100; myCap.Minimum = 100; myCap.Maximum = 400; twainDevice.SetCapability(myCap);

C# Example

Copy Code

// This code demonstrates how to request that the Data Source only allow resolutions in the range of 100 to 400 dpi (assuming the ICAP_UNITS capability is set to inches)

Accusoft.TwainProSdk.CapabilityContainerRange myCap = new CapabilityContainerRange(Capability.IcapXResolution);
myCap.Value = 100;
myCap.Minimum = 100;
myCap.Maximum = 400;
twainDevice.SetCapability(myCap);

Sources are not required to allow their values to be restricted by the application, so support of this feature varies widely. Some devices will ignore these parameters completely, while others may only allow it for certain capabilities. For instance, a device may allow ICAP_PIXELTYPE to be restricted to black and white images, but won’t allow ICAP_XRESOLUTION to be restricted to the range shown in the above example.