Getting and Setting Capabilities

Each TWAIN source may support a number of capabilities. These capabilities dictate the behavior of the TWAIN source. Before acquiring images from the selected TWAIN source, the user may wish to examine and change the capability settings for that source.

It is possible to check whether the installed scanner to the system supports certain capabilities. For more information, refer to How to Find Out Whether Your Scanner Supports Certain Capabilities Using Twacker, found on http://support.leadtools.com/SupportPortal/cs/forums/3781/ShowPost.aspx.

To begin this period of getting and setting the TWAIN source capabilities, the user must call L_TwainStartCapsNeg. The LEADTOOLS TWAIN toolkit provides the user low-level and high-level functionality for getting and setting the capabilities.

LEADTOOLS provides both low-level and high-level functions for getting and setting capabilities. The low-level functions get and set capabilities individually. The high-level functions let the user get and set specific capabilities, either singularly, or in groups.

Low-Level:

• Each capability is retrieved or set using a container.  For information on working with containers please refer to How to Work with the Containers.  When setting a capability, use the TW_ONEVALUE container to modify a capability's current value.  Use the other containers to limit a capability's possible values to a subset of the available values.

• To get information about the capabilities supported by the selected TWAIN source, call the L_TwainEnumCapabilities function. For each capability enumerated by L_TwainEnumCapabilities, this function will call the LTWAINCAPABILITYCALLBACK callback function. Within this callback function the user can process the capability information.

• To get information on a specific capability (current, default, or all possible values) call L_TwainGetCapability. This function gets information about the capability specified in a TW_CAPABILITY structure. For more information about TW_CAPABILITY, refer to the TWAIN 1.9 specification from the site "http://www.twain.org/".

• To set a specific capability to a new value or to reset the value of a capability to the default value, call L_TwainSetCapability.

High-Level:

• L_TwainGetProperties and L_TwainSetProperties allow the user to set and get a number of capabilities through the LTWAINPROPERTIES structure. If this structure does not have the capability needed to negotiate, the user may use the low-level functions to do so.

• The L_TwainQueryProperty function lets the user get the available values for a specific capability from the selected source.

• There are several transfer option capabilities that control the file name, compression, transfer mode, and file format. These can be obtained or set collectively using the L_TwainGetTransferOptions and the L_TwainSetTransferOptions functions.

• In addition to the transfer options mentioned above, the transfer modes supported by the TWAIN source can be obtained by calling the L_TwainGetSupportedTransferMode function.

• When transferring files from the TWAIN source there is a maximum number of files that can be transferred. To get the current value, call the L_TwainGetMaxXferCount function. To change that value, call the L_TwainSetMaxXferCount function.

• There are many capabilities associated with various image characteristics, such as image resolution, image frame, image unit, bits per pixel, etc. The current values for these can be obtained using the following functions:

L_TwainGetResolution

L_TwainGetImageFrame

L_TwainGetImageUnit

L_TwainGetImageBitsPerPixel

• To change the values of these capabilities, use the following functions:

L_TwainSetResolution

L_TwainSetImageFrame

L_TwainSetImageUnit

L_TwainSetImageBitsPerPixel

• Image contrast, highlight and brightness capabilities can be set simultaneously by calling L_TwainSetImageEffects. To find out the current settings for contrast, highlight and brightness, call L_TwainGetImageEffects.

• The RGB elements used by the TWAIN source can be set by calling the L_TwainSetRGBResponse function.

• If the TWAIN source supports duplex scanning, a specific duplex mode can be enabled or disabled by calling L_TwainEnableDuplex. To get the current duplex mode and the enabled status of that mode, call L_TwainGetDuplexOptions.

• The page size and orientation used during image acquisition can be set by calling L_TwainSetAcquirePageOptions. To get the current settings for these page options, call L_TwainGetAcquirePageOptions.

• During the actual acquisition process, you can elect to have a progress indicator displayed. The L_TwainShowProgress function lets you hide or display the progress indicator.

• The device event capability (CAP_DEVICEEVENT) values for the current TWAIN driver can be set by calling L_TwainSetDeviceEventCapability. To get the device event capability values, call L_TwainGetDeviceEventCapability. To reset the device event capability values, call L_TwainResetDeviceEventCapability. To get detailed information for a device event, you should first set the device event callback LTWAINDEVICEEVENTCALLBACK by calling L_TwainSetDeviceEventCallback. This callback will be fired when acquiring an image from the TWAIN source. And then, you should call L_TwainGetDeviceEventData to get the detailed information.

• After setting the desired capabilities call L_TwainAcquire to scan the pages.

• When working with TW_CAPABILITY structures it may be necessary to create a container associated with that structure. For more information on containers, refer to How to Work with the Containers.

• The user when dealing with the TWAIN source, can obtain or update JPEG Compression options used for TWAIN source. For more information, refer to Using JPEG Compression for a TWAIN Source.

• After the user has finished enumerating, getting, setting and resetting capabilities, the L_TwainEndCapsNeg function must be called. This ends the period of getting and setting capabilities and prepares the TWAIN source for acquiring images.

To get the custom data of TWAIN data source, call the L_TwainGetCustomDSData function, which is also saves the custom data to a file.

To update the custom data of TWAIN data source, call the L_TwainSetCustomDSData function, which is also loads the data from a file.