Edit

About the IWiaItem2 Item Tree

  • Article

With Windows Vista, the Windows Image Acquisition (WIA) item tree has changed significantly. IWiaItem2 items are used to represent device attributes and device data. Imaging applications see a Windows Image Acquisition (WIA) 2.0 device as a hierarchical tree of items, with the root item representing the device itself and the child items representing things like programmable data sources, images, or folders that contain images.

Application Items

The WIA 2.0 item tree that an application can see is separate from the tree created and maintained by a WIA 2.0 minidriver. When a minidriver creates a tree, the WIA 2.0 service uses this WIA 2.0 item tree as a guide to create a copy of the tree that can be viewed by imaging applications. Items in the copied tree are called application items. Items in the tree created by a minidriver are called driver items.

A WIA item can represent a programmable data source for a scanner's document feeder or the data stored on that device. A WIA device should be divided into individual items that describe different data produced by that device.

For example, a WIA scanner that supports both flatbed scanning and document feeder scanning might be divided into two child items. One represents the flatbed scanning functionality and the other represents the document feeder scanning functionality.

Multiple images laid out on a flatbed scanner and scanned at the same time can be placed in one folder. Using the segmentation filter (IWiaSegmentationFilter), each image or subregion can then be created as a child item of the folder.

The WIA tree for a camera device that stores photos ("Film") can be divided into items that represent folders, subfolders, and photos.

Item Flags

WIA item flags help classify the content or supported behavior of a particular WIA item. WIA item flags fall into two groups.

  1. Item status flags report the current state of the WIA item, for example, WiaItemTypeDisconnected, WiaItemTypeDeleted, and so forth.
  2. Item data representation/usage flags report the data that the WIA item represents or can produce if transferred. For example, WiaItemTypeImage is a data representation flag that tells the application the data associated with the current WIA item is image data and should have image data properties. WIA_IPA_ITEM_FLAGS is an item usage flag that tells the application that the WIA item is configurable and follows a set of predefined configuration rules based on the WIA_IPA_ITEM_CATEGORY and that the configuration can possibly change the result for each data transfer. (For more information about category definitions, see Item Categories item categories.)

The following graphic shows an example of a WIA item tree and the various flags that might be associated with each item.

examples of item flags for items in a tree

Item Categories

WIA items are grouped into categories using the WIA_IPA_ITEM_CATEGORY property values. These categories define how a WIA item is to be treated or used. For example, if the item represents a finished file (WIA_CATEGORY_FINISHED_FILE), a WIA application should assume that the data is static and located on the device. If the item represents a feeder (WIA_CATEGORY_FEEDER), the application should expect it to contain the required document feeder properties and operate like a document feeder.

The categories defined by WIA are:

  • WIA_CATEGORY_AUTO
  • WIA_CATEGORY_FEEDER
  • WIA_CATEGORY_FILM
  • WIA_CATEGORY_FINISHED_FILE
  • WIA_CATEGORY_FLATBED

For example, a scanner's flatbed item may have the WIA_IPA_ITEM_FLAGS set to WiaItemTypeImage, WiaItemTypeTransfer, andWiaItemTypeProgrammableDataSource, and the WIA_IPA_ITEM_CATEGORY property set to WIA_CATEGORY_FLATBED.

The following table shows WIA category grouping with item flags and WIA items. This table does not include a full list of the WIA item flags defined by WIA.

WIA Category Valid WIA Item Flags WIA Property Set WIA Items
WIA_CATEGORY_AUTO Property set includes auto-configured scanner properties. WIA auto item that represents the scanner's auto-configured scanning settings.
WIA_CATEGORY_FEEDER Property set includes feeder scanner control properties (usually image and document specific property set). WIA Feeder items, including child items that represent the front and back pages of a document.
WIA_CATEGORY_FILM Property set includes film scanner control properties (usually image and document specific property set). WIA Film items, including child items that represent the individual scanning frames.
WIA_CATEGORY_FINISHED_FILE The property set on this item depends on the item type reported. For example, WiaItemTypeImage should include some image item properties, like bits per pixel and so forth. WIA storage items, including child items that represent finished file content (data files like JPEG, HTML, TXT, and so forth).
WIA_CATEGORY_FLATBED The property set includes flatbed scanner control properties (usually image and document specific property set). WIA flatbed items, including child items that represent regions being scanned on the scanner's flatbed platen.

 

The following graphic shows an example of a WIA item tree and the various categories that might be associated with each item.

examples of item categories for items in a tree

Root Item

A WIA root item is a folder item marked with WiaItemTypeRoot and WiaItemTypeDevice flags that represents the device itself. It contains device attributes like manufacturer, device name, and driver attributes like driver version and user interface class identifier (CLSID). Imaging applications get the root to the WIA item tree by calling IWiaDevMgr2::CreateDevice method. The application uses the root item to gain access to the individual child WIA items by enumerating the tree (see IEnumWiaItem2).

Data Item

Any item that can be use to transfer data is considered a data item. This includes items marked with the WiaItemTypeProgrammableDataSource flag.

Folder items and nonfolder items can expose the ability to transfer data by being marked with the WiaItemTypeTransfer flag. Any item with this flag set has to provide the following WIA item properties:

Programmable data source items marked with the WiaItemTypeTransfer flag must also supply the data item required property set.

WIA data items may have additional properties depending on the item's flag settings. For example, WIA items marked with the WiaItemTypeImage flag should have image specific information properties, like WIA_IPA_DEPTH and WIA_IPA_NUMBER_OF_LINES.

Reference

IWiaItem2

IEnumWiaItem2

IWiaDevMgr2