Example - Overriding Source Capability Negotiation using Initialization File

Here is an example of a typical DTWAIN INI file that has been customized to handle an Epson and HP scanner.:

[AllSources]

QUERYSUPPORT=1

;--------------------------------------------------------------------------------------------------------------------

; Define the Epson scanner and any overrides

[Epson Scanner]

; Define the containers to use for the ICAP_FRAMES capability

ICAP_FRAMES=TW_ONEVALUE,TW_ONEVALUE,TW_ONEVALUE,TW_ONEVALUE,TW_ONEVALUE

; Define the containers to use for the CAP_SUPPORTEDCAPS capability

CAP_SUPPORTEDCAPS=TW_ENUMERATION,0,0,0,0

;Define the states that ICAP_FRAMES can be negotiated

ICAP_FRAMES_STATES=5,6,7

;Define the states that ICAP_MAXFRAMES can be negotiated

ICAP_MAXFRAMES_STATES=5,6,7

;Let DTWAIN know that the Epson Source doesn't support DG_CONTROL/DAT_IDENTITY/ MSG_QUERYSUPPORT triplet

QUERYSUPPORT=0

;----------------------------------------------------------------------------------------------------------------------

;Define the HP Scanner and any overrides

[HP Scanner]

; Define the containers to use for the ICAP_XRESOLUTION and ICAP_YRESOLUTION, respectively

ICAP_XRESOLUTION=TW_ARRAY,TW_ONEVALUE,TW_ONEVALUE,TW_ONEVALUE,0

ICAP_YRESOLUTION=TW_ARRAY,TW_ONEVALUE,TW_ONEVALUE,TW_ONEVALUE,0

; Define the custom capability 0x8030 that the HP Scanner has available

CUSTOMBASE+48_DATATYPE=TWTY_BOOL

CUSTOMBASE+48_STATES=5,6,7

The first section, [AllSources] has the QUERYSUPPORT=1 setting.  This means that for all Sources, DTWAIN will issue the DG_CONTROL / DAT_CAPABILITY / MSG_QUERYSUPPORT triplet to determine a capability's supported actions.  Note that later on in this example, one particular source (Epson_Scanner) will override this behavior for itself.

The next sections describe behavior related to two Data Sources; the "Epson Scanner" and "HP Scanner".  The [Epson Scanner] section is the correct way to start the custom definitions for the Epson Scanner.  This assumes that "Epson Scanner" is the actual Product Name of the scanner.  The Product Name is the same name that appears in the TWAIN Select Source dialog.  Similarly, the [HP Scanner] section starts the definition of the HP Scanner.

For the "Epson Scanner" source, there are two capabilities that are defined that need to be overridden.  The first is ICAP_FRAMES, and the second is CAP_SUPPORTEDCAPS.  For ICAP_FRAMES, the MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT, SETCURRENT and SETAVAILABLE should all use the TW_ONEVALUE container.  For CAP_SUPPORTEDCAPS, the MSG_GET container is TW_ENUMERATION (in the Twain 1.8 specification this should be TW_ARRAY, but the source is not compliant and uses TW_ENUMERATION).  The rest of the values are 0 to denote that the MSG_GETCURRENT, MSG_GETDEFAULT, SETAVAILABLE, and SETCURRENT options are not available for this capability.

The "Epson Scanner" Source also has a problem when ICAP_FRAMES or ICAP_MAXFRAMES is being negotiated in state 4 (Source is open).  This should not be an error, but the Source does not behave properly for state 4 negotiation of these capabilities.  By including the ICAP_FRAMES_STATES and ICAP_MAXFRAMES_STATES in the settings for Epson Scanner, we can control which states are valid for negotiating these capabilities.  Note that the data is 5,6,7 meaning that states 5, 6, and 7 are valid states where negotiating these capabilities are safe.  Since 4 is not specified as a valid state, DTWAIN will not attempt to negotiate the ICAP_FRAMES and ICAP_MAXFRAMES capability when the Epson Scanner source is in state 4.

The QUERYSUPPORT setting is 0, which means that the Epson Scanner Source does not support the MSG_QUERYSUPPORT operation.  This overrides the [AllSources] value of 1 for QUERYSUPPORT, but only for the Espson Scanner.

For the "HP Scanner", the ICAP_XRESOLUTION and ICAP_YRESOLUTION capabilities are defined.  The GET uses a TW_ARRAY, and the GETCURRENT, GETDEFAULT, SETCURRENT, uses a TW_ONEVALUE.  The SETAVAILABLE is not defined for this capability.   Since there is no QUERYSUPPORT setting in the HP Scanner section, the setting in the [AllSources] section is used.

Also, the "HP Scanner" has a custom capability, with a number of 0x8030 (a hexadecimal number).  The hexadecimal number 0x8030 is equivalent to 32816 in decimal.  Since the rule for specifying custom capabilities is to subtract the capability number from 32768, the subtraction (32816 - 32768) gives us 48.  Therefore the CUSTOMBASE has 48 added to it in the following way:

CUSTOMBASE+48

This serves as the capability name to use when specifying custom capability 0x8030.  Note that we have set the datatype (using the _DATATYPE appended to the capability name), and we have specified the states that capability 0x8030 can be negotiated in using the _STATES appened to the name.