Appendix – Use Capability Negotiation

This article describes how to negotiate capabilities with different capability container types using Dynamic Web TWAIN. For an advanced sample, please check out this demo page. You can also download the source code here.

Description

Capabilities represent the features that a specified TWAIN source (e.g. a scanner) provides. In order to make full use of such a source/device, TWAIN applications needs to perform the operation called capability negotiation. With the negotiation, TWAIN applications can understand the source and then guide it to provide the images they would like to receive from it.

Capability Containers

Capabilities exist in many varieties but all have a Default Value, Current Value, and may have other values available that can be supported if selected. To help categorize the supported values into clear structures, TWAIN defines four types of containers for capabilities which are

Name of the Data Structure for the Container Type of Contents
TW_ONEVALUE A single value whose current and default values are coincident. The range of available values for this type of capability is simply this single value. For example, a capability that indicates the presence of a document feeder could be of this type.
TW_ARRAY An array of values that describes the current logical item. The available values may be a larger array of values. For example, a list of the names, such as the supported capabilities list returned by the CAP_SUPPORTEDCAPS capability, would use this type of container.
TW_RANGE Many capabilities allow users to select their current value from a range of regularly spaced values. The capability can specify the minimum and maximum acceptable values and the incremental step size between values. For example, resolution might be supported from 100 to 600 in steps of 50 (100, 150, 200, ..., 550, 600).
TW_ENUMERATION This is the most general type because it defines a list of values from which the Current Value can be chosen. The values do not progress uniformly through a range and there is not a consistent step size between the values. For example, if a Source's resolution options did not occur in even step sizes then an enumeration would be used (for example, 150, 400, and 600).

What is involved

To perform capability negotiation, you basically do two things

  • Get a Capability. This is used to ask the source about a specified capability and get its type, value, etc.
  • Set a Capability. This is generally used to request the source to set/change the value of a capability.

Now we'll talk about how to perform capability negotiation Before doing any capability negotiation, please keep in mind that it can only be done when the source is open (DataSourceStatus is 1). Basically, you need to use the methods SelectSource() and OpenSource() to select a TWAIN source and get it ready for the negotiation.

Get

To get information about a capability, you can simply use the following code snippet

DWObject.OpenSource();

DWObject.Capability = EnumDWT_Cap.***;

DWObject.CapGet();

var tempValue = '';

DWObject.CapValueType > 8?

/*STR*/
tempValue = DWObject.CapValueString
:
/*NUM*/
tempValue = DWObject.CapValue;

/*

* Special for BOOL

*/

if(DWObject.CapValueType == EnumDWT_CapValueType.TWTY_BOOL) {

DynamsoftCapabilityNegotiation.CurrentCapabilityHasBoolValue = true;

tempValue == 0 ? tempValue='FALSE' : tempValue='TRUE';

}
alert('The type of the capability is ' + DWObject.CapType); 
/*<a href="https://developer.dynamsoft.com/dwt/api-reference/capability-negotiation/captype/">More info</a>*/

alert('The value of the capability is ' + tempValue);

Set

Please NOTE that the container type and available values for a capability are generally dictated by the TWAIN source vendor. When you try to set a capability, you are basically just trying to change it so that it uses a different but available value. Therefore, we recommend that you try to 'get' the capability before you set it.

TW_ONEVALUE

To set a capability with TW_ONEVALUE container, the following steps are needed:

  • Set the Capability property to the capability to be negotiated;
  • Set the CapType property to TW_ONEVALUE (EnumDWT_CapType.TWON_ONEVALUE(5) ) (if you did CapGet() first, this step can be skipped);
  • Input the value that you'd like to set to this capability. Please NOTE that you can only set certain values (for example, only 'true' and 'false' are allowed for a capability with the CapValueType of TWTY_BOOL);
  • If the data type (CapValueType) of the capability is a string (EnumDWT_CapValueType.TWTY_STR32/64/128/255), set the value using the CapValueString property. Otherwise, set the value using the CapValue property;
  • Call CapSet() to actually set the value.
DWObject.OpenSource();
/*Make sure this Capability is TW_ONEVALUE*/
DWObject.Capability = EnumDWT_Cap.***;
/*Recommended*/
DWObject.CapGet(); 

DWObject.CapType = EnumDWT_TWAINCONTAINERTYPE.TWON_ONEVALUE;

DWObject.CapValueType > 8 ?

/*STR*/
DWObject.CapValue = someStringValue;
:
/*NUM*/
DWObject.CapValue = someNonStringValue;

DWObject.CapSet();

TW_ARRAY

TW_ARRAY capability container type can be used to set or return a group of associated individual values.

To set a capability with TW_ARRAY container, the following steps are needed:

  • Set the Capability property to the capability to be negotiated;
  • Set the CapType property to TWON_ARRAY (EnumDWT_CapType.TWON_ARRAY (3) ) (if you did CapGet() first, this step can be skipped);
  • Set the CapNumItems property to indicate how many items are in the array;
  • If the data type (CapValueType) of the capability is a string (EnumDWT_CapValueType.TWTY_STR32/64/128/255), set the value using the CapValueString property. Otherwise, set the value using the CapValue property;
  • Call CapSet() to actually set the value.
DWObject.OpenSource();
/*Make sure this Capability is TWON_ARRAY*/
DWObject.Capability = EnumDWT_Cap.***; 
/*Recommended*/
DWObject.CapGet(); 

DWObject.CapType = EnumDWT_TWAINCONTAINERTYPE.TWON_ARRAY;

DWObject.CapNumItems = *;

if(DWObject.CapValueType > 8 ){

/*STR*/

DWObject. SetCapItemsString (0, someStringValue);

DWObject. SetCapItemsString (1, someStringValue);

…

} else {

/*NUM*/

DWObject. SetCapItems(0, someNonStringValue);

DWObject. SetCapItems(1, someNonStringValue);

…

}

DWObject.CapSet();

TW_RANGE

TW_RANGE capability container type can be used to set or return a range of individual values describing a capability. The values are uniformly distributed between a minimum and a maximum value. The step size between every two values is constant.

To set a capability with TW_RANGE container, the following steps are needed:

DWObject.OpenSource();
/*Make sure this Capability is TWON_RANGE*/
DWObject.Capability = EnumDWT_Cap.***; 
/*Recommended*/
DWObject.CapGet(); 

DWObject.CapType = EnumDWT_TWAINCONTAINERTYPE.TWON_RANGE;

DWObject.CapMinValue = 80;

DWObject.CapMaxValue = 200;

DWObject.CapStepSize = 20;

DWObject.CapCurrentValue = 100;

DWObject.CapSet();

TW_ENUMERATION

TW_ENUMERATION capability container type can be used to set or return a group of associated individual values describing a capability. The values are ordered from the lowest to highest values, but the step size between every two values is probably not uniform.

To set a capability with TW_ENUMERATION container, the following steps are needed:

  • Set the Capability property to the capability to be negotiated;
  • Set the CapType property to TWON_ARRAY (EnumDWT_CapType.TWON_ENUMERATION (4) ) (if you did CapGet() first, this step can be skipped);
  • Set the CapNumItems property to indicate how many items are in the array;
  • If the data type (CapValueType) of the capability is a string (EnumDWT_CapValueType.TWTY_STR32/64/128/255), set the value using the CapValueString property. Otherwise, set the value using the CapValue property;
  • Set the CapCurrentIndex to indicate the index of the current value;
  • Call CapSet() to actually set the value.
DWObject.OpenSource();
/*Make sure this Capability is TWON_ENUMERATION*/
DWObject.Capability = EnumDWT_Cap.***; 
/*Recommended*/
DWObject.CapGet(); 

DWObject.CapType = EnumDWT_TWAINCONTAINERTYPE.TWON_ENUMERATION;

DWObject.CapNumItems = *;

if(DWObject.CapValueType > 8 ){

/*STR*/

DWObject. SetCapItemsString (0, someStringValue);

DWObject. SetCapItemsString (1, someStringValue);

…

} else {

/*NUM*/

DWObject. SetCapItems(0, someNonStringValue);

DWObject. SetCapItems(1, someNonStringValue);

…

}

DWObject.CapCurrentIndex = 1;

DWObject.CapSet();

Using a custom capability that the TWAIN Specification doesn't have

Some TWAIN sources come with their own custom capabilities that are only supported by their corresponding devices. In such cases, you can refer to the following KB article on how to make use of these capabilities. https://developer.dynamsoft.com/dwt/kb/2724

Is this page helpful?

Leave a Reply

Your email address will not be published.