ImageMan.Net Twain
Working with TWAIN Capabilities
See Also Send Feedback on this topic
ImageMan.Net Twain > Getting Started > Working with TWAIN Capabilities

Glossary Item Box

What Are Capabilities ?

Capabilities are used by TWAIN drivers and applications to control the scanning device and the attributes of images to be acquired.

 

Using the NegotiateCapability, GetCapability and SetCapability methods your application can:

 

Querying a Capability

The GetCapability method is used to get the supported values for a given capability. Two versions of the GetCapability method exist differing only in how the first parameter is typed. One method takes a long as the first parameter, the other takes an enumeration of type Capabilities.

 

The next two parameters are passed by reference and are used to return information from the method. The CapabilityValue parameter will contain an object which encapsulates the value(s) of the capability. The dataType parameter returns the type of the object returned in the capabilityValue parameter.

 

The method returns True if the capability was successfully queried otherwise False is returned and the LastError property contains an Error object which describes the error that occurred.

 

The capabilityValue parameter will contain an object returned from the method which will correspond to the type of the dataType parameter. Some capabilities return an object containing a single value such as an Int32, while others may return RangeEnumeration or Array objects which contain the values returned by the method call.

 

 

Your code that calls the GetCapability method will need to look at the dataType parameter in order to determine the type of the returned object and access it appropriately.

 

C# Copy Code
DataType type;
Object obj;

bool retval = twainControl1.GetCapability( Capabilities.Brightness, out obj, out type );

if ( retval ) 
{
    switch( type )
    {
        case DataType.Enumeration:
            Console.WriteLine( "Got an Enumeration" );
            break;

        case DataType.Array:
            Console.WriteLine( "Got an Array" );
            break;

        case DataType.Range:
            Console.WriteLine( "Got a Range" );
            break;

        default:
            Console.WriteLine( "Got a " + type.ToString() );
            break;
  }
}

 

 

Visual Basic Copy Code
Dim vt As DTI.ImageMan.Twain.DataType
Dim obj As Object

Dim retval As Boolean = TwainControl1.GetCapability(DTI.ImageMan.Twain.Capabilities.Brightness, obj, vt)

If retval Then
    Select Case vt
        Case DTI.ImageMan.Twain.DataType.Enumeration
            Console.WriteLine("Got an Enumeration")
  
        Case DTI.ImageMan.Twain.DataType.Array
            Console.WriteLine("Got an Array")
  
        Case DTI.ImageMan.Twain.DataType.Range
            Console.WriteLine("Got a Range")
  
        Case Else
            Console.WriteLine("Got a " + vt.ToString())
    End Select
End If

Setting Scanner Capabilities

The process of setting a value for a capability involves several steps, first the application should call GetCapability to see if the capability is supported and also to get the supported values. Based on the supported values the application can then call SetCapability to set the capability to the desired value. Its up to the application to decide which of the supported values is closest to the desired value in case the device can't support the specific value desired. The application must also deal with the various data types supported by the TWAIN specification when calling these methods.

 

To simplify this process, the TwainControl provides the NegotiateCapability method which does the negotiation and data type conversion automatically simplifying your application's code.

 

Setting a Capability using NegotiateCapability

The NegotiateCapability method is used to set a capability to a given value or the closest value supported by the device. The capability to be set is specified as the first parameter and the the value is passed as the second parameter.

 

If the method succeeds it will return True otherwise it will return False and the LastError property will contain an Error object which describes the error.

 

C# Copy Code
bool obj = true;

bool retval = twainControl1.NegotiateCapability( Capabilities.AutoFeed, true ); 

 

Visual Basic Copy Code
Dim obj As bool = True 

bool retval = TwainControl1.NegotiateCapability( Capabilities.AutoFeed, true ) 

 

Setting a Capability using SetCapability 

The SetCapability method is used to set a capability to a given value. The capability to be set is specified as the first parameter and the object containing the value itself is passed as the second parameter, the final parameter is the TWAIN data type of the value passed as the third parameter.

 

If the method succeeds it will return True otherwise it will return False and the LastError property will contain an Error object which describes the error.

 

C# Copy Code
bool obj = true;

bool retval = twainControl1.SetCapability( Capabilities.AutoFeed, true, DataType.Bool ); 

 

Visual Basic Copy Code
Dim obj As bool = True 

bool retval = TwainControl1.SetCapability( Capabilities.AutoFeed, true, DataType.Bool ) 

 

See Also