Setting and Getting Device Capabilities
|
To set the Source's device capabilities, the following functions are used:
To retrieve a device's capability setting, the following functions are used:
To check if a capability exists for a particular Source, the following functions are used:
In addition, you can get or set any capability using the low-level DTWAIN_CallDSMFunction using the DG_CONTROL/DAT_CAPABILITY/MSG_xxxx TWAIN triplet. Please note that this function should only be used by persons familiar with TWAIN triplets and setting up the TWAIN triplet mechanism when making calls to the Data Source Manager.
Detailed steps in setting or retrieving capability values: In general, the requirements to set or retrieve capability values with DTWAIN are as follows:
Determine the proper capability constant: This requires the application programmer to decide which capability that needs to be set or retrieved. For example, if the application needs to query the current unit of measure used by the Source, the capability constant to use would be DTWAIN_CV_ICAPUNITS. A list of the capabilities and their data types are found here. The constants are the same consants used in the TWAIN official C-language header file twain.h. Thus the capability constants you see in twain.h are interchangeable with the DTWAIN constants. Check if the capability is supported by the Source: The next step is to determine if the capability constant is supported by the Source. There are some capabilities that will not be supported by the Source, so the application may want to check if the capability is supported before proceeding to set or get capability values. By default, DTWAIN always does a check for capability support whenever the DTWAIN_GetCapValues, etc. or DTWAIN_SetCapValues, etc. is called, but letting your application do the check results in faster code. To check for capability support the DTWAIN_IsCapSupported function is used.
Now you must either set or get the capability values:
Setting Capability Values a) Call DTWAIN_ArrayCreateFromCap to create the appropriate DTWAIN_ARRAY that matches the same data type as the capability. b) Add the desired values to the DTWAIN_ARRAY that you want to set the capability to. c) Call DTWAIN_SetCapValues, DTWAIN_SetCapValuesEx, or DTWAIN_SetCapValuesEx2 to complete the process of setting the device's capability to your DTWAIN_ARRAY's values. d) Ensure that the DTWAIN_ARRAY that was created is eventually destroyed by using DTWAIN_ArrayDestroy or by shutting down DTWAIN by calling DTWAIN_SysDestroy.
Getting Capability Values a) Determine the data type for the capability values. Use the DTWAIN_GetCapDataType function to get the correct data type. The data types may be LONG's, DTWAIN_FLOAT's, etc. b) If calling DTWAIN_GetCapValues, DTWAIN_GetCapVaulesEx, or DTWAIN_GetCapValuesEx2, declare a DTWAIN_ARRAY. Do not call DTWAIN_ArrayCreateFromCap. c) If using DTWAIN_GetCapValues, DTWAIN_GetCapValuesEx, or DTWAIN_GetCapValuesEx2, send the address of the DTWAIN_ARRAY created in step b). If using the DTWAIN_ArrayGetCapValues... versions of these functions, these functions will automatically create and return the DTWAIN_ARRAY. d) You can now extract the capability values from the DTWAIN_ARRAY using the DTWAIN_ArrayGetAt or related DTWAIN_ArrayGetAt... function. The data type that the extracted values are to be stored in was determined by step 1.
e) Ensure that the DTWAIN_ARRAY that was created is eventually destroyed by using DTWAIN_ArrayDestroy or by shutting down DTWAIN by calling DTWAIN_SysDestroy. 'C' Example of Getting Capabilities 'C' Example of Setting Capabilities
|