Conversion of Values to the Expected Type When Setting a Capability

When setting a capability using the ImGearCap classes and the ImGearTWAIN.SetCapability method, ImageGear .NET and ImageGear for Silverlight will attempt to convert the value to the data type of the capability that is specified in the TWAIN specification (FIX32, UINT16, STR128, and etcetera). This conversion logic is implemented differently between ImageGear .NET TWAIN and ImageGear for Silverlight TWAIN. Not only does it behave differently, but it also occurs at different times.

In ImageGear .NET, the conversion takes place in the property setters of the properties of the ImGearCap sub classes. These properties include:

ImGearCapOneValueFloat.Value
ImGearCapOneValueString.Value
ImGearCapRange.CurrentValue
ImGearCapRange.DefaultValue
ImGearCapRange.MinValue
ImGearCapRange.MaxValue
ImGearCapRange.StepSize
ImGearCapArray.this[]

Additionally, conversion takes place in the following method:

ImGearCapArray.Add

This logic is pretty strict about enforcing the type of the capability specified in the TWAIN specification. For instance if the calling code is trying to set the value of a FIX32 capability (say ICAP_CONTRAST), but the calling code is trying to set this with a string value, then ImageGear .NET will try to convert that string to a FIX32 value. If the conversion fails, then an exception will be thrown. The following code demonstrates this.

C#	Copy Code
ImGearCapOneValue capContainer = new ImGearCapOneValue (ImGearCapabilities.ICAP_CONTRAST); // A capContainer.Value = "100"; // B: this converts successfully capContainer.Value = "one-hundred"; // C: this does not convert successfully and an exception is thrown imGearTwain.SetCapability(capContainer, ImGearMessages.SET); // D

Copy Code

ImGearCapOneValue capContainer =
new ImGearCapOneValue (ImGearCapabilities.ICAP_CONTRAST); // A
capContainer.Value = "100"; // B: this converts successfully
capContainer.Value = "one-hundred"; // C: this does not convert successfully and an exception is thrown
imGearTwain.SetCapability(capContainer, ImGearMessages.SET); // D

So code line B executes successfully, because the string "100" could successfully be converted to a FIX32 value. Code line C does not convert successfully because the string "one-hundred" could not successfully be converted to a FIX32.

Also note that if we had removed code line C, then code line D would execute. This call actually sets the value of the capability on the device, so there is also a chance here that the method throws if the value 100 was not legal for the capability, or the capability could not be set on the device.

In ImageGear for Silverlight, conversion takes place only in the call to SetCapability. Furthermore, the conversion only converts from strings to strings of the expected length, and from numeric values to numeric values of the expected type. If a user is attempting to set the value of a FIX32 capability using a string, then SetCapability will attempt to set the value of that capability using a string (resulting in an exception only if the data source returns an error code). The following code demonstrates this.

C#	Copy Code
ImGearCapOneValueString capContainer = new ImGearCapOneValueString(ImGearCapabilities.ICAP_CONTRAST); // A capContainer.Value = “100”; // B: the property is set as expected, but no conversion is done imGearTwain.SetCapability(capContainer); // D: no conversion, attempts to set capability

Copy Code

ImGearCapOneValueString capContainer =
new ImGearCapOneValueString(ImGearCapabilities.ICAP_CONTRAST); // A
capContainer.Value = “100”; // B: the property is set as expected, but no conversion is done
imGearTwain.SetCapability(capContainer); // D: no conversion, attempts to set capability

So, comparing this to the behavior of ImageGear .NET, in line B there is no conversion in ImageGear for Silverlight, but there is in ImageGear .NET. In line D, ImageGear for Silverlight looks at the container type and since it is a string, it will attempt to set the capability to a string value. If the data source returns an error in this case, then an exception will be thrown. The next code example demonstrates how the conversion actually works in ImageGear for Silverlight. This code is setting the value of a FIX32 capability using a float.

C#	Copy Code
ImGearCapOneValueFloat capContainer = new ImGearCapOneValueFloat(ImGearCapabilities.ICAP_CONTRAST); // A capContainer.Value = 100f; // B: the property is set as expected, but no conversion is done imGearTwain.SetCapability(capContainer); // D: conversion of 100f to a FIX32 value

Copy Code

ImGearCapOneValueFloat capContainer =
new ImGearCapOneValueFloat(ImGearCapabilities.ICAP_CONTRAST); // A
capContainer.Value =  100f; // B: the property is set as expected, but no conversion is done
imGearTwain.SetCapability(capContainer); // D: conversion of 100f to a FIX32 value

In code line D, the float value 100f is converted to a FIX32 value and the value is set on the data source. This line could still throw an exception if 100f was an illegal value for ICAP_CONTRAST for the data source and the data source returned an error.