-details

The -details option writes information on all the installed TWAIN devices to the file specified by filename. The full path name can be specified as the file name.

The -details option should be used only for getting information on the devices, and not to acquire images. DTWAIN_TwainSave will return immediately after writing the details to the file filename and not attempt to acquire images.

The example above writes detailed information about the installed TWAIN devices to "scanner_details.txt". As with any parameters that may contain spaces, the filename must be enclosed in double quotes if the file name contains spaces.

Device_Contrast_Type:<string>,<numeric_value>,...
Device_Gamma_Type:<string>,<numeric_value>,...

where <integer> is any integer, <numeric_value> could be any floating point value, and <string> is one or more characters. Note that there is always a colon ':' after the name of the information requested. Also note that the decimal point is the "." character, and the separator for each value is the comma ",". Therefore if you are working in a locale where the decimal point is not ".", please be aware of the convention used in the details file.

As a quick example, if there are two TWAIN devices installed, the following will be found in the details file.

If the product name of the device is "xyz scanner", the following will be found in the details file:

Since the format of the output generated is well-defined, the detail log can also provide programmers with a file that they can parse for certain values, and allow their programs to use the information. For example, a program can be written to execute DTWAIN_TwainSave to generate the detail log, and from the log, determine what devices are functional, and also the various color and bits-per-pixel combinations that are valid for a particular device. Then DTWAIN_TwainSave can be executed again with the color/bits-per-pixel information gathered from the detail log to ensure that images will be scanned with valid color and bits-per-pixel information.

For example, the detail log can be used to discover the valid color and bits-per-pixel information for each installed device. If the -color and/or the -bpp options are used when running DTWAIN_TwainSave, they must be valid values. The detail log will indicate the valid color and bits-per-pixel values.

Message	Definition	Example
Device_Count:<integer>	Denotes the number of TWAIN devices installed that can be detected by DTWAIN_TwainSave.	Device_Count:2
Device_Name:<string>	Denotes the product name of a TWAIN device	Device_Name:HP ScanJet
Device_OK:<string>	Denotes the product name of a TWAIN device if DTWAIN_TwainSave successfully communicated with the device. Also, this item is written immediately before the device's color information is written.	Device_Chosen:HP ScanJet
Device_NumColors:<integer>	Denotes the number of colors that the device specified by Device_Chosen has available when acquiring images.	Device_NumColors:3
Device_Color_Info:<integer>;<integer>, <integer>, ...	Denotes the color type and bits-per-pixel that is available for the color type. The color type follows immediately after the colon (":"), followed by a semicolon ";" and then all the supported bits-per-pixel, seperated by commas.	Device_Color_Info:0;1 Device_Color_Info:1;1,4,8 Device_Color_Info:2;24
Device_Failure:<string>	Denotes a device that failed to open. If a device fails to open, it cannot be used for acquiring images. The <string> is the device's product name. Usually a device not able to open means that the TWAIN driver for the device is not installed correctly, or there is some other error communicating with the device.	Device_Failure:My Bad Scanner
Device_Resolution_Type:<string1>,<string2>,<numeric_values>,...	Denotes the resolution values supported by the device. The <string1> will be either be Range or Discrete denoting that the values shown for the resolution will either be defined by a range of values, or discrete values, respectively. See below the table for a full explanation of the differences between Range and Discrete values. The <string2> will be one of the following: Inch, CM, Pica, Point, TWIP, Pixel denoting the unit of measure that the range values are based on. See below this table for more information. The <numeric_values> is one or more decimal values, denoting the various resolutions that are supported for the specified unit of measure. Note that these values can be fractional (decimal) as well as whole numbers.	(See below the table)
Device_Brightness_Type:<string>,<numeric_values>,... Device_Contrast_Type:<string>,<numeric_values>,... Device_Gamma_Type:<string>,<numeric_values>,...	Denotes the brightness, contrast, or gamma values supported by the device. The <string> will be either Range or Discrete denoting that the values shown for the resolution will either be defined by a range of values, or discrete values, respectively. See below the table for a full explanation of the differences between Range and Discrete values. The <string> can also be Unsupported, meaning that setting the brightness, gamma, or contrast is not supported by the device. The <numeric_values> will be one or more values that denote the brightness, contrast, or gamma. If <string> is Unsupported, no numeric values will appear.	(See below the table)
Device_Paper_Sizes:<string>,...	Denotes the paper sizes supported by the device. The <string> is one or more of the paper sizes specfied by the -P option.	Device_Paper_Sizes:letter,A4
Device_Feeder:<integer> Device_Feeder_Sensitive:<integer> Device_Imprinter:<integer> Device_Duplex:<integer> Device_UI_Controllable:<integer> Device_Job_Control:<integer>	Denotes if device supports a document feeder, imprinter, duplexer, controllable user interface, and job control. The Device_Feeder_Sensitive denotes whether the device can detect if there is paper loaded in the document feeder. Use this to check if the -AF option can be used. If <integer> is 0, then the particular option is not supported. If <integer> is 1, then the option is supported.	Device_Feeder:1 Device_Feeder_Sensitive:1 Device_Imprinter:0 Device_Duplex:0 Device_UI_Controllable:1 Device_Job_Control:0

For some of the details listed, a Range or Discrete set of values will be displayed. A Range is denoted by three values -- a minimum value, maximum value, and step value. For example:

The above means that the brightness values have a minimum of 10, a maximum of 1000, and that the other values are in increments of 5, starting from the minimum value. So the brightness values are 10, 15, 20, 25, 30, 35, 40, 45, etc.. up to 1000.

The Discrete set of values lists all of the different values possible. For example:

The Device_Resolution_Values contains two strings before the listing of the numerical resolution values. The first string is either Discrete or Range, as defined above. The second string denotes the unit of measure that the numerical values will be based on. So for example, the following denotes a device that has resolution values of 100, 200, 300 DPI, and 100, 200, 300 dots per centimeter:

Note that each device listed may have one or more Device_Resolution_Type's listed, since a single device may have multiple units of measure supported.

A sample detail log for three devices named "Device1", "Device2", and "Device3" would look similar to the following:

First, we know it was found, since it appears as one of the Device_Name types. We also know that it was opened successfully, since there is this:

The "CanoScan LiDE 500F" can acquire using three different -color settings, therefore there are three Device_Color_Info entries. The first Device_Color_Info setting describes the color and bits-per-pixel valid for color 0. For color 0, the valid bits-per-pixel used is 1. Similarly, the second Device_Color_Info describes the valid bits-per-pixel values for color 1, and the third Device_Color_Info describes the valid bits-per-pixel for color 2. The color value can be used in the DTWAIN_TwainSave command-line option -color, and the bits-per-pixel can be used in the -bpp option.

For example, the following DTWAIN_TwainSave command is valid for the CanoScan LiDE 500F scanner:

The "CanoScan LiDE 500F" can acquire resolutions using three different units of measure, namely Inch, CM (meaning centimeter), and Pica. Therefore there are three separate Device_Resolution_Type entries.

The first Device_Resolution_Type has the Range type, denoting that the resolution values listed on that line describes a range of values.

The values listed are 25, 9600, and 1. Since a Range type describes a minimum, maximum, and step values, the 96 denotes the minimum value of the range, the 9600 is the maximum value of the range, and the 1 denotes the step value. Therefore the valid resolution settings, given that the units are in inches are 25, 26, 27, 28, 29, ... up to 9600.

This line states that for units of centimeters, the valid resolution values are defined by the range starting from 9.843 up to 3780, with a step value of 0.3937.

This line states that for units of pica, the valid resolution values are defined by the range starting from 1 up to 1 with a step value of 1. This is basically stating that there is only a single value that can be set if the units are in pica's, namely 1.

Note that the brightness values are stored in a Range. The minimum value in the range is -1000, the maximum value is 1000, and the step value used in the range is 7.874. This means that the following are valid brightness values: -1000, -992.126, -984.252, ... up to 1000 (the step value of 7.874 is added to each value).

The next line in the listing denotes the gamma values supported by the "CanoScan LiDE 500F":

Note that the type of values are Discrete, meaning that the values listed are the only values available. The only value listed is 2.26. This means that the gamma value is set for 2.26 and cannot be changed.

All of the supported paper sizes follow the Device_Paper_Sizes: text, and are comma separated. Therefore the CanoScan LiDE 500F supports "none", "A4", "B5", "letter", etc. sizes. Note that these sizes can be used in the -P option.

The final set of lines denote whether various aspects of the scanner are supported or unsupported:

According to the lines above, the "CanoScan LiDE 500F" supports a document feeder, the feeder can detect if paper is inserted, there is no imprinter support, no duplex support, the user interface when acquiring images can be turned off by DTWAIN_TwainSave's -noui command, and there is no job control support. Note that 1 in the listing above means "is supported", and 0 means "unsupported".

There is another listing in the details log for a device called the "Twain_32 Sample Source". Let's just go over some of the differences between what is listed for this device and what we saw previously with the CanoScan LiDE 500F scanner.

It only supports a color value of 2, but the bits-per-pixel can be either 8 or 24.

This means that if the units are in inches, only one value can be used, and that is 100.

Also note that there is no gamma settings available for the "Twain_32 Sample Source":

There is also a third device that was found called "Joe's Great Scanner". Unfortunately, it either doesn't work, wasn't installed properly, or some other malfunction, since the following shows up:

This denotes that the scanner failed and cannot be used to acquire images. If this error occurs, it is for the reasons stated previously, namely the device wasn't installed properly, the software was installed but there is a malfunction in the device (maybe a cable is loose or not connected, or maybe the device is broken or missing), or some other software/hardware issue that DTWAIN_TwainSave cannot solve.