Scanner WIA Item Property Constants

Article
08/25/2021

The following constants specify the valid set of Windows Image Acquisition (WIA) scanner item properties.

The prefix "WIA_IPS_" indicates an Item Property for Scanner devices and is the naming convention used in C/C++. For scripting purposes these constants use the prefix "ScannerPicture" and are part of the WiaItemPropertyId enumerated type. The corresponding member name from that script enumeration appears in parentheses next to the C/C++ constant name in the following list.

Constant/value Description

WIA_IPS_AUTO_DESKEW
ScannerPictureAutoDeskew

Note:
This property is supported only by Windows Vista and later.

Turns automatic deskew on or off.
Optional for WIA_CATEGORY_FEEDER only.
Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_LIST
The following table has the constants that are valid with this property.

Constant	Description
WIA_AUTO_DESKEW_ON	Turn on automatic deskew.
WIA_AUTO_DESKEW_OFF	Turn off automatic deskew.

WIA_IPS_BRIGHTNESS
ScannerPictureBrightness

The image brightness values available within the scanner.

Contains the current hardware brightness setting for the device. An application sets this property to the hardware's brightness value. The minidriver creates and maintains this property.

Values should be mapped in a range from -1000 through 1000, where 1000 corresponds to the maximum brightness, 0 corresponds to normal brightness, and -1000 corresponds to the minimum brightness.

Required for all items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM. Optional, but recommended, for WIA_CATEGORY_FINISHED_FILE items supporting previews.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_CONTRAST
ScannerPictureContrast

Contains the current hardware contrast setting for a device. An application sets this property to the hardware's contrast value. The minidriver creates and maintains this property.

Values should be mapped in a range from -1000 through 1000, where -1000 corresponds to the minimum contrast, 0 corresponds to normal contrast, and 1000 corresponds to the maximum contrast.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_CUR_INTENT
ScannerPictureCurIntent

Contains the current intent settings. The minidriver creates and maintains this property.

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FINISHED_FILE or WIA_CATEGORY_FOLDER items.

Type: VT_I4 Access: Read/Write, Valid Values: WIA_PROP_FLAGS

The driver uses these to preset item properties based on an application's intended use of the image. This might include, for example, maximum quality, minimum size, and so on.

The driver chooses the bit depth, in dots per inch, and other settings that it determines are appropriate for the selected intent. It is up to the application to read the current settings to determine which properties were changed. An application sets this property to auto-set the WIA properties for specific acquisition intent. This property is required for all scanners.

An application sets this property to auto-set the WIA properties for specific acquisition intent

Note:
The flags can be combined with a bitwise OR operator, but an image cannot be both grayscale and color.

This property is required for all scanners.

The following table contains the image-type flags and their definitions. These flags are used to set which type of image is intended: color, grayscale, and so on.

Intended image type flags	Description
WIA_INTENT_NONE	Default value. No intent is specified.
WIA_INTENT_IMAGE_TYPE_COLOR	The application intends to prepare the device for a color scan.
WIA_INTENT_IMAGE_TYPE_GRAYSCALE	The application intends to prepare the device for a grayscale scan.
WIA_INTENT_IMAGE_TYPE_TEXT	The application intends to prepare the device for scanning text.
WIA_INTENT_IMAGE_TYPE_MASK	Mask for all of the image-type flags.

The following table contains the quality and size flags and their definitions. These flags are used to set which level of quality is intended.

Intended image size/quality flags	Description
WIA_INTENT_MINIMIZE_SIZE	The application intends to prepare the device for scanning an image that result's in a small scan.
WIA_INTENT_MAXIMIZE_QUALITY	The application intends to prepare the device for scanning a high-quality image.
WIA_INTENT_SIZE_MASK	This flag is a mask for all of the size/quality flags.
WIA_INTENT_BEST_PREVIEW	The application intends to prepare the device for scanning a preview.

WIA_IPS_DESKEW_X
ScannerPictureDeskewX

Note:
This property is supported only by Windows Vista and later.

Contains the number of pixels in the x-direction from WIA_IPS_XPOS to the x-coordinate of the uppermost corner of the image to be deskewed. Hence, it describes, in conjunction with WIA_IPS_DESKEW_Y, where the two upper corners of the skewed image are located within the bounding rectangle defined by WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT and WIA_IPS_YEXTENT. his property is implemented by the scanner driver if it supports deskewing.

The valid values for WIA_IPS_DESKEW_X must be between 0 and (WIA_IPS_XEXTENT - 1). A value of 0 means that no deskew should be performed.

This property is optional for items of the categories WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, and WIA_CATEGORY_FILM; and it is not available for WIA_CATEGORY_FINISHED_FILE or WIA_CATEGORY_FOLDER items.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_DESKEW_Y
ScannerPictureDeskewY

Note:
This property is supported only by Windows Vista and later.

Contains the number of pixels in the y-direction from WIA_IPS_YPOS to the y-coordinate of the leftmost corner of the image to be deskewed. Hence, it describes, in conjunction with WIA_IPS_DESKEW_X, where the two upper corners of the skewed image are located within the bounding rectangle defined by WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT and WIA_IPS_YEXTENT. This property is implemented by the scanner driver if it supports deskewing.

The valid values for WIA_IPS_DESKEW_Y must be between 0 and (WIA_IPS_YEXTENT - 1). A value of 0 means that no deskew should be performed.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_DOCUMENT_HANDLING_SELECT
ScannerPictureDocumentHandlingSelect

Note:
This property is supported only by Windows Vista and later.

Contains the current scanner acquisition source and mode. The minidriver creates and maintains this property.

An application reads this property to determine the current acquisition source of the scanner or to write this property to set the source and mode of the scanner. In addition, applications use this property to enable and disable duplexer functionality.

Type: VT_I4, Access: Read/Write, Valid values: WIA_PROP_FLAG

The following table has the constants that are valid with this property.

Flags	Description
DUPLEX	Scan using duplexer operations. Scan both document sides using common settings configured for the feeder item (WIA_CATEGORY_FEEDER). DUPLEX and ADVANCE_DUPLEX cannot both be set.
ADVANCED_DUPLEX	Scan using individual settings configured for each child feeder item (WIA_CATEGORY_FEEDER_FRONT and WIA_CATEGORY_FEEDER_BACK). DUPLEX and ADVANCE_DUPLEX cannot both be set.
FRONT_FIRST	Scan the front of the document first. This value is valid when DUPLEX or ADVANCED_DUPLEX is set.
BACK_FIRST	Scan the back of the document first. This value is valid when DUPLEX or ADVANCED_DUPLEX is set.
FRONT_ONLY	Scan the front only.
BACK_ONLY	Scan the back only. This value is valid when DUPLEX or ADVANCED_DUPLEX is set.

WIA_IPS_FILM_NODE_NAME
ScannerPictureFilmNodeName

Note:
This property is supported only by Windows Vista and later.

Enables specification of a particular film scanning attachment when there is more than one.

This property is required for the WIA_CATEGORY_FILM items when there are multiple film scan items. If the device supports only one root scanner film item then this property is optional.

Type: VT_BSTR, Access: Read Only, Valid Values: WIA_PROP_NONE

Allowed values: The BSTR should be in the form of @ResourceBinary,-<ResourceID> to allow localization as this string would be exposed to the user through the film scanning UI.

WIA_IPS_FILM_SCAN_MODE
ScannerPictureFilmScanMode

Note:
This property is supported only by Windows Vista and later.

Enables configuration of the current film scan.

This property is required for the WIA_CATEGORY_FILM item.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_LIST

The following table has the constants that are valid with this property.

Constant	Description
WIA_FILM_COLOR_SLIDE	Scan for a color slide.
WIA_FILM_COLOR_NEGATIVE	Scan for a color negative.
WIA_FILM_BW_NEGATIVE	Scan for a black and white negative.

WIA_IPS_INVERT
ScannerPictureInvert

Reserved for future use and is not implemented at this time.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

WIA_IPA_ITEMS_STORED
ScannerPictureInvert

Note:
This property is supported only by Windows Vista and later.

Specifies how many items are stored in the WIA_CATEGORY_FOLDER item.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

WIA_IPS_LAMP
ScannerPictureLamp

Note:
This property is supported only by Windows Vista and later.

Turns the scanner lamp on or off.

Optional for the WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, and WIA_CATEGORY_FILM items and recommended for WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_LIST

The following table has the constants that are valid with this property.

Constant	Description
WIA_LAMP_ON	Turn on the lamp.
WIA_LAMP_OFF	Turn off the lamp.

WIA_IPS_LAMP_AUTO_OFF
ScannerPictureLampAutoOff

Note:
This property is supported only by Windows Vista and later.

Sets the maximum time to keep the lamp on when the scanner is not being used.

Optional for the WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, and WIA_CATEGORY_FILM items and recommended for WIA_CATEGORY_FILM.

Type: VT_UI4, Access: Read/Write, Valid Values: 0 - 0xFFF seconds

WIA_IPS_MAX_HORIZONTAL_SIZE
ScannerPictureMaxHorizontalSize

Note:
This property is supported only by Windows Vista and later.

Specifies the maximum width, in thousandths of an inch, that is scanned in the horizontal (X) axis at the current resolution. This may be the width of the sheet feeder or the scanning bed, according to the type of item.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_MAX_VERTICAL_SIZE
ScannerPictureMaxVerticalSize

Note:
This property is supported only by Windows Vista and later.

Specifies the maximum height, in thousandths of an inch, that is scanned in the vertical (Y) axis at the current resolution. This may be the height of the sheet feeder or the scanning bed, according to the type of item.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_MIN_HORIZONTAL_SIZE
ScannerPictureMinHorizontalSize

Note:
This property is supported only by Windows Vista and later.

Specifies the minimum width, in thousandths of an inch, that is scanned in the horizontal (X) axis at the current resolution.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_MIN_VERTICAL_SIZE
ScannerPictureMinVerticalSize

Note:
This property is supported only by Windows Vista and later.

Specifies the minimum height, in thousandths of an inch, that is scanned in the vertical (Y) axis at the current resolution.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_MIRROR
ScannerPictureMirror

Reserved for future use and is not implemented at this time.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

WIA_IPS_OPTICAL_XRES
ScannerPictureOpticalXres

Note:
This property is supported only by Windows Vista and later.

Horizontal Optical Resolution. Highest supported horizontal optical resolution in DPI. This property is a single value. This is not a list of all resolutions that can be generated by the device. Rather, this is the resolution of the device's optics. The minidriver creates and maintains this property. This property is required for all items.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_OPTICAL_YRES
ScannerPictureOpticalYres

Note:
This property is supported only by Windows Vista and later.

Vertical Optical Resolution. Highest supported vertical optical resolution in DPI. This property is a single value. This is not a list of all resolutions that are generated by the device. Rather, this is the resolution of the device's optics. The minidriver creates and maintains this property. This property is required for all items.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_ORIENTATION
ScannerPictureOrientation

Specifies the current orientation of the documents to be scanned. The minidriver creates and maintains this property.

An application sets this property to define the original orientation of a page or image to be acquired. For information on how to use WIA_IPS_ORIENTATION, see WIA_IPS_PAGE_SIZE.

Note:
WIA_IPS_ORIENTATION refers to the position of the document to be scanned on the scanner bed or feeder. It is the orientation of the document relative to the direction of the scan. WIA_IPS_ROTATION refers to rotation that is applied to the image after it is scanned, just before the image is transferred to the application.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_LIST

The following table has the four constants that are valid with this property.

Value	Definition
PORTRAIT	0 degrees.
LANDSCAPE	90-degree counter-clockwise rotation, relative to the PORTRAIT orientation.
ROT180	180-degree counter-clockwise rotation, relative to the PORTRAIT orientation.
ROT270	270-degree counter-clockwise rotation, relative to the PORTRAIT orientation.

WIA_IPS_PAGE_SIZE
ScannerPicturePageSize

Note:
This property is supported only by Windows Vista and later.

Contains the size of the page that is currently set to be scanned. An application sets this property to select the dimensions of the page to scan. The minidriver creates and maintains this property.

Type: VT_I4, Access: Read/Write, Valid values: WIA_PROP_LIST

For the constants that can be used with this property, see WIA 2.0 Page Size Constants. Note these non-fixed sizes, in particular:

Value	Definition
WIA_PAGE_CUSTOM	Defined by the values of the WIA_IPS_PAGE_HEIGHT and WIA_IPS_PAGE_WIDTH properties.
WIA_PAGE_AUTO	Page size is automatically determined by the device.
WIA_PAGE_CUSTOM_BASE	A custom page size whose dimensions are already known to the application and the device driver.

The value of the WIA_IPS_ORIENTATION property determines the orientation of the currently selected page. The WIA_IPS_PAGE_WIDTH and WIA_IPS_PAGE_HEIGHT properties report the page's dimensions, in thousandths of an inch. These properties must be in agreement with WIA_IPS_XEXTENT and WIA_IPS_YEXTENT, which contain the page's dimensions in pixels.

Note:
Valid values of type WIA_PROP_LIST depend on valid settings of the WIA_IPS_ORIENTATION property. If, for example, the device cannot scan landscape-oriented documents with a WIA_PAGE_A4 setting, WIA_PAGE_A4 is not a valid value for the WIA_IPS_PAGE_SIZE property when WIA_IPS_ORIENTATION is set to LANDSCAPE.

If an application sets WIA_IPS_PAGE_SIZE to any value other than the three in the table above, the minidriver should adjust the values of WIA_IPS_PAGE_WIDTH and WIA_IPS_PAGE_HEIGHT to the page's dimensions in thousandths of an inch. It should also adjust the values of WIA_IPS_XEXTENT and WIA_IPS_YEXTENT to the page's dimensions in pixels.

If an extent setting (WIA_IPS_XEXTENT or WIA_IPS_YEXTENT) is changed to a value that does not match the current page size setting, the minidriver should change the value of the WIA_IPS_PAGE_SIZE property to WIA_PAGE_CUSTOM. The minidriver should also modify WIA_IPS_PAGE_WIDTH or WIA_IPS_PAGE_HEIGHT in accordance with the new extent setting.

If WIA_IPS_ORIENTATION is set to LANDSCAPE, the extent settings will be exchanged relative to their usual values. For example, if an application sets WIA_IPS_PAGE_SIZE to WIA_PAGE_A4, the minidriver sets WIA_IPS_PAGE_WIDTH to 11692 and WIA_IPS_PAGE_HEIGHT to 8267. (The minidriver should also adjust WIA_IPS_XEXTENT and WIA_IPS_YEXTENT accordingly.)

Note:
If WIA_IPS_PAGE_SIZE is set to WIA_PAGE_CUSTOM, the orientation setting is not used to determine the extent dimensions of the page to be scanned.

The minidriver is responsible for ensuring that the WIA_IPS_ORIENTATION property is in agreement with the current selection area. If an application changes the value of WIA_IPS_ORIENTATION to one that is invalid for the currently selected page size, the minidriver should change the value of WIA_IPS_PAGE_SIZE to a page size that is supported by the new orientation value.

If an application sets the WIA_IPS_PAGE_SIZE property to WIA_PAGE_CUSTOM, the current selection area is not affected. The WIA minidriver should obtain the current image layout, starting from the current settings of the WIA_IPS_XPOS and WIA_IPS_YPOS properties. If the page size setting results in a selection area that is outside the scanner's bed, the minidriver must automatically adjust the values of the WIA_IPS_XPOS and WIA_IPS_YPOS properties to valid settings. If the WIA_IPS_PAGE_SIZE and WIA_IPS_ORIENTATION properties are set at the same time, and they are invalid when applied in combination, the minidriver should fail the application's settings by returning an error in the IWiaMiniDrv::drvValidateItemProperties.

The following four examples show different WIA_IPS_PAGE_SIZE scenarios.

The driver reports the settings.
An application sets the WIA_IPS_PAGE_SIZE property to WIA_PAGE_LETTER.
An application sets the WIA_IPS_ORIENTATION property to LANDSCAPE.
An application changes the WIA_IPS_XEXTENT property to a smaller value.

Example 1: The minidriver reports the settings

In the following example, the minidriver sets a custom selection area before an application sets any WIA properties. In this case, the selection area represents the entire flatbed.

WIA_IPS_PAGE_SIZE = WIA_PAGE_CUSTOM
WIA_IPS_PAGE_WIDTH = 11500
WIA_IPS_PAGE_HEIGHT = 14000
WIA_IPS_ORIENTATION = PORTRAIT
WIA_IPS_XPOS = 0
WIA_IPS_YPOS = 0
WIA_IPS_XEXTENT = 1150
WIA_IPS_YEXTENT = 1400
WIA_IPS_XRES = 100
WIA_IPS_YRES = 100

Example 2: An application sets the WIA_IPS_PAGE_SIZE property to WIA_PAGE_LETTER

WIA_IPS_PAGE_SIZE = WIA_PAGE_LETTER
WIA_IPS_PAGE_WIDTH = 8500
WIA_IPS_PAGE_HEIGHT = 11000
WIA_IPS_ORIENTATION = PORTRAIT
WIA_IPS_XPOS = 0
WIA_IPS_YPOS = 0
WIA_IPS_XEXTENT = 850
WIA_IPS_YEXTENT = 1100
WIA_IPS_XRES = 100
WIA_IPS_YRES = 100

Example 3: An application sets the WIA_IPS_ORIENTATION property to LANDSCAPE

The physical bed must be able to acquire a page that was originally in landscape orientation.

WIA_IPS_PAGE_SIZE = WIA_PAGE_LETTER
WIA_IPS_PAGE_HEIGHT = 11000
WIA_IPS_PAGE_WIDTH = 8500
WIA_IPS_ORIENTATION = LANDSCAPE
WIA_IPS_XPOS = 0
WIA_IPS_YPOS = 0
WIA_IPS_XEXTENT = 1100
WIA_IPS_YEXTENT = 850
WIA_IPS_XRES = 100
WIA_IPS_YRES = 100

Example 4: An application changes the WIA_IPS_XEXTENT property to a smaller value

In the following example, an application changes the WIA_IPS_XEXTENT property to 1000. The minidriver should assume that the new value contained in WIA_IPS_XEXTENT is no longer valid for the WIA_IPS_PAGE_SIZE property and should thus change WIA_IPS_PAGE_SIZE to WIA_PAGE_CUSTOM. The minidriver must also adjust WIA_IPS_PAGE_WIDTH.

WIA_IPS_PAGE_SIZE = WIA_PAGE_CUSTOM
WIA_IPS_PAGE_HEIGHT = 10000
WIA_IPS_PAGE_WIDTH = 8500
WIA_IPS_ORIENTATION = LANDSCAPE
WIA_IPS_XPOS = 0
WIA_IPS_YPOS = 0
WIA_IPS_XEXTENT = 1000
WIA_IPS_YEXTENT = 850
WIA_IPS_XRES = 100
WIA_IPS_YRES = 100

WIA_IPS_PAGE_HEIGHT
ScannerPicturePageHeight

Note:
This property is supported only by Windows Vista and later.

Contains the height, in thousandths of an inch, of the currently selected page. The minidriver creates and maintains the WIA_IPS_PAGE_HEIGHT property. An application reads this property to determine the physical dimensions of the page being scanned. If the extent settings are different from the known page sizes, this property reports the height of the page whose WIA_IPS_PAGE_SIZE property is set to WIA_PAGE_CUSTOM (which is a value of the WIA_IPS_PAGE_SIZE property). WIA_IPS_PAGE_HEIGHT must be in sync with WIA_IPS_XEXTENT, which reports the height, in pixels, of the page to be scanned.

This property is required for WIA_CATEGORY_FEEDER items.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_PAGE_WIDTH
ScannerPicturePageWidth

Note:
This property is supported only by Windows Vista and later.

Contains the width of the current page selected, in thousandths of an inch. An application reads this property to determine the physical dimensions of the page being scanned. If the extent settings are different from known page sizes, this property reports the width of the page whose WIA_IPS_PAGE_SIZE property is set to WIA_PAGE_CUSTOM. WIA_IPS_PAGE_WIDTH must be in sync with the value of WIA_IPS_XEXTENT, which reports the width, in pixels, of the page to be scanned. The minidriver creates and maintains this property.

This property is required for WIA_CATEGORY_FEEDER items.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

WIA_IPS_PAGES
ScannerPicturePages

Note:
This property is supported only by Windows Vista and later.

Contains the current number of pages to be acquired from an automatic document feeder. The minidriver creates and maintains this property.

Type: VT_I4; Access: Read/Write; Valid values: WIA_PROP_RANGE This is zero through the maximum number of pages that the scanner can scan. The value is ALL_PAGES (= 0) if the scanner can scan continuously.

An application reads this property to determine the document feeder's page capacity. The application also sets this property to the number of pages it is going to scan.

Note:
If duplex mode is enabled (WIA_IPS_DOCUMENT_HANDLING_SELECT is set to FEEDER | DUPLEX | ADVANCED_DUPLEX), WIA_IPS_PAGES is still equal to the number of pages to scan.

One sheet of paper will automatically contain two pages if DUPLEX is enabled, even if the back side of the page is blank.

Setting WIA_IPS_PAGES to 1 causes a scanner to process one side of the page. We recommend that, if a scanner is unable to scan only one side of a page while in duplex mode, you change the WIA_IPS_PAGES value for the Inc member of the Range member of the WIA_PROPERTY_INFO structure to 2. This value signals the application that it must request pages in multiples of two. A value of ALL_PAGES (= 0) means that all pages that are currently loaded into the document feeder are to be scanned.

WIA_IPS_PHOTOMETRIC_INTERP
ScannerPicturePhotometricInterp

Contains the current setting for white and black pixels. The minidriver creates and maintains this property.

An application reads this value to determine the value of WHITE or BLACK (depending on what the application is doing).

Required for all acquisition enabled or stored items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, WIA_CATEGORY_FINISHED_FILE, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FOLDER items.

Type: VT_I4; Access: Read/Write; Valid Values: WIA_PROP_LIST. If the device can be set to only a single value, create a WIA_PROP_LIST type, and place the valid value in it.

The following table has the two constants that are valid with this property.

Value	Definition
WIA_PHOTO_WHITE_0	WHITE is 0, and BLACK is 1.
WIA_PHOTO_WHITE_1	WHITE is 1, and BLACK is 0.

WIA_IPS_PREVIEW
ScannerPicturePreview

Note:
This property is supported only by Windows Vista and later.

Indicates the preview mode for a device. An application sets this property to place the device into a preview mode.

This property is required for the WIA_CATEGORY_FLATBED and WIA_CATEGORY_FILM items, optional for the WIA_CATEGORY_FEEDER item.

Type: VT_I4, Access: Read/Write, Valid values: WIA_PROP_LIST

The following table has the constants that are valid with this property.

Value	Definition
WIA_FINAL_SCAN	The application will perform a final scan.
WIA_PREVIEW_SCAN	The application will perform a preview scan.

WIA_IPS_PREVIEW_TYPE
ScannerPicturePreviewType

Note:
This property is supported only by Windows Vista and later.

Specifies whether the existing preview image can be updated during an image preview (in response to a change in the WIA_IPA_DATATYPE or WIA_IPA_DEPTH properties).

This property is optional for all acquisition enabled items that support preview scans; that is, WIA_IPS_PREVIEW is supported with WIA_PREVIEW_SCAN. This includes items of types WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

The following table has the constants that are valid with this property.

Constant	Description
WIA_ADVANCED_PREVIEW	Updating the existing image is possible.
WIA_BASIC_PREVIEW	Another preview scan must be executed because updating the existing image is not possible.

WIA_IPS_ROTATION
ScannerPictureRotation

Contains the current rotation setting, if it is implemented. The minidriver creates and maintains this property.

An application sets this property to inform the driver how much (if at all) to rotate the image before the driver returns it to the application.

The WIA minidriver is responsible for rotating the image data before sending it back to the application. The application is responsible for checking the image headers to see the newly rotated values.

Considerable confusion exists about resolving the effect of rotation on the current image's selection area (which is defined by the WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT and WIA_IPS_YEXTENT properties).

Selection area refers to the selected area on the physical scanner bed that an image is be acquired from. WIA_IPS_ROTATION does not modify the selection area. The driver applies a counterclockwise rotation according to WIA_IPS_ROTATION only after the driver has acquired the appropriate selection area. WIA_IPS_ROTATION does affect the dimensions of the output image, so these dimensions must be reflected in the resulting image's data header.

Optional for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_LIST

The following rotation constants are defined.

Constant	Definition
PORTRAIT	The driver will not rotate the image.
LANDSCAPE	TThe driver rotates the image 90 degrees counterclockwise.
ROT180	The driver rotates the image 180 degrees counterclockwise.
ROT270	The driver rotates the image 270 degrees counterclockwise.

WIA_IPS_SEGMENTATION
ScannerPictureSegmentation

Note:
This property is supported only by Windows Vista and later.

Specifies whether the application should use the driver's segmentation filter for multi-region scanning. WIA_IPS_SEGMENTATION must be implemented for WIA_CATEGORY_FLATBED and WIA_CATEGORY_FILM items if they support either the creation of child items with a segmentation filter or if the driver itself creates child items for fixed frames.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

The following table has the two constants that are valid with this property.

Value	Definition
WIA_USE_SEGMENTATION_FILTER	The application should use the segmentation filter for multi-region scanning.
WIA_DONT_USE_SEGMENTATION_FILTER	The driver creates the child items itself for multi-region scanning. This is usually the case if the scanner uses fixed frames for this purpose.

Note:
It is possible for a driver to come with a segmentation filter, but still have WIA_IPS_SEGMENTATION set to WIA_DONT_USE_SEGMENTATION_FILTER for one of its items (such as, the WIA_CATEGORY_FILM item). This could be the case if the scanner uses fixed frames for film scanning, but not for regular scanning from WIA_CATEGORY_FLATBED items.

WIA_IPS_SHEET_FEEDER_REGISTRATION
ScannerPictureSheetFeederRegistration

Note:
This property is supported only by Windows Vista and later.

Contains the registration, or alignment and edge detection, for documents that are placed on the flatbed. The minidriver creates and maintains this property. This property indicates how the sheet is horizontally positioned on the scanning head of a handheld or sheet-fed scanner. The property is used to predict where across the scan head a document is placed.

For scanners that support more than one scan head, this property is relative to the topmost scan head. This property is mandatory for sheet-fed, scroll-fed, and handheld scanners.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

The following table has the three constants that are valid with this property.

Constant	Description
LEFT_JUSTIFIED	The sheet is positioned to the left with respect to the scanning head.
CENTERED	The sheet is centered on the scanning head.
RIGHT_JUSTIFIED	The sheet is positioned to the right with respect to the scanning head.

WIA_IPS_SHOW_PREVIEW_CONTROL
ScannerPictureShowPreviewControl

Note:
This property is supported only by Windows Vista and later.

Indicates whether an item needs a preview control displayed to the user. The minidriver creates and maintains this property.

Optional for all transfer enabled items. This is usually just items of the categories WIA_ITEM_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FILM, and WIA_CATEGORY_FINISHED_FILE.

Type: VT_I4, Access: Read Only, Valid values: WIA_PROP_NONE

The following table has the constants that are valid with this property.

Constant	Description
WIA_SHOW_PREVIEW_CONTROL	Show a preview control to the user, because this device can perform a preview.
WIA_DONT_SHOW_PREVIEW_CONTROL	Do not show a preview control to the user, because this device cannot perform a preview.

WIA_IPS_SUPPORTS_CHILD_ITEM_CREATION
ScannerPictureSupportsChildItemCreation

Note:
This property is supported only by Windows Vista and later.

Specifies whether the application (or the filters) can create child items under the current item.

Optional for all transfer enabled item categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FILM and even WIA_CATEGORY_FOLDER. (If the storage won't support upload of new items then this property should be either unsupported or supported with the FALSE value.)

Items supporting WIA_IPS_SEGMENTATION and WIA_USE_SEGMENTATION_FILTER must also support WIA_IPS_SUPPORTS_CHILD_ITEM_CREATION and have it set to TRUE.

Type: VT_I4, Access: Read Only, Valid Values: TRUE and FALSE

WIA_IPS_THRESHOLD
ScannerPictureThreshold

Note:
This property is supported only by Windows Vista and later.

Specifies the grayscale value that determines whether a pixel will be converted to white or black when an image is converted to monochromatic. Pixels above the threshold become white. Pixels below the threshold become white.

This property is required for acquisition items that support 1-bpp scans and that have the WIA_IPA_DATATYPE property set to WIA_DATA_THRESHOLD.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_TRANSFER_CAPABILITIES
ScannerPictureTransferCapabilities

Note:
This property is supported only by Windows Vista and later.

Specifies whether the driver is capable of transferring multiple child items in single transfer call.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_FLAG

The only possible value for this property is WIA_TRANSFER_CHILDREN_SINGLE_SCAN. If this flag is set, then the driver is capable of transfering multiple child items in single transfer call. If the flag is not set, the WIA Service will walk through the child items recursively and then transfer each of those items.

WIA_IPA_UPLOAD_ITEM_SIZE
ScannerPictureInvert

Note:
This property is supported only by Windows Vista and later.

Specifies the number of bytes to upload for the item.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_NONE

WIA_IPS_WARM_UP_TIME
ScannerPictureWarmUpTime

Specifies the maximum warm-up time, in milliseconds, that the device needs before starting the scanning operation. The minidriver creates and maintains this property.

An application can read this property to determine the maximum warm-up time for this device. It can then present a "waiting for the device to warm up" dialog box, to let the user know that a wait or pause might occur before anything happens.

This property is required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read Only, Valid Values: WIA_PROP_NONE

WIA_IPS_XEXTENT
ScannerPictureXextent

Contains the current width, in pixels, of the selected image to acquire. An application sets this property to mark the width of a selection area to acquire. This property must agree with the WIA_IPA_PIXELS_PER_LINE property. The minidriver creates and maintains this property.

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_XPOS
ScannerPictureXpos

Contains the x coordinate, in pixels, of the upper-left corner of the selected image. An application sets this property to mark the upper-left corner of the selection area. The minidriver creates and maintains this property.

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, WIA_CATEGORY_FINISHED_FILE, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FOLDER items.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_XRES
ScannerPictureXres

Contains the current horizontal resolution, in pixels per inch, for the device. An application sets this property to set the horizontal resolution. The minidriver creates and maintains this property.

If the device can be set to only a single value, create a WIA_PROP_LIST type and place the valid value in it. This is also a case where one resolution setting depends on another resolution. (The vertical resolution can depend on the horizontal resolution.)

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, WIA_CATEGORY_FINISHED_FILE, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FOLDER items.

Type: VT_I4, Access: Read/Write or Read Only, Valid Values: WIA_PROP_RANGE or WIA_PROP_LIST

WIA_IPS_XSCALING
ScannerPictureXscaling

Note:
This property is supported only by Windows Vista and later.

Sets the horizontal scaling, as a percentage, that may be applied to scanned images within the scanner device or its driver.

This property is optional for all acquisition enabled items; that is, items of types WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read/Write or Read Only, Valid Values: WIA_PROP_LIST or WIA_PROP_RANGE.

Values can be from 1 to maximum VT_I4 (0xFFFF). For example, 100 means no scaling, 050 means scaling down to 50% of the orignal size, and 200 means scaling up to 200% of the original size.

WIA_IPS_YEXTENT
ScannerPictureYextent

Contains the current height, in pixels, of the selected image to acquire. An application sets this property to mark the height of a selection area. This property must be agree with the value of the WIA_IPA_PIXELS_PER_LINE property. The minidriver creates and maintains this property.

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, and WIA_CATEGORY_FILM.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_YPOS
ScannerPictureYpos

Current y coordinate, in pixels, of the upper-left corner of the selected image. An application sets this property to mark the upper-left corner of the selection area. The minidriver creates and maintains this property.

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, WIA_CATEGORY_FINISHED_FILE, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FOLDER items.

Type: VT_I4, Access: Read/Write, Valid Values: WIA_PROP_RANGE

WIA_IPS_YRES
ScannerPictureYres

Contains the current vertical resolution, in pixels per inch, for the device. An application sets this property to set the vertical resolution. The minidriver creates and maintains this property.

If the device can be set to only a single value, create a WIA_PROP_LIST type and place the valid value in it. This is also a case where one resolution setting depends on another resolution. (The horizontal resolution can depend on the vertical resolution.)

Required for all acquisition enabled items; that is, items in the categories: WIA_CATEGORY_FLATBED, WIA_CATEGORY_FEEDER, WIA_CATEGORY_FEEDER_FRONT, WIA_CATEGORY_FEEDER_BACK, WIA_CATEGORY_FINISHED_FILE, and WIA_CATEGORY_FILM. It is not supported for WIA_CATEGORY_FOLDER items.

Type: VT_I4, Access: Read/Write or Read Only, Valid Values: WIA_PROP_RANGE or WIA_PROP_LIST

WIA_IPS_YSCALING
ScannerPictureYscaling

Note:
This property is supported only by Windows Vista and later.

Sets the vertical scaling, as a percentage, that may be applied to scanned images within the scanner device or its driver.

Type: VT_I4, Access: Read/Write or Read Only, Valid Values: WIA_PROP_LIST or WIA_PROP_RANGE.

Values can be from 1 to maximum VT_I4 (0xFFFF). For example, 100 means no scaling, 050 means scaling down to 50% of the orignal size, and 200 means scaling up to 200% of the original size.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	Wiadef.h

Share via

Scanner WIA Item Property Constants

Requirements

Feedback

Additional resources