Windows Image Acquisition

Purpose

The Windows Image Acquisition (WIA) application programming interface (API) is standardized for acquiring digital images from devices that are primarily used to capture still images, and for managing these devices.

Where Applicable

Windows Image Acquisition can be used in all applications based on Microsoft® Windows® Me operating system.

Developer Audience

The Windows Image Acquisition API is designed for use by C/C++ programmers. Familiarity with the Windows graphical user interface and using COM interfaces is required.

Run-time Requirements

Applications that use the WIA API require the Windows Me operating system.

About Windows Image Acquisition

General information about WIA

Using Windows Image Acquisition

Information about using WIA interfaces

Reference

Documentation of WIA interfaces, methods, and data types.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Legal Information

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2000 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, JScript, Visual Basic Scripting Edition, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About Windows Image Acquisition

The Microsoft® Windows® Image Acquisition (WIA) interface is both an application programming interface (API) and a device driver interface (DDI). The WIA API is designed to allow applications to:

  • Run in a robust and stable environment.
  • Minimize interoperability problems.
  • Enumerate available image acquisition devices.
  • Create connections to multiple devices simultaneously.
  • Query properties of devices in a standard and expandable manner.
  • Acquire device data using standard and high performance transfer mechanisms.
  • Maintain image properties across data transfers.
  • Be notified of a wide variety of device events.

The WIA DDI is designed to minimize the amount of code a hardware vendor must write, while maintaining the flexibility to craft individual solutions. This is accomplished by:

  • Providing a standard device service library that performs most driver operations.
  • Promoting industry device communications standards so that one WIA driver supports most WIA devices. For example, Picture Transfer Protocol (PTP).
  • Allowing the device driver to support custom interfaces, while not requiring that it use the standard device service library. However, drivers still need to implement the standard WIA interfaces.

This section presents a brief overview of the WIA interface in the following areas:

  • WIA Architecture
  • STI Compatibility
  • TWAIN Compatibility
  • WIA Device Manager
  • WIA Minidriver Service Library
  • WIA Minidriver


WIA Architecture

WIA is implemented as a Component Object Model (COM) out-of-process server to ensure the robust operation of client applications. Unlike most out of process server applications, WIA avoids performance penalties during image data transfer by providing its own data transfer mechanism, IWiaDataTransfer. This high performance interface uses a shared memory window to transfer data to the client.

WIA has three main components: a Device Manager, a Minidriver Service Library, and a Device Minidriver.

  • The Device Manager enumerates imaging devices, retrieves device properties, sets up events for devices, and creates device objects.
  • The Minidriver Service Library implements all services that are device independent.
  • The Device Minidriver maps WIA properties and commands to the specific device.

The following diagram illustrates the WIA architecture:


STI Compatibility

The WIA architecture is built upon the foundation established by the Still Image Architecture (STI). WIA device drivers will be compliant with STI's User Mode Driver (USD) model. While the original USD's purpose is to support TWAIN data sources and other APIs, WIA drivers support the new WIA application interface.


TWAIN Compatibility

WIA provides a TWAIN compatibility layer that allows TWAIN-aware applications to communicate with WIA devices. TWAIN-aware applications do not have full access to WIA functionality. For example, an application cannot suppress the user interface using the TWAIN compatibility layer.

WIA devices appear twice to an application that is aware of both WIA and TWAIN: once through normal WIA communication, and once through the TWAIN compatibility layer. To avoid listing a WIA device twice, an application that is aware of both WIA and TWAIN must filter out the WIA devices that come through the TWAIN compatibility layer. All WIA devices that come through the TWAIN compatibility layer have "WIA-" as a prefix, so it is easy to filter them.

TWAIN applications that communicate to WIA through the TWAIN compatibility layer are restricted by the following limitations:

  • Automatic document feeder (ADF) type transfers are unsupported. Transfers from ADF devices is supported, but transfer only one page at a time.
  • Only BMP file transfers are supported.
  • Suppressing the standard user interface is not supported.


WIA Device Manager

The WIA Device Manager is an extension of the Still Image (STI) Event Monitor. The WIA Device Manager provides objects, methods, and interfaces for the following:

  • Installing devices
  • Enumerating devices
  • Querying properties of installed devices
  • Creating device objects
  • Monitoring device events
  • Acquiring images
  • Registering destination applications.


WIA Minidriver Service Library

To simplify driver implementation as much as possible, WIA provides a Minidriver Service Library that performs many of the administrative tasks required by the WIA architecture. The service library provides helper functions to maintain the device's tree of IWiaDrvItem objects.

The basic service library functions perform helper functions that most device drivers would otherwise need to implement. These functions read and write properties. They also create driver item objects and copy device information properties.


WIA Minidriver

Applications see WIA devices as a hierarchical tree of IWiaItem objects with the root item representing the device itself. WIA devices may be used concurrently by more than one application. It is therefore necessary that each application's view of an IWiaItem object be independent of another application's views. This is accomplished by having two different item objects. The driver creates the driver item tree of IWiaDrvItem objects, also called driver items, using the WIA driver services methods. These are global objects that the driver uses to represent each driver's internal items. When an application creates an IWiaItem object (also called an application item), this object is linked to the driver's corresponding IWiaDrvItem in the driver item tree. A reference count is maintained on the IWiaDrvItem object subject to the following rules:

  • When a driver adds an IWiaDrvItem object to the driver item tree, the IWiaDrvItem object's reference count is incremented. This typically takes place during drvInitializeWia or when a WIA_CMD_SYNCHRONIZE command is processed.
  • When a driver removes an IWiaDrvItem object from the driver item tree, the IWiaDrvItem object's reference count is decremented and the IWiaDrvItem object is marked so that it can't access the device again. This typically takes place when a device is disconnected or an item is deleted. Applications are still able to read properties from an IWiaItem object even when the corresponding IWiaDrvItem object has been removed from the driver item tree.
  • When an IWiaItem object is created it is linked to a corresponding IWiaDrvItem object. The reference count of the IWiaDrvItem object is incremented.
  • When an IWiaItem object is released, the link to its corresponding IWiaDrvItem object is severed and the IWiaDrvItem object's reference count is decremented.
  • If an IWiaDrvItem object's reference count goes to zero, the IWiaDrvItem object is deleted. This applies to all IWiaDrvItem objects including the root item. An IWiaDrvItem object's reference count only goes to zero when no application items reference it and it is no longer linked to the driver item tree.

Using this reference counting scheme, many IWiaItem objects may link to one IWiaDrvItem without interference. Because each IWiaItem contains its own property storage, an application can continue to read item properties even after an item has been deleted, but no operation that requires access to the device will succeed. Because item properties are stored in the IWiaItem object, the driver must set the IWiaItem object's properties to the device before a data transfer.


Using Windows Image Acquisition

This section presents an overview of how Microsoft® Windows® Image Acquisition (WIA) works, and how it can be used to create applications that manage imaging devices. For more information, see the following:

  • Using WIA Device Objects
  • Acquiring Images
  • Navigating an Item Tree
  • Registering WIA Events
  • Using WIA Enumerators
  • Reading and Setting WIA Properties
  • WIA Error Information
  • Using Multiple Threads in a WIA Application
  • Communicating with a WIA Device in Multiple Threads or Applications
  • Using the WIA Scripting Model


Using WIA Device Objects

An imaging device is represented in WIA as a hierarchical tree of WIA item objects (IWiaItem interfaces). Typically, the root of this item tree represents the device itself, while the other items on the tree represent images, for a camera, or scanning regions, for a scanner.

Applications use the WIA device manager to create and enumerate WIA devices. The following sections explain how to create and use WIA devices:

  • Selecting a Device
  • WIA Camera Devices
  • WIA Scanner Devices


Selecting a Device

When an application connects to a WIA hardware device, WIA creates an item tree (a hierarchical tree of IWiaItem interfaces) that represents the device and its images, folders, and scanning beds. An application can select and connect to a device without user input, or it can display a dialog box that allows a user to select a device.

Selecting a Device Without the UI

Perform the following steps to select and connect to a WIA hardware device.

  • Call CoCreateInstance to retrieve a pointer to the IWiaDevMgr interface.
  • Use the EnumDeviceInfo method of the IWiaDevMgr interface to obtain a pointer to the IEnumWIA_DEV_INFO interface. For instructions on how to enumerate devices, see Enumerating System Devices.
  • Use IEnumWIA_DEV_INFO interface to obtain IWiaPropertyStorage interface pointers for each WIA device enumerated.
  • Use IWiaPropertyStorage interface to inspect the device information properties of each device and save the DeviceID property from the desired device.
  • Use the DeviceID property with the CreateDevice method in the IWiaDevMgr interface to create a WIA device object. The CreateDevice method provides the application with the pointer to the IWiaItem interface of the root item of the specified device.

For an example of how to do this in an application, see Creating a Device in the tutorial section of this guide.

Selecting a Device With the UI

After retrieving a pointer to IWiaDevMgr, an application can allow a user to select a device by skipping the rest of the above steps and calling IWiaDevMgr::SelectDeviceDlg. The SelectDeviceDlg displays a dialog box in which the user can select a WIA device.

It is recommended that applications make device and image selection available through a menu item named From scanner or camera on the File menu.


WIA Camera Devices

WIA represents a camera device as a hierarchical tree of IWiaItem objects. The root item, returned from a call to the WIA device manager IWiaDevMgr::CreateDevice method, is used to get and set device information, to control the device, and to begin device item enumeration. The following diagram illustrates a sample camera implementation. The camera root item has three child items, two pictures and one folder. The folder has two child items, both pictures.


WIA Scanner Devices

The WIA scanner device is implemented as a hierarchical tree of IWiaItem objects. From the root item an application may:

  • Query scanner capabilities
  • Set scanner device properties
  • Control the document feeder

A WIA scanner device is different from a WIA camera device because, in general, it does not store multiple images in memory.

Underneath the root item, a typical scanner object has a single IWiaItem object that represents the data collecting functionality of the device, the Scan Item. This item has the WiaItemTypeFile flag set to indicate that data transfers on this item are possible. An application sets up a scan by setting the properties of the scan item, then performs the scan and transfers the data using a data transfer interface.

The following diagram illustrates the WIA implementation for a typical scanner:

The WIA implementation of a typical scanner.

A typical duplex scanner is represented in WIA by having one IWiaItem object. Front- and back-page data is accessed sequentially one data transfer per page.

The following diagram illustrates the WIA representation of a duplex scanner:

The WIA representation of a duplex scanner.

A slide scanner capable of scanning multiple slides in a single scan operation represents each separate image as a separate IWiaItem object.

The following diagram illustrates the WIA representation of a slide scanner:


Acquiring Images

After an image has been selected, an application uses the IWiaDataTransfer interface to transfer image data from imaging devices.

After a device has been selected, an application uses the IWiaItem::DeviceDlg method of the IWiaItem interface of the device (the root item) to select an image from a specified WIA device. The IWiaDevMgr::GetImageDlg method displays a dialog box that allows a user to select an image from a specified device, and returns a pointer to the IWiaItem interface that corresponds to the selected image. For more information, see Selecting a Device

Note that it is not necessary for a user to select an image using the above method. An application can obtain a pointer to an image item directly from a device's item tree. For instructions, see Navigating an Item Tree.

Once the WIA item that represents the desired image has been selected, an application queries the IWiaItem interface of that item for a pointer to its IWiaDataTransfer interface.

The application can then use one of the methods of the IWiaDataTransfer interface to transfer the image data to the application. For example, the application can call the idtGetData method of the IWiaDataTransfer interface.

If the imaging device is a scanner, idtGetData, or other methods of the IWiaDataTransfer interface, triggers a scan operation, and then transfers the resulting image data. If the device is a camera, the image data is simply transferred from the camera to the application.


Navigating an Item Tree

An application navigates a WIA device's item tree to find and select images on that device. Using this technique, an application selects and acquires an image without presenting a dialog box to the user.

A WIA device is represented as the root item in a tree of IWiaItem objects. The child items in the tree represent images for a camera or scan beds for a scanner.

After a WIA device is selected, an application calls the EnumChildItems method of the IWiaItem interface of the device to enumerate the child items (the images or scan beds) of the device. For instructions, see Selecting a Device.

The EnumChildItems method creates an enumeration object for the child items of the device, and returns a pointer to that object's IEnumWiaItem interface. The application can then use the methods of the IEnumWiaItem interface to obtain pointers to the items in the device's item tree.


Registering WIA Events

Applications can register to be notified of WIA hardware device events by calling one of the following three IWiaDevMgr interface methods:

  • RegisterEventCallbackCLSID
  • RegisterEventCallbackInterface
  • RegisterEventCallbackProgram

All of these methods take parameters that specify the event and the hardware device for which the application is to be notified. Applications register to receive an event for all WIA devices by passing a NULL value for the parameter that specifies the hardware device.

The RegisterEventCallbackInterface method registers an application to receive a WIA hardware device event if the application is running at the time the event occurs. When the event for which the application is registered occurs, WIA calls the IWiaEventCallback::ImageEventCallback method of the application to transmit the event information.

The RegisterEventCallbackCLSID method registers an application that is a registered COM component to receive a WIA hardware device event even if the application is not running. In addition to the parameters mentioned previously, this method takes a parameter, pClsID, that specifies the class ID of the application. When the specified event occurs, the WIA system uses the CoCreateInstance function and the class ID specified by pClsID to create a new instance of the application, and calls the IWiaEventCallback::ImageEventCallback method of that application to transmit the event information.

The RegisterEventProgram method registers an application to receive a WIA hardware device event even if the application is not running when the event occurs. The application need not be a registered COM component. WIA launches the application with a command line statement. RegisterEventProgram takes a parameter, bstrCommandLine, that specifies the full path and filename of the executable application. RegisterEventProgram exists for backward compatibility with applications that were not written for WIA, and should be avoided. Use RegisterEventCallbackInterface or RegisterEventCallbackCLSID instead.

To determine which handlers are registered for events on a specific WIA device, an application calls a IWiaItem::EnumRegisterEventInfo method of a root item. This method creates an enumeration object for the registration information. The application can then use the IEnumWIA_DEV_CAPS interfaceof that object to enumerate information about the handlers registered to receive events for that device.

If an event occurs for which a running application is registered through RegisterEventCallbackInterface and either RegisterEventCallbackCLSID or RegisterEventProgram, WIA notifies the running application and does not attempt to launch a new instance of the application because event registration through RegisterEventCallbackInterface takes precedence over both RegisterEventCallbackCLSID and RegisterEventProgram.

Note In a multi-threaded application, there is no guarantee that the thread that the event notification callback will return on is the same thread that registered the callback.


Using WIA Enumerators

WIA provides several interfaces for enumerating various capabilities, properties, and information. The WIA enumeration interfaces are all specific implementations of the standard COM enumeration interface. For details, see IEnumXXXX.

The following table provides information about the WIA enumeration interfaces.

Interface | How to Obtain a Pointer | Used For
IEnumWIA_DEV_CAPS | Call a IWiaItem::EnumDeviceCapabilities method of a WIA root item's. | Enumerates the capabilities of a WIA hardware device, such as device commands and events.
IEnumWIA_DEV_INFO | Call the IWiaDevMgr::EnumDeviceInfo method. | Enumerates available WIA devices, and provides pointers to their IWiaPropertyStorage interfaces.
IEnumWIA_FORMAT_INFO | Call an IWiaDataTransfer::idtEnumWIA_FORMAT_INFO method of an item. | Enumerates all image format information that a WIA item provides.
IEnumWiaItem | Call a IWiaItem::EnumChildItems method of WIA item. | Enumerates the child items of a WIA item that represents either a device or a folder.


Reading and Setting WIA Properties

The IWiaPropertyStorage interface provides methods for reading and writing a WIA item's properties. Item properties include device commands, item format information, and device information.

An application can obtain a pointer to an IWiaPropertyStorage interface of an item either by enumerating the item's device information or event information by calling IWiaItem::EnumDeviceCapabilities or IWiaItem::EnumRegisterEventInfo or by querying the IWiaItem interface of the item.

IWiaPropertyStorage inherits from IPropertyStorage and the inherited methods are implemented as described in the reference section of Structured Storage in the Microsoft Platform SDK.

The following sections describe the various WIA properties:

  • WIA Property Validation
  • Device Information Properties
  • Device Properties
  • Item Properties
  • Additional WIA Properties


WIA Property Validation

When an application performs a WriteMultiple operation on any writeable WIA property, the WIA driver performs a validation on the new property value. Writing one property may have side affects that change other property values. It is up to the application to read all property values after a write operation to determine that all properties are set to values the application desires.

Multiple properties can be written simultaneously using the WriteMultiple operation. There may be cases where some property assignments conflict. In such cases, the priority used to resolve conflicts is as follows:

WIA_IPS_CUR_INTENT

WIA_IPA_DATATYPE

WIA_IPA_DEPTH

WIA_IPS_XRES

WIA_IPS_YRES

WIA_IPS_XPOS

WIA_IPS_YPOS

WIA_IPS_XEXTENT

WIA_IPS_YEXTENT


Device Information Properties (WIA_DIP_XXXX)

Device Information Properties are properties that describe the setup and installation of the device. These properties are available through the IWiaDevMgr interface and also through the root item. Device information properties are prefixed with WIA_DIP (DeviceInformationProperty), and are supplied by WIA. For more information, see Device Information Property Constants.


Device Properties

Device Properties are properties that control the function of the entire device. These properties can only be accessed through the root item of the tree that represents a device. There are three types of device properties: common, scanner, and camera.

For reference information, see:

  • Common Device Property Constants
  • Camera Device Property Constants
  • Scanner Device Property Constants


Item Properties

Item properties are properties that control the function of a WIA item. These properties are accessed through any item on a tree that represents a device. There are three types of item properties: common, scanner, and camera.

For reference information for these properties, see:

  • Common WIA Item Property Constants
  • Camera WIA Item Property Constants
  • Scanner WIA Item Property Constants


Additional WIA Properties

WIA devices may support additional item properties depending on hardware configuration. Unsupported properties have a VARTYPE of VT_EMPTY.


WIA Error Information

The WIA APIs return their completion status in an HRESULT return value. Applications check these return values against the FACILITY_WIA constant to determine whether the error requires user intervention to clear — such as a jammed paper path — and report them to the user. In addition, all driver-level errors are logged to the event log in detail, using error strings provided by the device minidriver. The following WIA-specific errors may be returned to an application when an API call fails:

Constant | Description
WIA_ERROR_GENERAL_ERROR | There was a general device failure.
WIA_ERROR_PAPER_JAM | The paper path is jammed.
WIA_ERROR_PAPER_EMPTY | There are no documents in the input tray to scan.
WIA_ERROR_PAPER_PROBLEM | There is a general problem with an input document.
WIA_ERROR_OFFLINE | The device is offline.
WIA_ERROR_BUSY | The device is busy.
WIA_ERROR_WARMING_UP | The device is warming up.
WIA_ERROR_USER_INTERVENTION | The user has paused or stopped the device.
WIA_S_NO_DEVICE_AVAILABLE | No WIA device of the selected type is available.


Using Multiple Threads in a WIA Application

When using a WIA interface in more than one thread within a single process, an application must provide marshalling for that interface. If one thread creates an interface pointer, you cannot use that pointer in a different thread without marshalling.

For example, if one thread in an application obtains a pointer to the IWiaItem interface, a separate thread cannot use that interface pointer without marshalling.

A common technique used to accomplish this marshalling is to use the global interface table. The global interface table is a table maintained across all threads within a single process. All threads running within the process can retrieve interfaces that are registered to the global interface table. This technique avoids the need to create streams for passing interfaces between threads.

The MSQSCAN application uses the global interface table to marshal interfaces between threads. For information on how to use the global interface table, see IGlobalInterfaceTable.

Even if you do not intend to use multiple threads in a WIA application, you must assume that all data transfer or device event callback functions run in separate threads.


Communicating with a WIA Device in Multiple Threads or Applications

When a thread is actively communicating with a WIA device (for example, transferring data or writing device properties) WIA "locks" the device. When a device is locked, no other threads or processes can actively communicate with that device.

WIA does not prohibit multiple threads or processes from maintaining connections to a single device. That is, a device is locked only during the actual communication, and two or more applications can simultaneously have a single device selected.

WIA creates a separate item tree each time any thread or application calls IWiaDevMgr::CreateDevice to create an instance of that device. WIA maintains separate state information for each item tree. For example, if a thread creates two instances of a particular scanner, it can set different scan resolutions for the two instances. When IWiaDataTransfer::idtGetData is called on a particular instance, WIA loads the properties associated with that instance to the device before the actual scan takes place. This does not affect the state of the other instance of the device.

If a thread currently has a device locked (it is actively communicating with that device) and another thread attempts to call a method that actively communicates with the device, the method returns a WIA_ERROR_BUSY error.

Typically, reading and writing device properties takes so little time that these operations rarely cause a conflict. Transferring data, however, usually takes longer, and therefore is more likely to create device access conflicts. It is sound programming to avoid lengthy device operations (data transfers) concurrently in separate threads within an application.

An application should never assume that it is the only application that is communicating with a WIA device when it starts.


Using the WIA Scripting Model

Through the WIA Scripting Model, WIA functionality is made available to scripting languages such as Microsoft® JScript® development software and Microsoft Visual Basic® Scripting Edition, and high-level languages such as Microsoft Visual Basic® development system.

The WIA scripting model exposes objects that inherit the IDispatch interface.

The scripting model offers a simplified version of the WIA application programming interface (API).

For more information, see the following:

  • Setting up the Scripting Model Development Environment
  • Connecting to a Device
  • Navigating a Tree of Item Objects
  • Transferring Data
  • Limitations of the Scripting Model


Setting up the Scripting Model Development Environment

To use the WIA scripting model, you must have the files wiascr.dll and wiascr.tlb installed and registered on the machine.

Copy these files from the WIA SDK into the %windir%/System (for example, c:\windows\system) directory. At the command line, navigate to this directory, and type regsvr32 wiascr.dll.

This enters the necessary information in the system registry.

You are now ready to use the WIA scripting model.


Connecting to a Device

The first step in any application or script that uses the WIA scripting model is creating the Wia object. This object provides methods for to obtain a collection of DeviceInfo objects and connect these objects to devices. It also provides the ability to listen for WIA hardware events.

The following line of VBScript code creates the Wia object:

objWia = CreateObject(Wia.Script)

After creating the Wia object, use its Create method to connect to a WIA hardware device.

You can also use the Wia object's Devices property to obtain a collection of DeviceInfo objects. Enumerate this collection and use the DeviceInfo.Create method to connect to a device.


Navigating a Tree of Item Objects

An application or script navigates a WIA device's item tree to find and select images on that device. Using this technique, an application selects and acquires an image without the use of a dialog box.

A WIA device is represented as the root item in a tree of Item objects. The child items in the tree represent folders and images for a camera or scan beds for a scanner.

After connecting to a device, call the Children property of the Item object that represents the device (the root item of the tree) to obtain a collection of the child items (the images or scan beds) of the device.

Enumerate this collection (recursively, if necessary) to navigate item tree.


Transferring Data

Use the Transfer method of an Item object to transfer image or audio data from a device to a file or the clipboard.

Pass a path and filename as the first parameter to save the data to disk, or pass the string "clipboard" to transfer the item to the clipboard.


Limitations of the Scripting Model

The WIA scripting model exposes a subset of WIA functionality. The following table provides descriptions of the limitations of the scripting model.

WIA Functionality | Scripting Model Limitation
Suppressing the user interface | Cannot suppress the user interface for setting device/transfer properties.
Setting properties | Cannot set (write) any device or item properties.
Registering for callback events | Can only receive notification for three specified events: Wia.OnTransferComplete, Wia.OnDeviceConnected, and Wia.OnDeviceDisconnected.
Handling errors | Cannot handle WIA errors.


WIA Tutorial

This tutorial provides step-by-step instructions to use Microsoft® Windows® Image Acquisition (WIA) in real-world applications.

The tutorial presents code from the sample applications included in the SDK. It is intended to demonstrate how developers can implement the major functionality of WIA and is not a blueprint to create a complete application.

The tutorial focuses on the following tasks:

  • Creating a WIA Device Manager
  • Enumerating System Devices
  • Reading Device Properties
  • Creating a Device
  • Enumerating Items
  • Transferring Image Data
  • Registering for Events


Creating a WIA Device Manager

The first step in using WIA services is to obtain an IWiaDevMgr interface pointer. To do this, call CoCreateInstance with the appropriate parameters. The sample application GetImage creates a device manager within a global function implemented by the following code:

BOOL CreateWIADeviceManager()
{
    HRESULT hr = S_OK;
    g_pIWiaDevMgr = NULL;
    hr = CoCreateInstance(CLSID_WiaDevMgr, NULL, CLSCTX_LOCAL_SERVER,
                          IID_IWiaDevMgr,(void**)&g_pIWiaDevMgr);
    if (SUCCEEDED(hr))
        return TRUE;
    else
        return FALSE;
}

In this example, CLSID_WiaDevMgr and IID_IWiaDevMgr are WIA constants that represent the class ID and the interface ID of IWiaDevMgr, respectively, and g_pIWiaDevMgr is a variable of type IWiaDevMgr *.

The value for the dwClsContext argument of the CoCreateInstance call must be CLSCTX_LOCAL_SERVER. No other server type is supported, and COM rejects any other value for this parameter.


Enumerating System Devices

Use the IWiaDevMgr::EnumDeviceInfo method to enumerate the WIA devices installed on a system. This method creates an enumeration object for the properties of the devices, and returns a pointer to the IEnumWIA_DEV_INFO interface that the enumeration object supports.

You can then use the methods of the IEnumWIA_DEV_INFO interface to obtain an IWiaPropertyStorage interface pointer for each device installed on the system.

The following code from the MSQSCAN sample application demonstrates how to create an enumeration object for the devices on a system and iterate through those devices:

hr = g_pIWiaDevMgr->EnumDeviceInfo(WIA_DEVINFO_ENUM_LOCAL,&pWiaEnumDevInfo);
    if (SUCCEEDED(hr)){
        // Call Reset on Enumerator
        hr = pWiaEnumDevInfo->Reset();
        if (SUCCEEDED(hr)) {
            do {
                // Enumerate requesting 1 Device on each Next call
                hr = pWiaEnumDevInfo->Next(1,&pIWiaPropStg,&ulFetched);
                if (hr == S_OK) {
                    // Do something with the device
                    pIWiaPropStg->Release();
                }while (hr == S_OK);
        } else
                    printf(TEXT("Reset() Failed\n"));
            }
    else{
        printf(TEXT("EnumDeviceInfo Failed\n"));
        return FALSE;
    }

In this example, WIA_DEVINFO_ENUM_LOCAL is a WIA constant that represents the only valid value for this parameter, g_pIWiaDevMgr is a variable of type IWiaDevMgr *, pWiaEnumDevInfo is a variable of type IEnumWIA_DEV_INFO *, and pIWiaPropStg is a variable of type IWiaPropertyStorage *.

In the example, g_pIWiaDevMgr points to an instance of the IWiaDevMgr interface after a previous call to CoCreateInstance.

The application calls the EnumDeviceInfo method of the IWiaDevMgr pointer g_pIWiaDevMgr that fills pWiaEnumDevInfo with the address of a pointer to the IEnumWIA_DEV_INFO interface.

If the call succeeds, the application then calls the Reset method of the IEnumWIA_DEV_INFO pointer. The pWiaEnumDevInfo variable ensures that the enumeration starts at the beginning.

If this call succeeds, the application iterates through the devices on the system by repeatedly calling the Next method of the IEnumWIA_DEV_INFO pointer pWiaEnumDevInfo until the method no longer returns S_OK, indicating that the enumeration is complete.

Each call to pWiaEnumDevInfo->Next fills pIWiaPropStg with a pointer to the IWiaPropertyStorage interface that contains property information for a specific device.


Reading Device Properties

Applications use a device's IWiaPropertyStorage interface to read and write device properties. IWiaPropertyStorage inherits all of the methods of the COM interface IPropertyStorage.

In the following example, the application obtains a pointer to the IWiaPropertyStorage interface by using the methods of IEnumWIA_DEV_INFO to enumerate the devices on a system. Applications can also query a WIA item to obtain a pointer to its IWiaPropertyStorage interface.

Device properties include information about a device that describe the device's capabilities and settings. For a list of these properties, see Device Properties.

Among the device properties that are read using IWiaPropertyStorage is the device ID, that is then used to create a WIA device. For more information,see IWiaDevMgr::CreateDevice.

The following example reads the device ID, the device name, and the server name from the array of device properties, and prints these properties to the screen.

hr = pWiaEnumDevInfo->Next(1,&pIWiaPropStg,&ulFetched);
                        if (hr == S_OK) {
                            if(ulFetched != 1){
                                printf(TEXT("Next returned %d item(s), after requesting for 1 item\n"),ulFetched);
                                hr = E_FAIL;
                            }
                            PROPSPEC        PropSpec[3];
                            PROPVARIANT     PropVar[3];

                            memset(PropVar,0,sizeof(PropVar));

                            PropSpec[0].ulKind = PRSPEC_PROPID;
                            PropSpec[0].propid = WIA_DIP_DEV_ID;

                            PropSpec[1].ulKind = PRSPEC_PROPID;
                            PropSpec[1].propid = WIA_DIP_DEV_NAME;

                            PropSpec[2].ulKind = PRSPEC_PROPID;
                            PropSpec[2].propid = WIA_DIP_SERVER_NAME;
                            hr = pIWiaPropStg->ReadMultiple(sizeof(PropSpec)/sizeof(PROPSPEC),
                                PropSpec,
                                PropVar);
                            if (hr == S_OK) {
                                printf(TEXT("Device Name: \t%ws\n"),PropVar[1].bstrVal);
                                printf(TEXT("Device ID: \t%ws\n"),PropVar[0].bstrVal);
                                printf(TEXT("Server Name: \t%ws\n"),PropVar[2].bstrVal);
                                printf(TEXT("\n"));
                                // Free Prop Varient
FreePropVariantArray(sizeof(PropSpec)/sizeof(PROPSPEC),PropVar);
                                // Release Property Storage
                                pIWiaPropStg->Release();
                            } else
                                printf(TEXT("ReadMultiple() Failed while reading device name,server,and deviceID\n"));
}

In this example, the application calls the Next method of the IEnumWIA_DEV_INFO pointer pWiaDevInfo to obtain a pointer to a device's IWiaPropertyStorage interface, which it stores in the variable pIWiaPropStg. For information about enumerating devices, see Enumerating System Devices.

The application then sets up PROPSPEC and PROPVARIANT arrays (PropSpec and PropVar, respectively) to hold property information. These arrays are passed as parameters in the call to ReadMultiple method of the IWiaPropertyStorage pointer pIWiaPropStg. Each element of the PropSpec array contains the type and name of a device property. Upon return, each element of the PropVar contains the value of the device property represented by the corresponding element of the PropSpec array.

The application then calls ReadMultiple property of the IWiaPropertyStorage pointer pIWiaPropStg to retrieve the property information.

The technique used to read and set device properties is the same as that for item properties, the only difference is the type of the WIA item on which you call the appropriate methods. For a list of item properties, see Item Properties.


Creating a Device

Once an application has the device ID of a given device, it can call the IWiaDevMgr::CreateDevice method, which creates a hierarchical tree of IWiaItem objects that represent an imaging device and the image scanning beds, and folders contained on that device.

The following example from the sample application GetImage implements a function that takes a device ID as a parameter. For information about how to obtain a device ID for a particular device, see Reading Device Properties.

BOOL CreateThisDevice(BSTR DeviceID)
{
    //
    // Create a WIA Device (IWiaItem* - pIWiaRootItem)
    //

    HRESULT hr = S_OK;

    hr = g_pIWiaDevMgr->CreateDevice(DeviceID,&g_pIWiaRootItem);
    if (hr != S_OK) {
        printf(TEXT("Failed to Create Device, possible invalid DeviceID\n"));
        return FALSE;
    }
    return TRUE;
}

In this example, g_pIwiaDevMgr is a pointer to the IWiaDevMgr interface, and pIWiaRootItem is a variable that, after the call to CreateDevice, contains the address of a pointer to the root item of the tree that represents the newly created device.


Enumerating Items

When a device is created, WIA creates a hierarchical tree of WIA items that represent the device and the folders and images associated with that device. Use the root item's (the item at the root of the tree that represents the device) EnumChildItems method to create an enumerator object and obtain a pointer to its IEnumWiaItem interface, which is used to navigate the item tree and gain access to the images or scanning beds associated with the device.

The following example demonstrates two functions that, together, recursively enumerate all of the items of a tree, beginning with a root item that is passed to one of the functions.

HRESULT EnumerateAllItems(IWiaItem *pIRootItem)
{
    HRESULT hr = S_OK;
    IEnumWiaItem* pEnumItem = NULL;

    if (pIRootItem != NULL) {
        DisplayItemName(pIRootItem);
        hr = pIRootItem->EnumChildItems(&pEnumItem);

        //
        // we have children so continue to enumerate them
        //

        if (hr == S_OK && pEnumItem != NULL) {
            EnumNextLevel(pEnumItem);
            pEnumItem->Release();
        }
    } else {

        //
        // pIRootItem is NULL!!
        //

        printf(TEXT("RootItem is NULL\n"));
        return E_INVALIDARG;
    }

    return  hr;
}

The previous function takes the parameter pIRootItem, a pointer to the IWiaItem interface of the root item of the item tree to enumerate.

It then calls the EnumChildItems method of pIRootItem to create an enumerator object for the item tree. If this call succeeds, and the enumerator is valid, the function then passes the enumerator to a second function, which follows:

HRESULT EnumNextLevel(IEnumWiaItem *pEnumItem)
{
    IWiaItem *pIWiaItem;
    ULONG     cEnum;
    LONG      lType;
    HRESULT   hResult;

    while (pEnumItem->Next(1,&pIWiaItem,&cEnum) == S_OK) {
        if (pIWiaItem != NULL) {
            DisplayItemName(pIWiaItem);
        } else
            return E_FAIL;

        //
        // find out if the item is a folder, if it is,
        // recursively enumerate
        //

        pIWiaItem->GetItemType(&lType);
        if (lType & WiaItemTypeFolder) {
            IEnumWiaItem *pEnumNext;
            hResult = pIWiaItem->EnumChildItems(&pEnumNext);
            if (hResult == S_OK) {
                EnumNextLevel(pEnumNext);
                pEnumNext->Release();
            }
        }
        pIWiaItem->Release();
    }
    return S_OK;
}

The EnumNextLevel function is passed a pointer to an enumerator object, pEnumItem. It calls this Next method of the object, which fills pIWiaItem with a pointer to the first child item in the enumeration.

The function then checks whether the item is a folder. If it is, it calls the EnumChildItems method of the item, which fills pEnumNext with a pointer to a new enumeration object. EnumNextLevel then passes this pointer to itself in a recursive function call.

In this manner, the function enumerates all branches of the item tree below the root item passed to EnumerateAllItems.


Transferring Image Data

Use the methods of the IWiaDataTransfer interface to transfer data from a WIA device to an application. This interface supports a shared memory window to transfer data from the device object to the application and eliminate unnecessary data copies during marshalling.

Applications must query an image item to obtain a pointer to its IWiaDataTransfer interface, as in the following code sample:

//
    // get IWiaDatatransfer interface
    //

    IWiaDataTransfer *pIWiadataTransfer = NULL;
    hr = pIWiaItem->QueryInterface(IID_IWiaDataTransfer, (void **)&pIWiadataTransfer);

In the previous code, it is assumed that pIWiaItem is a valid pointer to the IWiaItem interface. The call to QueryInterface fills pIWiadataTransfer with a pointer to the IWiaDataTransfer interface of the item referred to by pIWiaItem.

The application then sets the STGMEDIUM structure members. For information, see STGMEDIUM and TYMED.

    if (SUCCEEDED(hr)) {

        //
        // set storage medium
        //

        STGMEDIUM StgMedium;
        StgMedium.tymed    = TYMED_FILE;
        StgMedium.lpszFileName   = "c:\myimages\sample.bmp";
        StgMedium.pUnkForRelease = NULL;
        StgMedium.hGlobal        = NULL;

The filename must include the proper file extension; WIA does not provide file extensions. If the lpszFileName member of StgMedium is NULL, WIA generates a random file name and path for the transferred data. Rename and move this file for easier use.

The application then calls the idtGetData method to execute the data transfer:

                // Execute transfer call
                hr = pIWiadataTransfer->idtGetData(&StgMedium,pIWiaDataCallback);

In the call to idtGetData, the second parameter specifies a pointer to the IWiaDataCallback interface. Applications must implement this interface to receive callbacks during data transfers. For information about implementing this interface, see IWiaDataCallback::BandedDataCallback.

The application then releases the pointers to the IWiaDataTransfer interface and the STGMEDIUM structure.

                //
                // Release IWiadataTransfer Interface
                                pIWiadataTransfer->Release();
 ReleaseStgMedium(&StgMedium);
                } else{
                    printf(TEXT("idtGetData() failed\n"));
                    return FALSE;
} else
        printf(TEXT("QueryInterface(IID_IWiaDataTransfer) failed\n"));


Registering for Events

The following example uses the IWiaDevMgr::RegisterEventCallbackCLSID method to register for notification when any WIA device is connected to the system. Applications can also use IWiaDevMgr::RegisterEventCallbackInterface and IWiaDevMgr::RegisterEventCallbackProgram to register for events. It is assumed that the example is taken from an application that is registered as a COM object.

The call to RegisterEventCallbackCLSID is as follows:

pIWiaDevMgr->RegisterEventCallbackCLSID(WIA_REGISTER_EVENT_CALLBACK,
                                        NULL,
                                        WIA_EVENT_DEVICE_CONNECTED,
                                        pCLSID)

In the previous code, pIWiaDevMgr is a valid pointer to the IWiaDevMgr interface, WIA_REGISTER_EVENT_CALLBACK is a constant that specifies that this call is to register for the event as opposed to unregistering for the event, WIA_EVENT_DEVICE_CONNECTED is a constant that specifies that the application is registering to be notified whenever a device is connected to the user's computer, and pCLSID is a pointer to the registered CLSID of the application.

The application must then implement the IWiaEventCallback::ImageEventCallback method, which is called whenever an event occurs for which the application is registered.

An application can use the IWiaItem::EnumRegisterEventInfo method to enumerate the information about events for which it is registered.


WIA References

The WIA run-time system is divided into the following components:

  • WIA Application Programming Interface
  • WIA Scripting Model


WIA Application Programming Interface

This section contains reference information for the application programming interface (API) elements that are provided by Windows® Image Acquisition (WIA). The reference material is divided into the following categories:

  • Interfaces
  • Structures
  • Constants


Interfaces

This section contains reference information about the interfaces used with the WIA application programming interface (API). The following interfaces are presented:

  • IEnumWIA_DEV_CAPS
  • IEnumWIA_DEV_INFO
  • IEnumWIA_FORMAT_INFO
  • IEnumWiaItem
  • IWiaDataCallback
  • IWiaDataTransfer
  • IWiaDevMgr
  • IWiaEventCallback
  • IWiaItem
  • IWiaItemExtras
  • IWiaPropertyStorage


IEnumWIA_DEV_CAPS

The IEnumWIA_DEV_CAPS interface enumerates the currently available WIA hardware device capabilities. Device capabilities include commands and events that the device supports.

Methods

The methods of the IEnumWIA_DEV_CAPS interface are as follows:

Methods | Description
Clone | Creates an additional instance of the IEnumWIA_DEV_CAPS interface and sends back a pointer to it.
GetCount | Returns the number of elements stored by this enumerator.
Next | Fills an array of pointers to WIA_DEV_CAP structures.
Reset | Restarts the enumeration of device capabilities.
Skip | Skips the specified number of hardware device capabilities during an enumeration of available device capabilities.

The IEnumWIA_DEV_CAPS interface is a specific implementation for WIA of the standard OLE enumeration interface. For details, see IEnumXXXX.

Applications obtain a pointer to the IEnumWIA_DEV_CAPS interface by invoking the IWiaItem::EnumDeviceCapabilities method.

The IEnumWIA_DEV_CAPS interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IEnumXXXX, IWiaItem::EnumDeviceCapabilities.


IEnumWIA_DEV_CAPS::Clone

The IEnumWIA_DEV_CAPS::Clone method creates an additional instance of the IEnumWIA_DEV_CAPS interface and sends back a pointer to it.

HRESULT Clone(
  IEnumWIA_DEV_CAPS **ppIEnum
);

Parameters

ppIEnum
[out] Contains the address of a pointer to the instance of IEnumWIA_DEV_CAPS that IEnumWIA_DEV_CAPS::Clone creates.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications must call the IEnumWIA_DEV_CAPS::Release method (inherited from IUnknown) on the pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_CAPS::GetCount

The IEnumWIA_DEV_CAPS::GetCount method returns the number of elements stored by this enumerator.

HRESULT GetCount(
  ULONG *pcelt
);

Parameters

pcelt
[out] Pointer to a ULONG that receives the number of elements in the enumeration.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_CAPS::Next

The IEnumWIA_DEV_CAPS::Next method fills an array of pointers to WIA_DEV_CAP structures.

HRESULT Next(
  ULONG celt,
  WIA_DEV_CAP *rgelt,
  ULONG *pceltFetched
);

Parameters

celt
[in] Specifies the number of array elements in the array indicated by the rgelt parameter.
rgelt
[out] Pointer to an array of WIA_DEV_CAP structures. IEnumWIA_DEV_CAPS::Next fills this array of structures.
pceltFetched
[in, out, unique] On output, this parameter contains the number of structure pointers actually stored in the array indicated by the rgelt parameter.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications use this method to query the capabilities of each available WIA hardware device. To do so, the application passes a pointer to an array of WIA_DEV_CAP structures that it allocates. It also passes in the number of array elements in the parameter celt. The IEnumWIA_DEV_CAPS::Next method fills the array with structures. Applications then use the structures to enumerate WIA hardware device capabilities.

WIA device capabilities are defined as events and commands that the device supports. Using the rgelt array, IEnumWIA_DEV_CAPS::Next passes a single structure to the application for each event and command that the device supports.

Note that IEnumWIA_DEV_CAPS::Next dynamically allocates the WIA_DEV_CAP structures it provides to applications. Therefore, applications must delete the WIA_DEV_CAP structures they receive through the rgelt parameter. Applications should use SysFreeString() to free the bstrName, nstrDescription, and bstrIcon fields of all WIA_DEV_CAP structures.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_CAPS::Reset

The IEnumWIA_DEV_CAPS::Reset method is used by applications to restart the enumeration of device capabilities.

HRESULT Reset(void);

Parameters

None.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_CAPS::Skip

The IEnumWIA_DEV_CAPS::Skip method skips the specified number of hardware device capabilities during an enumeration of available device capabilities.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Specifies the number of items to skip.

Return Values

If the method succeeds, the method returns S_OK. It returns S_FALSE if it could not skip the specified number of device capabilities. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_INFO

The IEnumWIA_DEV_INFO interface enumerates the currently available WIA hardware devices and their properties. Device information properties describe the installation and configuration of WIA hardware devices.

Methods

The methods of the IEnumWIA_DEV_INFO interface are as follows:

Methods | Description
Clone | Creates an additional instance of the IEnumWIA_DEV_INFO interface and sends back a pointer to it.
GetCount | Returns the number of elements stored by this enumerator.
Next | Fills an array of pointers to IWiaPropertyStorage interfaces.
Reset | Restarts the enumeration of device information.
Skip | Skips the specified number of hardware devices during an enumeration of available devices.

The IEnumWIA_DEV_INFO interface is a specific implementation for WIA of the standard OLE enumeration interface. For details, see IEnumXXXX.

Applications obtain a pointer to the IEnumWIA_DEV_INFO interface by invoking the IWiaDevMgr::EnumDeviceInfo method.

The IEnumWIA_DEV_INFO interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IEnumXXXX, IWiaDevMgr::EnumDeviceInfo, Enumerating System Devices


IEnumWIA_DEV_INFO::Clone

The IEnumWIA_DEV_INFO::Clone method creates an additional instance of the IEnumWIA_DEV_INFO interface and sends back a pointer to it.

HRESULT Clone(
  IEnumWIA_DEV_INFO **ppIEnum
);

Parameters

ppIEnum
[out] Pointer to an IEnumWIA_DEV_INFO interface. This parameter contains a pointer to the IEnumWIA_DEV_INFO interface instance that IEnumWIA_DEV_INFO::Clone creates.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications must call the IEnumWIA_DEV_INFO::Release method (inherited from IUnknown) on the pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_INFO::GetCount

The IEnumWIA_DEV_INFO::GetCount method returns the number of elements stored by this enumerator.

HRESULT GetCount(
  ULONG *pcelt
);

Parameters

pcelt
[out] This parameter points to a ULONG that receives the number of elements in the enumeration.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_INFO::Next

The IEnumWIA_DEV_INFO::Next method fills an array of pointers to IWiaPropertyStorage interfaces.

HRESULT Next(
  ULONG celt,
  IWiaPropertyStorage **rgelt,
  ULONG *pceltFetched
);

Parameters

celt
[in] Specifies the number of array elements in the array indicated by the rgelt parameter.
rgelt
[out] Receives the address of an array of IWiaPropertyStorage interface pointers. IEnumWIA_DEV_INFO::Next fills this array with interface pointers.
pceltFetched
[in, out, unique] On output, this parameter contains the number of interface pointers actually stored in the array indicated by the rgelt parameter.

Return Values

While there are devices left to enumerate, this method returns S_OK. It returns S_FALSE when the enumeration is finished. If the method fails, it returns a standard COM error code.

Remarks

Applications use this method to query the properties of each available WIA hardware device. To do so, the application passes an array of IWiaPropertyStorage interface pointers that it allocates. It also passes the number of array elements in the parameter celt. The IEnumWIA_DEV_INFO::Next method fills the array with pointers to IWiaPropertyStorage interfaces. Applications can query the interfaces for the properties that the device supports.

Applications must call the IWiaPropertyStorage::Release method (inherited from IUnknown) on the interface pointers they receive through the rgelt parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_INFO::Reset

The IEnumWIA_DEV_INFO::Reset method is used by applications to restart the enumeration of device information.

HRESULT Reset(void);

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_DEV_INFO::Skip

The IEnumWIA_DEV_INFO::Skip method skips the specified number of hardware devices during an enumeration of available devices.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Specifies the number of devices to skip.

Return Values

If the method succeeds, the method returns S_OK. If it is unable to skip the specified number of devices, it returns S_FALSE. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_FORMAT_INFO

Use the IEnumWIA_FORMAT_INFO interface to enumerate the format and media type information for a device.

Methods

The methods of the IEnumWIA_FORMAT_INFO interface are as follows:

Methods | Description
Clone | Creates an additional instance of the IEnumWIA_FORMAT_INFO interface and returns an interface pointer to the new interface.
GetCount | Returns the number of elements stored by this enumerator.
Next | Returns an array of WIA_FORMAT_INFO structures.
Reset | Sets the enumeration back to the first WIA_FORMAT_INFO structure.
Skip | Skips the specified number of structures in the enumeration.

The IEnumWIA_FORMAT_INFO interface is a specific implementation for WIA of the standard COM enumeration interface. For details, see IEnumXXXX.

Applications obtain a pointer to the IEnumWIA_FORMAT_INFO interface by invoking the idtEnumWIA_FORMAT_INFO method of an item's IWiaDataTransfer interface.

The IEnumWIA_FORMAT_INFO interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IEnumXXXX, idtEnumWIA_FORMAT_INFO


IEnumWIA_FORMAT_INFO::Clone

The IEnumWIA_FORMAT_INFO::Clone method creates an additional instance of the IEnumWIA_FORMAT_INFO interface and returns an interface pointer to the new interface.

HRESULT Clone(
  IEnumWIA_FORMAT_INFO **ppIEnum
);

Parameters

ppIEnum
[out] Pointer to a new IEnumWIA_FORMAT_INFO interface.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications must call the IEnumWIA_FORMAT_INFO::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_FORMAT_INFO::GetCount

The IEnumWIA_FORMAT_INFO::GetCount method returns the number of elements stored by this enumerator.

HRESULT GetCount(
  ULONG *pcelt
);

Parameters

pcelt
[out] Pointer to a ULONG that receives the number of elements in the enumeration.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_FORMAT_INFO::Next

The IEnumWIA_FORMAT_INFO::Next method returns an array of WIA_FORMAT_INFO structures.

HRESULT Next(
  ULONG celt,
  WIA_FORMAT_INFO *rgelt,
  ULONG *pceltFetched
);

Parameters

celt
[in] Specifies the number of elements requested.
rgelt
[out] Receives the address of the array of WIA_FORMAT_INFO structures.
pceltFetched
[in, out, unique] On output, receives the address of a ULONG that contains the number of WIA_FORMAT_INFO structures actually returned in the rgelt parameter.

Return Values

If the enumeration is continuing, this method returns S_OK and sets the value pointed to by pceltFetched to the number of capabilities returned. If the enumeration is complete, it returns S_FALSE and sets the value pointed to by pceltFetched to zero. If the method fails, it returns a standard COM error.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_FORMAT_INFO::Reset

The IEumWIA_FORMAT_INFO::Reset method sets the enumeration back to the first WIA_FORMAT_INFO structure.

HRESULT Reset(void);

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWIA_FORMAT_INFO::Skip

The IEnumWIA_FORMAT_INFO::Skip method skips the specified number of structures in the enumeration.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Specifies the number of structures to skip.

Return Values

This method returns S_OK if it is able to skip the specified number of elements. It returns S_FALSE if it is unable to skip the specified number of elements. If the method fails, it returns a standard COM error.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWiaItem

The IEnumWiaItem interface is used by applications to enumerate IWiaItem objects in the tree's current folder. The WIA run-time system represents every WIA hardware device to applications as a hierarchical tree of IWiaItem objects.

Methods

The methods of the IEnumWiaItem interface are as follows:

Methods | Description
Clone | Creates an additional instance of the IEnumWiaItem interface and sends back a pointer to it.
GetCount | Returns the number of elements stored by this enumerator.
Next | Fills an array of pointers to IWiaItem interfaces.
Reset | Restarts the enumeration of item information.
Skip | Skips the specified number of items during an enumeration of available IWiaItem objects.

The IEnumWiaItem interface is a specific implementation for WIA of the standard COM enumeration interface. For details, see IEnumXXXX.

Applications obtain a pointer to the IEnumWiaItem interface by invoking the IWiaItem::EnumChildItems method.

The IEnumWiaItem interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IEnumXXXX, IWiaItem::EnumChildItems, Enumerating Items


IEnumWiaItem::Clone

The IEnumWiaItem::Clone method creates an additional instance of the IEnumWiaItem interface and sends back a pointer to it.

HRESULT Clone(
  IEnumWiaItem **ppIEnum
);

Parameters

ppIEnum
[out] Pointer to the IEnumWiaItem interface. Receives the address of the IEnumWiaItem interface instance that IEnumWiaItem::Clone creates.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications must call the IEnumWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWiaItem::GetCount

The IEnumWiaItem::GetCount method returns the number of elements stored by this enumerator.

HRESULT GetCount(
  ULONG *pcelt
);

Parameters

pcelt
[out] Pointer to a ULONG that receives the number of elements in the enumeration.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWiaItem::Next

The IEnumWiaItem::Next method fills an array of pointers to IWiaItem interfaces.

HRESULT Next(
  ULONG celt,
  IWiaItem **ppIWiaItem,
  ULONG *pceltFetched
);

Parameters

celt
[in] Specifies the number of array elements in the array indicated by the ppIWiaItemt parameter.
ppIWiaItem
[out] Receives the address of an array of IWiaItem interface pointers. IEnumWiaItem::Next fills this array with interface pointers.
pceltFetched
[in, out, unique] On output, this parameter receives the number of interface pointers actually stored in the array indicated by the ppIWiaItem parameter. When the enumeration is complete, this parameter will contain zero.

Return Values

If the method succeeds, the method returns S_OK. When the enumeration is complete, it returns S_FALSE. If the method fails, it returns a standard COM error code.

Remarks

The WIA run-time system represents WIA hardware devices as a hierarchical tree of IWiaItem objects. Applications use the IEnumWiaItem::Next method to obtain an IWiaItem interface pointer for each item in the current folder of a hardware device's IWiaItem object tree.

To obtain the list of pointers, the application passes an array of IWiaItem interface pointers that it allocates. It also passes the number of array elements in the parameter celt. The IEnumWiaItem::Next method fills the array with pointers to IWiaItem interfaces.

Until the enumeration process completes, the IEnumWiaItem::Next method returns S_OK. Each time it does, it sets the value pointed to by pceltFetched to the number of items it inserted into the array. When IEnumWiaItem::Next finishes the process of enumerating IWiaItem objects, it returns S_FALSE and sets the memory location pointed to by pceltFetched to zero.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWiaItem::Reset

The IEnumWiaItem::Reset method is used by applications to restart the enumeration of item information.

HRESULT Reset(void);

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IEnumWiaItem::Skip

The IEnumWiaItem::Skip method skips the specified number of items during an enumeration of available IWiaItem objects.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Specifies the number of items to skip.

Return Values

If the method succeeds, the method returns S_OK. If it is unable to skip the specified number of items, it returns S_FALSE. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataCallback

The IWiaDataCallback interface provides an application callback mechanism during data transfers from WIA hardware devices to applications. It supports the following method:

Method | Description
BandedDataCallback | Provides data transfer status notifications.

The IWiaDataCallback interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataCallback::BandedDataCallback

The IWiaDataCallback::BandedDataCallback method is periodically called by WIA data transfer methods of the IWiaDataTransfer interface. It provides data transfer status notifications.

HRESULT BandedDataCallback(
  LONG lMessage,
  LONG lStatus,
  LONG lPercentComplete,
  LONG lOffset,
  LONG lLength,
  LONG lReserved,
  LONG lResLength,
  BYTE *pbBuffer
);

Parameters

lMessage
[in] Specifies a constant that indicates the reason for the callback. Can be one of the following values:
Constant | Meaning
IT_MSG_DATA | The WIA system is transferring data to the application.
IT_MSG_DATA_HEADER | The application is receiving a header prior to receiving the actual data.
IT_MSG_NEW_PAGE | The data transfer is beginning a new page.
IT_MSG_STATUS | This invocation of the callback is sending only status information.
IT_MSG_TERMINATION | The data transfer is complete.

lStatus
[in] Specifies a constant that indicates the status of the WIA device. Can be set to a combination of the following:
Constant | Meaning
IT_STATUS_TRANSFER_FROM_DEVICE | Data is currently being transferred from the WIA device.
IT_STATUS_PROCESSING_DATA | Data is currently being processed.
IT_STATUS_TRANSFER_TO_CLIENT | Data is currently being transferred to the client's data buffer.

lPercentComplete
[in] Specifies the percentage of the total data that has been transferred so far.
lOffset
[in] Specifies an offset, in bytes, from the beginning of the buffer where the current band of data begins.
lLength
[in] Specifies the length, in bytes, of the current band of data.
lReserved
[in] Reserved for internal use by the WIA run-time system.
lResLength
[in] Reserved for internal use by the WIA run-time system.
pbBuffer
[in] Pointer to the data buffer.

Return Values

If the method succeeds, the method returns S_OK. To cancel the data transfer, it returns S_FALSE. If the method fails, it returns a standard COM error code.

Remarks

Your application must provide the IWiaDataCallback::BandedDataCallback method. This method is periodically invoked by the data transfer methods of the IWiaDataTransfer interface. It provides status messages to the application during the data transfer. By returning S_FALSE, your program can also use this method to prematurely terminate the data transfer.

When this method is invoked, the lMessage parameter will contain the reason for the call. Not all parameters will contain data on all calls. For example, when IWiaDataCallback::BandedDataCallback is invoked with a message of IT_MSG_TERMINATION, it should not attempt to use the values in the pbBuffer, lOffset, and lLength parameters.

If the value of lMessage is IT_MSG_DATA, the buffer pointed to by pbBuffer contains a band of image data. The lOffset parameter contains an offset in bytes from the beginning of the buffer where the current band of data begins. The lLength parameter specified the length in bytes of the current band of data.

During calls where lMessage is set to IT_MSG_DATA or IT_MSG_STATUS, the lStatus parameter contains a valid value. Its contents should not be used when lMessage contains other values.

If lMessage is IT_MSG_DATA_HEADER, the pbBuffer parameter points to a WIA_DATA_CALLBACK_HEADER structure.

Example

class CDataCallback : public IWiaDataCallback
{
private:
    ULONG m_cRef;               // Object reference count.
    PBYTE m_pBuffer;            // Data buffer
    LONG  m_BufferLength;       // Length of buffer
    LONG  m_BytesTransfered;    // Total number of bytes transferred
    LONG  m_cFormat;            // Data format

public:
    //
    // Constructor, initialization, and destructor methods.
    //

    CDataCallback();
    ~CDataCallback();

    //
    // IUnknown
    //

    HRESULT _stdcall QueryInterface(const IID&,void**);
    ULONG   _stdcall AddRef();
    ULONG   _stdcall Release();

    //
    // IBandedCallback
    //

    HRESULT _stdcall BandedDataCallback(
        LONG lMessage,
        LONG lStatus,
        LONG lPercentComplete,
        LONG lOffset,
        LONG lLength,
        LONG lReserved,
        LONG lResLength,
        BYTE *pbBuffer);
};

//
// The application must instantiate the CDataCallback object and
// QueryInterface for the IWaiDataCallback interface.
// The application then calls the IWiaDataTransfer::idtGetBandedData
// method and passes it the IWiaDataCallback interface pointer.
//
// The following code fragment demonstrates the application's call
// to obtain data. It assumes that pIWiaDataTransfer is a valid
// pointer to an IWiaDataTransfer interface. Also, the application
// must create and properly initialize a WIA_DATA_TRANSFER_INFO
// structure. In the following code fragment, this structure is
// indicated by the parameter pWiaDataTransfer. The pWiaIDataCallback
// parameter is assumed to be a valid pointer to an IWiaDataCallback
// interface.

hr = pIWiaDataTransfer->idtGetBandedData(
         pWiaDataTransferInfo,    // Struct pointer
         pWiaIDataCallback);      // callback interface pointer

//
// The IWiaDataTransfer::idtGetBandedData method will periodically
// call the IWiaDataCallback::BandedDataCallback method with status
// messages. It then sends the callback a data header message
// followed by one or more data messages. It concludes by sending a
// termination message.

HRESULT _stdcall CDataCallback::BandedDataCallback(
                     LONG lMessage,
                     LONG lStatus,
                     LONG lPercentComplete,
                     LONG lOffset,
                     LONG lLength,
                     LONG lReserved,
                     LONG lResLength,
                     BYTE *pbDataBuffer)
{
    switch (lMessage)
    {
        case IT_MSG_DATA_HEADER:
        {
            //
            //data header contains bitmap final size
            //

            PWIA_DATA_CALLBACK_HEADER pHeader =
                 (PWIA_DATA_CALLBACK_HEADER)pbData;

            m_pBuffer = (PBYTE)LocalAlloc(LPTR,pHeader->lBufferSize);
            m_BufferLength = pHeader->lBufferSize;
            m_BytesTransfered = 0;
            m_cFormat = pHeader->lFormat;
        }
         break;

         case IT_MSG_DATA:
         {
             if (m_pBuffer != NULL)
             {
                 m_pDlg->UpdateProgress(lPercentComplete);
                 memcpy(m_pBuffer + lOffset, pbData, lLength);
                 m_BytesTransfered += lLength;
             }
         }
         break;

         case IT_MSG_STATUS:
         {
             if (lStatus & IT_STATUS_TRANSFER_FROM_DEVICE)
             {
                 m_pDlg->UpdateText(TEXT("Transfer from device"));
             }
             else if (lStatus & IT_STATUS_PROCESSING_DATA)
             {
                 m_pDlg->UpdateText(TEXT("Processing Data"));
             }
             else if (lStatus & IT_STATUS_TRANSFER_TO_CLIENT)
             {
                 m_pDlg->UpdateText(TEXT("Transfer to Client"));
             }

             m_pDlg->UpdateProgress(lPercentComplete);
         }
         break;
     } // end switch

   return S_OK;
}

This example demonstrates one possible way to implement the IWiaDataCallback::BandedDataCallback method.

The example application code defines the CDataCallback object, that it derives from the IWiaDataCallback interface. The application must instantiate a CDataCallback object. It then calls CDataCallback::QueryInterface to obtain an IWiaDataCallback interface pointer. When the application is ready to receive data, it invokes the IWiaDataTransfer::idtGetBandedData method and passes the method a pointer to the IWiaDataCallback interface.

Periodically, the IWiaDataTransfer::idtGetBandedData method uses the IWiaDataCallback interface pointer to invoke the CDataCallback::BandedDataCallback method of the application. The first invocations send status messages. These are followed by a call that transfers a data header to the callback method. After the application receives the data header, IWiaDataTransfer::idtGetBandedData invokes CDataCallback::BandedDataCallback to transfer data to the application. When the data transfer is complete. it calls the callback a final time to transmit a termination message.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataTransfer

The IWiaDataTransfer interface is a high performance data transfer interface. This interface supports a shared memory window to transfer data from the device object to the application, and eliminates unnecessary data copies during marshalling. A callback mechanism is provided in the form of the IWiaDataCallback interface. It enables applications to obtain data transfer status notification, transfer data from the WIA device to the application, and cancel pending data transfers.

Methods

The IWiaDataTransfer interface includes the following methods:

Methods | Description
idtEnumWIA_FORMAT_INFO | Creates a banded transfer implementation of the standard COM enumerator interface.
idtGetBandedData | Transfers a band of data from a hardware device to an application.
idtGetData | Retrieves complete files from a WIA device.
idtQueryGetData | Query a WIA device to determine what types of data formats it supports.

The IWiaDataTransfer interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataTransfer::idtEnumWIA_FORMAT_INFO

The IWiaDataTransfer::idtEnumWIA_FORMAT_INFO method creates a banded transfer implementation of the IEnumWIA_FORMAT_INFO interface.

HRESULT idtEnumWIA_FORMAT_INFO(
  IEnumWIA_FORMAT_INFO **lpEnum
);

Parameters

lpEnum
[out] Receives the address of a pointer to the IEnumWIA_FORMAT_INFO interface.

Return Values

If it fails for any reason other than those specified in the following table, this method will return a standard COM error.

Return Value | Meaning
E_INVALIDARG | The lpEnum parameter is not the address of a pointer to the IEnumWIA_FORMAT_INFO interface.
E_OUTOFMEMORY | There is not enough memory to create the enumerator object.
S_OK | The enumerator object was successfully created.

Remarks

This method creates the IEnumWIA_FORMAT_INFO interface that applications use to enumerate an array of WIA_FORMAT_INFO structures. This provides applications with the ability to determine the formats and media types of incoming data when transferring banded data.

Note that applications must call the IEnumWIA_FORMAT_INFO::Release method (inherited from IUnknown) on the pointers they receive through the lpEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataTransfer::idtGetBandedData

The IWiaDataTransfer::idtGetBandedData method transfers a band of data from a hardware device to an application. For efficiency, applications retrieve data from WIA hardware devices in successive bands.

HRESULT idtGetBandedData(
  PWIA_DATA_TRANSFER_INFO pWiaDataTransInfo,
  IWiaDataCallback *pIWiaDataCallback
);

Parameters

pWiaDataTransInfo
[in, unique] Pointer to the WIA_DATA_TRANSFER_INFO structure.
pIWiaDataCallback
[in, unique] Pointer to the IWiaDataCallback interface. Periodically, this method will call the IWiaDataCallback::BandedDataCallback method to provide the application with data transfer status notification.

Return Values

This method can return any one of the following values:

Return Value | Meaning
E_INVALIDARG | One or more parameters to this method contain invalid data.
E_OUTOFMEMORY | This method cannot allocate enough memory to complete its operation.
E_UNEXPECTED | An unknown error occurred.
S_FALSE | The application canceled the operation.
S_OK | The image was successfully acquired.
STG_E_MEDIUMFULL | The storage medium the application is using to acquire the image is full.
WIA_S_NO_DEVICE_AVAILABLE | There are no WIA hardware devices attached to the user's computer.

This method will return a value specified in Error Codes, or a standard COM error if it fails for any reason other than those specified in the preceding table.

Remarks

The IWiaDataTransfer::idtGetBandedData method allocates a section of memory to transfer data without requiring an extra data copy through the Component Object Model/Remote Procedure Call (COM/RPC) marshalling layer. This memory section is shared between the application and the hardware device's item tree.

Optionally, the application can pass in a pointer to a block of memory that IWiaDataTransfer::idtGetBandedData will use as its shared section. The application passes this handle by storing the pointer in the ulSection member of the WIA_DATA_TRANSFER_INFO structure prior to calling IWiaDataTransfer::idtGetBandedData.

Applications can improve performance by using double buffering. To do this, applications must set the bDoubleBuffer member of the WIA_DATA_TRANSFER_INFO structure to TRUE. The IWiaDataTransfer::idtGetBandedData method will divide the data buffer in half. When one half of the buffer is full, IWiaDataTransfer::idtGetBandedData will send a notification to the application using the IWiaDataCallback pointer passed in through the pIWiaDataCallback parameter. While the application is retrieving the data from the full half of the buffer, the device driver can fill the other half with data.

The format of the data transfer is determined by the values of the item's WIA_IPA_FORMAT and WIA_IPA_TYMED properties. The application sets these properties with calls to the IWiaPropertyStorage::WriteMultiple method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataTransfer::idtGetData

The IWiaDataTransfer::idtGetData method retrieves complete files from a WIA device.

HRESULT idtGetData(
  LPSTGMEDIUM pMedium,
  IWiaDataCallback *pIWiaDataCallback
);

Parameters

pMedium
[in, out] Pointer to the STGMEDIUM structure.
pIWiaDataCallback
[in, unique] Pointer to the IWiaDataCallback interface.

Return Values

This method can return any one of the following values:

Return Value | Meaning
E_INVALIDARG | One or more parameters to this method contain invalid data.
E_OUTOFMEMORY | This method cannot allocate enough memory to complete its operation.
E_UNEXPECTED | An unknown error occurred.
S_FALSE | The application canceled the operation.
S_OK | The image was successfully acquired.
STG_E_MEDIUMFULL | The storage medium the application is using to acquire the image is full.
WIA_S_NO_DEVICE_AVAILABLE | There are no WIA hardware devices attached to the user's computer.

This method will return a value specified in Error Codes, or a standard COM error if it fails for any reason other than those specified in the preceding table.

Remarks

In most respects, this method operates identically to the IDataObject::GetData method. The primary difference is that IWiaDataTransfer::idtGetData provides an additional parameter for a pointer to the IWiaDataCallback interface. Applications use this optional parameter to obtain status notifications during the data transfer. If no status notifications are needed, it should be set to zero.

The format of the data transfer is determined by the values of the item's WIA_IPA_FORMAT and WIA_IPA_TYMED properties. The application sets these properties with calls to the IWiaPropertyStorage::WriteMultiple method.

Unlike the IWiaDataTransfer::idtGetBandedData method, IWiaDataTransfer::idtGetData transfers a complete file from a WIA device to an application rather than just a single band of data. The pMedium parameter is a pointer to the STGMEDIUM structure which contains information on the storage medium to be used for the data transfer. Programs use the pIWiaDataCallback parameter to pass this method a pointer to the IWiaDataCallback interface. Periodically, this method will use the interface pointer to invoke the IWiaDataCallback::BandedDataCallback method and provide the application with status information about the data transfer in progress.

If the value returned by this method is a COM SUCCESS value or the transfer is a multipage file transfer, and the error code returned is WIA_ERROR_PAPER_JAM, WIA_ERROR_PAPER_EMPTY, or WIA_ERROR_PAPER_PROBLEM, WIA does not delete the file.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDataTransfer::idtQueryGetData

The IWiaDataTransfer::idtQueryGetData method is used by applications to query a WIA device to determine what types of data formats it supports.

HRESULT idtQueryGetData(
  WIA_FORMAT_INFO ** pfe
);

Parameters

pfe
[in, unique] The address of a pointer to a WIA_FORMAT_INFOstructure.

Return Values

If this method succeeds, it returns S_OK. Otherwise it returns a value specified in Error Codes, or a standard COM error.

Remarks

This method queries a device to determine the data formats it supports. Prior to a data transfer, an application can fill in the WIA_FORMAT_INFO structure with the intended medium and data format information. It then calls IWiaDataTransfer::idtQueryGetData and receives a return value of S_OK if the data format and media type are supported by this device.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr

Applications use the IWiaDevMgr interface to create and manage image acquisition devices. They also use it to register to receive device events.

Methods

The methods of the IWiaDevMgr interface are as follows:

Methods | Description
CreateDevice | Creates a hierarchical tree of IWiaItem objects for a WIA device.
EnumDeviceInfo | Enumerate property information for each available WIA device.
GetImageDlg | Displays one or more dialog boxes that enable a user to acquire an image from a WIA device and write the image to a specified file.
RegisterEventCallbackCLSID | Registers an application to receive events even if the application may not be running.
RegisterEventCallbackInterface | Registers a running application WIA event notification.
RegisterEventCallbackProgram | Registers an application to receive device events.
SelectDeviceDlg | Displays a dialog box that enables the user to select a hardware device for image acquisition.
SelectDeviceDlgID | Displays a dialog box that enables the user to select a hardware device for image acquisition.

The IWiaDevMgr interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::CreateDevice

The IWiaDevMgr::CreateDevice creates a hierarchical tree of IWiaItem objects for a WIA device.

HRESULT CreateDevice(
  BSTR bstrDeviceID,
  IWiaItem **ppWiaItemRoot
);

Parameters

bstrDeviceID
[in] Specifies the unique identifier of the WIA device.
ppWiaItemRoot
[out] Pointer to a pointer to the IWiaItem interface of the root item in the hierarchical tree for the WIA device.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications use the IWiaDevMgr::CreateDevice method to create a device object for the WIA devices specified by the bstrDeviceID parameter.

When it returns, the IWiaDevMgr::CreateDevice method stores an address of a pointer in the parameter ppWiaItemRoot. The pointer points to the root item of the tree of IWiaItem objects created by WiaDevMgr::CreateDevice. Applications can use this tree of objects to control and retrieve data from the WIA device.

Note that applications must call the IWiaItem::Release method (inherited from IUnknown) on the pointers they receive through the ppWiaItemRoot parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::EnumDeviceInfo

Applications use the IWiaDevMgr::EnumDeviceInfo method to enumerate property information for each available WIA device.

HRESULT EnumDeviceInfo(
  LONG lFlag,
  IEnumWIA_DEV_INFO **ppIEnum
);

Parameters

lFlag
[in] Specifies the types of WIA devices to enumerate. Should be set to WIA_DEVINFO_ENUM_LOCAL.
ppIEnum
[out, retval] Receives the address of a pointer to the IEnumWIA_DEV_INFO interface.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

The IWiaDevMgr::EnumDeviceInfo method creates an enumerator object, that supports the IEnumWIA_DEV_INFO interface. IWiaDevMgr::EnumDeviceInfo stores a pointer to the IEnumWIA_DEV_INFO interface in the parameter ppIEnum. Applications can use the IEnumWIA_DEV_INFO interface pointer to enumerate the properties of each WIA device attached to the user's computer.

Applications must call the IEnumWIA_DEV_INFO::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::GetImageDlg

The IWiaDevMgr::GetImageDlg method displays one or more dialog boxes that enable a user to acquire an image from a WIA device and write the image to a specified file. This method combines the functionality of SelectDeviceDlg to completely encapsulate image acquisition within a single API call.

HRESULT GetImageDlg(
  HWND hwndParent,
  LONG lDeviceType,
  LONG lFlags,
  LONG lIntent,
  IWiaItem *pItemRoot,
  BSTR bstrFilename,
  GUID *pguidFormat
);

Parameters

hwndParent
[in] Handle of the window that owns the Get Image dialog box.
lDeviceType
[in] Specifies which type of WIA device to use. Is set to StiDeviceTypeDefault, StiDeviceTypeScanner, or StiDeviceTypeDigitalCamera.
lFlags
[in] Specifies dialog box behavior. Can be set to the following values:
Flag | Meaning
0 | Default behavior.
WIA_SELECT_DEVICE_NODEFAULT | Force this method to display the Select Device dialog box. For more information, see the Remarks section of this reference page.
WIA_DEVICE_DIALOG_SINGLE_IMAGE | Restrict image selection to a single image in the device image acquisition dialog box.
WIA_DEVICE_DIALOG_USE_COMMON_UI | Use the system UI, if available, rather than the vendor-supplied UI. If the system UI is not available, the vendor UI is used. If neither UI is available, the function returns E_NOTIMPL.

lIntent
[in] Specifies what type of data the image is intended to represent. For a list of image intent values, see Image Intent Constants.
pItemRoot
[in] Pointer to the interface of the hierarchical tree of IWiaItem objects returned by IWiaDevMgr::CreateDevice.
bstrFilename
[in] Specifies the name of the file to which the image data is written.
pguidFormat
[in, out] On input, contains a pointer to a GUID that specifies the format to use. On output, holds the format used. Pass IID_NULL to use the default format.

Return Values

GetImageDlg returns S_FALSE if the user cancels the device selection or image acquisition dialog boxes, WIA_S_NO_DEVICE_AVAILABLE if no WIA device is currently available, E_NOTIMPL if no UI is available, and S_OK if the data is transferred successfully.

IWiaDevMgr::GetImageDlg returns a value specified in Error Codes, or a standard COM error if it fails for any reason other than those specified.

Remarks

Invoking this method displays a dialog box that enables users to acquire images. It can also display the Select Device dialog box created by the IWiaDevMgr::SelectDeviceDlg method.

If the application passes NULL for the value of the pItemRoot parameter, IWiaDevMgr::GetImageDlg displays the Select Device dialog box that lets the user select the WIA input device. If the application specifies a WIA input device by passing a pointer to the device's item tree through the pItemRoot parameter, IWiaDevMgr::GetImageDlg does not display the Select Device dialog box. Instead, it will use the specified input device to acquire the image.

When using the Select Device dialog box, applications can specify types of WIA input devices. To do so, they must set the pItemRoot parameter to NULL and pass the appropriate constants through the lDeviceType parameter. If more than one device of the specified type is present, the IWiaDevMgr::GetImageDlg displays the Select Device dialog box to let the user select which device will be used.

If IWiaDevMgr::GetImageDlg finds only one matching device, it will not display the Select Device dialog box. Instead, it will select the matching device. You can override this behavior and force IWiaDevMgr::GetImageDlg to display the Select Device dialog box by passing WIA_SELECT_DEVICE_NODEFAULT as the value for the lFlags parameter.

It is recommended that applications make device and image selection available through a menu item named From scanner or camera on the File menu.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::RegisterEventCallbackCLSID

The IWiaDevMgr::RegisterEventCallbackCLSID method registers an application to receive events even if the application may not be running.

HRESULT RegisterEventCallbackCLSID(
  LONG lFlags,
  BSTR bstrDeviceID,
  const GUID *pEventGUID,
  const GUID *pClsID,
  BSTR bstrName,
  BSTR bstrDescription,
  BSTR bstrIcon
);

Parameters

lFlags
[in] Specifies registration flags. Can be set to the following values:
Registration Flag | Meaning
WIA_REGISTER_EVENT_CALLBACK | Register for the event.
WIA_UNREGISTER_EVENT_CALLBACK | Delete the registration for the event.

bstrDeviceID
[in] Specifies a device identifier. Pass NULL to register for the event on all WIA devices.
pEventGUID
[in] Specifies the event for which the application is registering. For a list of standard events, see WIA Event Identifiers.
pClsID
[in, unique] Pointer to the application's class ID (CLSID). The WIA run-time system uses the application's CLSID to start the application when an event occurs for which it is registered.
bstrName
[in] Specifies the name of the application that registers for the event.
bstrDescription
[in Specifies a text description of the application that registers for the event.
bstrIcon
[in] Specifies the name of an image file to be used for the icon for the application that registers for the event.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

WIA applications use this method to register to receive hardware device events. Once programs call IWiaDevMgr::RegisterEventCallbackCLSID, they are registered to receive WIA device events even if they are not running.

When the event occurs, the WIA system determines which application is registered to receive the event. It uses the CoCreateInstance function and the class ID specified in the pClsID parameter to create an instance of the application. It then calls the application's IWiaEventCallback::ImageEventCallback method to transmit the event information.

An application can invoke the IWiaItem::EnumRegisterEventInfo method to enumerate event registration information.

If the application is not a registered COM component and is not compatible with the WIA architecture, developers should use IWiaDevMgr::RegisterEventCallbackInterface instead of this method.

Note In a multi-threaded application, there is no guarantee that the event notification callback will come in on the same thread that registered the callback.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::RegisterEventCallbackInterface

The IWiaDevMgr::RegisterEventCallbackInterface method registers a running application WIA event notification.

HRESULT RegisterEventCallbackInterface(
  LONG lFlags,
  BSTR bstrDeviceID,
  const GUID *pEventGUID,
  IEventCallback *pIEventCallback,
  IUnknown **pEventObject
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.
bstrDeviceID
[in] Specifies a device identifier. Pass NULL to register for the event on all WIA devices.
pEventGUID
[in] Specifies the event for which the application is registering. For a list of standard events, see WIA Event Identifiers.
pIEventCallback
[in, unique] Pointer to the IEventCallback interface that the WIA system used to send the event notification.
pEventObject
[out] Receives the address of a pointer to the IUnknown interface.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

When they begin executing, WIA applications use this method to register to receive hardware device events. This prevents the application from being restarted when another event for which it is registered occurs. Once a program invokes IWiaDevMgr::RegisterEventCallbackInterface to register itself to receive WIA events from a device, the registered events are routed to the program by the WIA system.

Applications use the IWiaItem::EnumRegisterEventInfo method to retrieve a pointer to an enumerator object for event registration properties.

Applications can unregister for events by using the IUnknown pointer returned through the pEventObject parameter to call the IUnknown::Release method.

Note In a multi-threaded application, there is no guarantee that the event notification callback will come in on the same thread that registered the callback.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::RegisterEventCallbackProgram

The IWiaDevMgr::RegisterEventCallbackProgram method registers an application to receive device events. It is primarily provided for backward compatibility with applications that were not written for WIA.

HRESULT RegisterEventCallbackProgram(
  LONG lFlags,
  BSTR bstrDeviceID,
  const GUID *pEventGUID,
  BSTR bstrCommandLine,
  BSTR bstrName,
  BSTR bstrDescription,
  BSTR bstrIcon
);

Parameters

lFlags
[in] Specifies registration flags. Can be set to the following values:
Registration Flag | Meaning
WIA_REGISTER_EVENT_CALLBACK | Register for the event.
WIA_UNREGISTER_EVENT_CALLBACK | Delete the registration for the event.

bstrDeviceID
Specifies a device identifier. Pass "*" to register for the event on all WIA devices.
pEventGUID
[in] Specifies the event for which the application is registering. For a list of valid event GUIDs, see WIA Event Identifiers.
bstrCommandLine
[in] Specifies a string that contains the full path name and the appropriate command-line arguments needed to invoke the application.
bstrName
[in] Specifies the name of the application. This name is displayed to the user when multiple applications register for the same event.
bstrDescription
[in] Specifies the description of the application. This description is displayed to the user when multiple applications register for the same event.
bstrIcon
[in] Specifies the icon that represents the application. The icon is displayed to the user when multiple applications register for the same event. The string contains the name of the application and the 0-based index of the icon (there may be more than one icon that represent application) separated by a comma. For example, "MyApp, 0".

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Use IWiaDevMgr::RegisterEventCallbackProgram to register for hardware device events. When an event occurs for which an application is registered, the application is launched and the event information is transmitted to the application.

Applications use the IWiaItem::EnumRegisterEventInfo method to retrieve a pointer to an enumerator object for event registration properties.

Programs should only use the IWiaDevMgr::RegisterEventCallbackProgram method for backward compatibility with applications not written for the WIA architecture. New applications should use the Component Object Model (COM) interfaces provided by the WIA architecture. Specifically, they should call IWiaDevMgr::RegisterEventCallbackInterface or IWiaDevMgr::RegisterEventCallbackCLSID to register for device events.

Typically, this method is called by an install program or a script. The install program or script registers the application to receive WIA device events. When the event occurs, the application will be started by the WIA run-time system.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::SelectDeviceDlg

The IWiaDevMgr::SelectDeviceDlg displays a dialog box that enables the user to select a hardware device for image acquisition.

HRESULT SelectDeviceDlg(
  HWND hwndParent,
  LONG lDeviceType,
  LONG lFlags,
  BSTR *pbstrDeviceID,
  IWiaItem **ppItemRoot
);

Parameters

hwndParent
[in] Handle of the window that owns the Select Device dialog box.
lDeviceType
[in] Specifies which type of WIA device to use. Can be set to StiDeviceTypeDefault, StiDeviceTypeScanner, or StiDeviceTypeDigitalCamera.
lFlags
[in] Specifies dialog box behavior. Can be set to any of the following values:
Constant | Meaning
0 | Use the default behavior.
WIA_SELECT_DEVICE_NODEFAULT | Display the dialog box even if there is only one matching device. For more information, see the Remarks section of this reference page.

pbstrDeviceID
[in, out] On output, receives a string which contains the device's identifier string. On input, pass the address of a pointer if this information is needed, or NULL if it is not needed.
ppItemRoot
[out, retval] Receives the address of a pointer to the IWiaItem interface of the root item of the tree that represents the selected WIA device. If no devices are found, it contains the value NULL.

Return Values

This method returns the following values:

Return Value | Meaning
S_OK | A device was successfully selected.
S_FALSE | The user canceled the dialog box.
WIA_S_NO_DEVICE_AVAILABLE | There are no WIA hardware devices that match the specifications given in the lDeviceType parameter.

Remarks

This method creates and displays the Select Device dialog box so the user can select a WIA device for image acquisition. If a device is successfully selected, the IWiaDevMgr::SelectDeviceDlg method creates a hierarchical tree of IWiaItem objects for the device. It stores a pointer to the IWiaItem interface of the root item in the parameter ppItemRoot.

Particular types of devices may be displayed to the user by specifying the device types through the lDeviceType parameter. If only one device meets the specification, IWiaDevMgr::SelectDeviceDlg does not display the Select Device dialog box. Instead it creates the IWiaItem tree for the device and store a pointer to the IWiaItem interface of the root item in the parameter ppItemRoot. You can override this behavior and force IWiaDevMgr::SelectDeviceDlg to display the Select Device dialog box by passing WIA_SELECT_DEVICE_NODEFAULT as the value for the lFlags parameter.

If more than one WIA device matches the specification, all matching devices are displayed in the Select Device dialog box so the user may choose one.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppItemRoot parameter.

It is recommended that applications make device and image selection available through a menu item named From scanner or camera on the File menu.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaDevMgr::SelectDeviceDlgID

The IWiaDevMgr::SelectDeviceDlgID method displays a dialog box that enables the user to select a hardware device for image acquisition.

HRESULT SelectDeviceDlgID(
  HWND hwndParent,
  LONG lDeviceType,
  LONG lFlags,
  BSTR *pbstrDeviceID,
);

Parameters

hwndParent
[in] Handle of the window that owns the Select Device dialog box.
lDeviceType
[in] Specifies which type of WIA device to use. Can be set to StiDeviceTypeDefault, StiDeviceTypeScanner, or StiDeviceTypeDigitalCamera.
lFlags
[in] Specifies dialog box behavior. Can be set to any of the following values:
Constant | Meaning
0 | Use the default behavior.
WIA_SELECT_DEVICE_NODEFAULT | Display the dialog box even if there is only one matching device. For more information, see the Remarks section of this reference page.

pbstrDeviceID
[out, retval] Pointer to a string that receives the identifier string of the device.

Return Values

This method returns the following values:

Return Value | Meaning
S_OK | A device was successfully selected.
S_FALSE | The user canceled the dialog box.
WIA_S_NO_DEVICE_AVAILABLE | There are no WIA hardware devices attached to the user's computer that match the specifications.

Remarks

This method works in a similar manner to IWiaDevMgr::SelectDeviceDlg. The primary difference is that if it finds a matching device, it does not create the hierarchical tree of IWiaItem objects for the device.

Like IWiaDevMgr::SelectDeviceDlg, the IWiaDevMgr::SelectDeviceDlgID method creates and displays the Select Device dialog box. This enables the user to select a WIA device for image acquisition. If a device is successfully selected, the IWiaDevMgr::SelectDeviceDlgID method passes its identifier string to the application through its pbstrDeviceID parameter.

Particular types of devices may be displayed to the user by specifying the device types through the lDeviceType parameter. If only one device meets the specification, IWiaDevMgr::SelectDeviceDlgID does not display the Select Device dialog box. Instead it passes the device's identifier string to the application without displaying the dialog box. You can override this behavior and force IWiaDevMgr::SelectDeviceDlgID to display the Select Device dialog box by passing WIA_SELECT_DEVICE_NODEFAULT as the value for the lFlags parameter.

If more than one WIA device matches the specification, all matching devices are displayed in the Select Device dialog box so the user may choose one.

It is recommended that applications make device and image selection available through a menu item named From scanner or camera on the File menu.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaEventCallback

The IWiaEventCallback interface is used by applications to receive notification of WIA hardware device events. An application registers itself to receive event notifications by passing a pointer to the IWiaEventCallback interface to the IWiaDevMgr::RegisterEventCallbackInterface method. This interface supports the following method:

Methods | Description
ImageEventCallback | Invoked by the WIA run-time system when a hardware device event occurs.

The IWiaEventCallback interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaEventCallback::ImageEventCallback

The IWiaEventCallback::ImageEventCallback method is invoked by the WIA run-time system when a hardware device event occurs.

HRESULT ImageEventCallback(
  const GUID *pEventGUID,
  BSTR bstrEventDescription,
  BSTR bstrDeviceID,
  BSTR bstrDeviceDescription,
  DWORD dwDeviceType,
  BSTR bstrFullItemName,
  ULONG *pulEventType,
  ULONG ulReserved
);

Parameters

pEventGUID
[in] Specifies the unique identifier of the event. For a complete list of device events, see WIA Event Identifiers.
bstrEventDescription
[in] Specifies the string description of the event.
bstrDeviceID
[in] Specifies the unique identifier of the WIA device.
bstrDeviceDescription
[in] Specifies the string description of the device.
dwDeviceType
[in] Specifies the type of the device. See WIA Device Type Specifiers for a list of possible values.
bstrFullItemName
[in] Specifies the full name of the WIA item that represents the device.
pulEventType
[in, out] Pointer to a ULONG that specifies whether an event is a notification event, an action event, or both. A value of 1 indicates a notification event, a value of 2 indicates an action event, and a value of 3 indicates that the event is of both notification and action type.
ulReserved
[in] Reserved for user information.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

To receive notification of WIA hardware device events, applications pass a pointer to the IWiaEventCallback interface to the IWiaDevMgr::RegisterEventCallbackInterface method. The WIA run-time system then uses that interface pointer to invoke the IWiaEventCallback::ImageEventCallback method whenever a WIA hardware device event occurs.

Note that there is no guarantee the callback will be invoked on the same thread that registered the IWiaEventCallback interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem

Each WIA hardware device is represented to an application as a hierarchical tree of IWiaItem objects. The IWiaItem interface provides applications with the ability to query devices to discover their capabilities. It also provides access to data transfer interfaces and item properties. In addition, the IWiaItem interface provides methods to enable applications to control the device.

Methods

The IWiaItem interface supports the following methods:

Methods | Description
AnalyzeItem | Causes the WIA hardware device to acquire and try to detect what data types are present.
CreateChildItem | Adds IWiaItem objects to a device's IWiaItem tree.
DeleteItem | Removes the current IWiaItem object from the device's object tree.
DeviceCommand | Issues a command to a WIA hardware device.
DeviceDlg | Displays a dialog box to the user to prepare for image acquisition.
EnumChildItems | Creates an enumerator object and passes back a pointer to its IEnumWiaItem interface.
EnumDeviceCapabilities | Creates an enumerator that is used to ascertain the commands and events a WIA device supports.
EnumRegisterEventInfo | Creates an enumerator used to obtain information about events for which an application is registered.
FindItemByName | Searches an item's tree of sub-items using the name as the search key.
GetItemType | Obtains an item's type information.
GetRootItem | Retrieves the root item of a tree of item objects used to represent a WIA hardware device.

Some of the methods of the IWiaItem interface are valid only on the root item of the device's tree. Other methods are valid on all items. The methods are grouped as follows:

Valid On Root Item Only | DeviceCommand
 | DeviceDlg
 | EnumDeviceCapabilities
 | EnumRegisterEventInfo
Valid On All Items | AnalyzeItem
 | CreateChildItem
 | DeleteItem
 | EnumChildItems
 | FindItemByName
 | GetItemType
 | GetRootItem

The IWiaItem interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::AnalyzeItem

The IWiaItem::AnalyzeItem method causes the WIA hardware device to acquire and try to detect what data types are present.

HRESULT AnalyzeItem(
  LONG lFlags
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

This method is used with scanners to detect what type of data is on a page. When an application calls this method, the WIA hardware device driver scans and analyzes the current page. For each data type it detects, it creates an IWiaItem object to represent the region on the page the data occupies.

Image processing and OCR software can use this capability to detect graphics and text on a page. This method adds the regions it creates into the WIA device's IWiaItem tree. The application can select the individual regions and use the standard data transfer methods to acquire data from them.

If necessary, applications can override the regions created by this method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::CreateChildItem

The IWiaItem::CreateChildItem method is used by applications to add IWiaItem objects to the IWiaItem tree of a device.

HRESULT CreateChildItem(
  LONG lFlags,
  IWiaItem **ppIWiaItem
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.
ppIWiaItem
[out] Receives the address of a pointer to the IWiaItem interface, that sets the IWiaItem::CreateChildItem method.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Some WIA hardware devices allow applications to create new items in the IWiaItem tree that represents the device. Applications must test the devices to see if they support this capability. Use the IEnumWIA_DEV_CAPS interface to enumerate the current device's capabilities.

If the device allows the creation of new items in the IWiaItem tree, invoking IWiaItem::CreateChildItem creates a new IWiaItem that is a child of the current node. It passes a pointer to the new node to the application through the ppIWiaItem parameter.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::DeleteItem

The IWiaItem::DeleteItem removes the current IWiaItem object from the object tree of the device.

HRESULT DeleteItem(
  LONG lFlags
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.

Return Values

This method returns S_OK regardless of how many items were deleted. If the method fails, it returns a standard COM error code.

Remarks

The WIA run-time system represents each WIA hardware device connected to the user's computer as a hierarchical tree of IWiaItem objects. A given WIA device may or may not allow applications to delete IWiaItem objects from its tree. Use the IEnumWIA_DEV_CAPS interface to query the device for item deletion capability.

If the device supports item deletion in its IWiaItem tree, invoke the IWiaItem::DeleteItem method to remove the IWiaItem object. Note that this method will only delete an object after all references to the object have been released.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::DeviceCommand

The IWiaItem::DeviceCommand issues a command to a WIA hardware device.

HRESULT DeviceCommand(
  LONG lFlags,
  const GUID *plCommand,
  IWiaItem **pIWiaItem
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.
plCommand
[in] Specifies a unique identifier that specifies the command to send to the WIA hardware device. For a list of valid device commands, see WIA Device Commands.
ppIWiaItem
[in, out] On output, this pointer points to the item created by the command, if any.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications use this method to send WIA commands to hardware devices. Note that this command is only used on the root item of the IWiaItem object tree of the hardware device.

When the application sends the WIA_CMD_TAKE_PICTURE command to the device, IWiaItem::DeviceCommand, the WIA run-time system creates the IWiaItem object to represent the image. The IWiaItem::DeviceCommand method stores the address of the interface in the ppIWiaItem parameter.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::DeviceDlg

The IWiaItem::DeviceDlg method is used by applications to display a dialog box to the user to prepare for image acquisition.

HRESULT DeviceDlg(
  HWND hwndParent,
  LONG lFlags,
  LONG lIntent,
  LONG *plItemCount,
  IWiaItem ***ppIWiaItem
);

Parameters

hwndParent
[in] Handle of the parent window of the dialog box.
lFlags
[in] Specifies a set of flags that control the dialog box's operation. Can be set to any of the following values:
Flag | Meaning
0 | Default behavior.
WIA_DEVICE_DIALOG_SINGLE_IMAGE | Restrict image selection to a single image in the device image acquisition dialog box.
WIA_DEVICE_DIALOG_USE_COMMON_UI | Use the system UI, if available, rather than the vendor-supplied UI. If the system UI is not available, the vendor UI is used. If neither UI is available, the function returns E_NOTIMPL.

lIntent
[in] Specifies what type of data the image is intended to represent. For a list of image intent values, see Image Intent Constants.
plItemCount
[out] Receives the number of items in the array indicated by the ppIWiaItem parameter.
ppIWiaItem
[out] Receives the address of an array of pointers to IWiaItem interfaces.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

This method displays a dialog box to the user that an application uses to gather all the information required for image acquisition. For instance, this dialog box enables the user to select images to download from a camera. When using a scanner, it is also used to specify image scan properties such as brightness and contrast.

After this method returns, the application can use the IWiaDataTransfer interface to acquire the image.

Applications must call the IWiaItem::Release method (inherited from IUnknown) for each element in the array of interface pointers they receive through the ppIWiaItem parameter. Applications must also free the array using CoTaskMemFree.

It is recommended that applications make device and image selection available through a menu item named From scanner or camera on the File menu.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::EnumChildItems

The IWiaItem::EnumChildItems method creates an enumerator object and passes back a pointer to its IEnumWiaItem interface for non-empty folders in a IWiaItem tree of a WIA device.

HRESULT EnumChildItems(
  IEnumWiaItem **ppIEnumWiaItem
);

Parameters

ppIEnumWiaItem
[out] Receives the address of a pointer to the IEnumWiaItem interface that IWiaItem::EnumChildItems creates.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

The WIA run-time system represents each WIA hardware device as a hierarchical tree of IWiaItem objects. The IWiaItem::EnumChildItems method enables applications to enumerate child items in the current item. However, it can only be applied to items that are folders.

If the folder is not empty, it contains a subtree of IWiaItem objects. The IWiaItem::EnumChildItems method enumerates all of the items contained in the folder. It stores a pointer to an enumerator in the ppIEnumWiaItem parameter. Applications use the enumerator pointer to perform the enumeration of an object's child items.

Applications must call the IEnumWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnumWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::EnumDeviceCapabilities

The IWiaItem::EnumDeviceCapabilities method creates an enumerator that is used to ascertain the commands and events a WIA device supports.

HRESULT EnumDeviceCapabilities(
  LONG lFlags,
  IEnumWIA_DEV_CAPS **ppIEnumWIA_DEV_CAPS
);

Parameters

lFlags
[in] Specifies a flag that selects the type of capabilities to enumerate. Can be set to one or more of the following values:
Flag | Meaning
WIA_DEVICE_COMMANDS | Enumerate device commands.
WIA_DEVICE_EVENTS | Enumerate device events.

ppIEnumWIA_DEV_CAPS
[out] Pointer to IEnumWIA_DEV_CAPS interface created by IWiaItem::EnumDeviceCapabilities.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Use this method to create an enumerator object to obtain the set of commands and events that a WIA device supports. You can use the lFlags parameter to specify which kinds of device capabilities to enumerate. The IWiaItem::EnumDeviceCapabilities method stores the address of the interface of the enumerator object' in the ppIEnumWIA_DEV_CAPS parameter.

Note that this method can only be called on the root item of IWiaItem objects of a device tree.

Applications must call the IEnumWIA_DEV_CAPS::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnumWIA_DEV_CAPS parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::EnumRegisterEventInfo

The IWiaItem::EnumRegisterEventInfo method creates an enumerator used to obtain information about events for which an application is registered.

HRESULT EnumRegisterEventInfo(
  LONG lFlags,
  CONST GUID *pEventGUID,
  IEnumWIA_DEV_CAPS **ppIEnum
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.
pEventGUID
[in] Pointer to an identifier that specifies the hardware event for which you want registration information.
ppIEnum
[out] Receives the address of a pointer to the IEnumWIA_DEV_CAPS interface.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

An application invokes this method to create an enumerator object for the event information. IWiaItem::EnumRegisterEventInfo stores the address of the IEnumWIA_DEV_CAPS interface of the enumerator object in the ppIEnum parameter. The program then uses the interface pointer to enumerate the properties of the event for which it is registered.

Applications must call the IEnumWIA_DEV_CAPS::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIEnum parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::FindItemByName

The IWiaItem::FindItemByName method searches an item's tree of sub-items using the name as the search key. Each IWiaItem object has a name as one of its standard properties.

HRESULT FindItemByName(
  LONG lFlags,
  BSTR bstrFullItemName,
  IWiaItem **ppIWiaItem
);

Parameters

lFlags
[in] Currently unused. Should be set to zero.
bstrFullItemName
[in] Specifies the name of the item for which to search.
ppIWiaItem
[out] Pointer to the IWiaItem interface.

Return Values

This method returns S_OK if it finds the item, or S_FALSE if it does not find the item. If the method fails, it returns a standard COM error code.

Remarks

This method searches the current item's tree of sub-items using the name as the search key. If IWiaItem::FindItemByName finds the item specified by bstrFullItemName, it stores the address of a pointer to the IWiaItem interface of the item in the ppIWiaItem parameter.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::GetItemType

The IWiaItem::GetItemType method is called by applications to obtain the type information of an item.

HRESULT GetItemType(
  LONG *pItemType
);

Parameters

pItemType
[out] Receives the address of a LONG variable that contains a combination of type flags.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Every IWiaItem object in the hierarchical tree of objects associated with a WIA hardware device has a specific data type. Item objects represent folders and files. Folders contain file objects. File objects contain data acquired by the device such as images and sounds. This method enables applications to identify the type of any item in a hierarchical tree of item objects in a device.

An item may have more than one type. For example, an item that represents an audio file will have the type attributes WiaItemTypeAudio | WiaItemTypeFile.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItem::GetRootItem

The IWiaItem::GetRootItem method retrieves the root item of a tree of item objects used to represent a WIA hardware device.

HRESULT GetRootItem(
  IWiaItem **ppIWiaItem
);

Parameters

ppIWiaItem
[out] Receives the address of a pointer to the IWiaItem interface that contains a pointer to the IWiaItem interface of the root item.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Given any IWiaItem object in the object tree of a WIA hardware device, the application retrieves a pointer to the root item by calling this function.

Applications must call the IWiaItem::Release method (inherited from IUnknown) on the interface pointers they receive through the ppIWiaItem parameter.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.


IWiaItemExtras

The IWiaItemExtras interface provides several methods that enable applications to communicate with hardware drivers.

Methods

The IWiaItemExtras interface supports the following methods:

Methods | Description
CancelPendingIO | Allows applications to asynchronously cancel any pending input/output on the driver.
Escape | Sends a request for a vendor-specific I/O operation to a still image device.
GetExtendedErrorInfo | After a device error occurs, call this method to retrieve a string from the device driver that describes the cause of the error.

The IWiaItem interface, like all COM interfaces, inherits the IUnknown interface methods.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IWiaItem


IWiaItemExtras::CancelPendingIO

The IWiaItemExtras::CancelPendingIO method cancels all pending input/output operations on the driver.

HRESULT CancelPendingIO(void);

Parameters

None.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Drivers are not required to support this method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IWiaItemExtras


IWiaItemExtras::Escape

The IWiaItemExtras::Escape method sends a request for a vendor-specific I/O operation to a still image device.

HRESULT Escape(
  DWORD dwEscapeCode,
  BYTE *lpInData,
  DWORD cbInDataSize,
  BYTE *pOutData,
  DWORD dwOutDataSize,
  DWORD *pdwActualDataSize
);

Parameters

dwEscapeCode
[in] Caller-supplied, vendor-defined, DWORD-sized value that represents an I/O operation.
lpInData
[in] Pointer to a caller-supplied buffer that contains data to be sent to the device.
cbInDataSize
[in] Caller-supplied length, in bytes, of the data contained in the buffer pointed to by lpInData.
pOutData
[out] Pointer to a caller-supplied memory buffer to receive data from the device.
dwOutDataSize
[in] Caller-supplied length, in bytes, of the buffer pointed to by pOutData.
pdwActualDataSize
[out] Receives the number of bytes actually written to pOutData.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IWiaItemExtras


IWiaItemExtras::GetExtendedErrorInfo

The GetExtendedErrorInfo gets a string from the device driver that contains information about the most recent error. Call this method after an error during an operation on a WIA item (such as data transfer).

HRESULT GetExtendedErrorInfo(
  BSTR *bstrErrorText
);

Parameters

bstrErrorText
[in] Pointer to a string that contains the error information.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IWiaItemExtras


IWiaPropertyStorage

The IWiaPropertyStorage interface is used to access information about the IWiaItem object's properties. Applications must query an item to obtain its IWiaPropertyStorage interface.

Methods

The IWiaPropertyStorage interface inherits the following methods from the IPropertyStorage interface. They are implemented as described in the Structured Storage Reference in the Platform SDK.

IPropertyStorage Methods | Description
ReadMultiple | Reads property values in a property set.
WriteMultiple | Writes property values in a property set.
DeleteMultiple | Deletes properties in a property set.
ReadPropertyNames | Gets string names that correspond to given property identifiers.
WritePropertyNames | Creates or changes string names that corresponds to given property identifiers.
DeletePropertyNames | Deletes string names for given property identifiers.
SetClass | Assigns a CLSID to the property set.
Commit | As in IStorage::Commit, flushes or commits changes to the property storage object.
Revert | When the property storage is opened in transacted mode, discards all changes since the last commit.
Enum | Creates and gets a pointer to an enumerator for properties within this set.
Stat | Receives statistics about this property set.
SetTimes | Sets modification, creation, and access times for the property set.

IWiaPropertyStorage extends the IPropertyStorage interface by adding the following methods:

Methods | Description
GetCount | Returns the number of properties stored in the property storage.
GetPropertyAttributes | Retrieves access rights and legal value information for a specified set of properties.
GetPropertyStream | Retrieves an item's property stream.
SetPropertyStream | Sets the property stream of an item in a tree of IWiaItem objects of the WIA hardware device.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IPropertyStorage


IWiaPropertyStorage::GetCount

The IWIAPropertyStorage::GetCount method returns the number of properties stored in the property storage.

HRESULT GetCount(
  ULONG *pulNumProps
);

Parameters

pulNumProps
[out] Receives the number of properties stored in the property storage.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IPropertyStorage


IWiaPropertyStorage::GetPropertyAttributes

The IWiaItem::GetPropertyAttributes method retrieves access rights and legal value information for a specified set of properties.

HRESULT GetPropertyAttributes(
  ULONG cpspec,
  PROPSPEC rgpspec[ ],
  ULONG rgflags[ ],
  PROPVARIANT rgpropvar[ ]
);

Parameters

cpspec
[in] Specifies the number of property attributes to query.
rgpspec
[in] Specifies an array of device information property constants. Each constant in the array selects a property to query.
rgflags
[out] An array that receives a property attribute descriptor for each property specified in the rgpspec array. Each element in the array is one or more descriptor values combined with a bitwise OR operation.
rgpropvar
[out] An array that receives a property attribute descriptor for each property specified in the pPROPSPEC array. For more information, see PROPVARIANT.

Return Values

This method returns one of the following values or a standard COM error code:

Return Value | Meaning
S_OK | This method succeeded.
S_FALSE | The specified property names do not exist. No attributes were retrieved.
STG_E_ACCESSDENIED | The application does not have access to the property stream or the stream may already be open.
STG_E_INSUFFICIENTMEMORY | There is not enough memory to complete the operation.
ERROR_NOT_SUPPORTED | The property type is not supported.
STG_E_INVALIDPARAMETER | One or more parameters are invalid. One or more of the PROPSPEC structures contain invalid data.
STG_E_INVALIDPOINTER | One or more of the pointers passed to this method are invalid.
ERROR_NO_UNICODE_TRANSLATION | A translation from Unicode to ANSI or ANSI to Unicode failed.

Remarks

This method retrieves both property access rights and valid property values. Access rights report whether the property is readable, writable, or both. Valid property values are specified as a range of values, a list of values, or a group of flag values. For more information, see Property Attributes.

If the property access rights flag has the WIA_PROP_NONE bit set, no legal value information is available for this property. Read only properties and properties with a binary data type are examples of properties that would have the WIA_PROP_NONE bit set.

If the property has a range of valid values, they can be determined through the rgpropvar parameter upon completion of this method. The ppvValidValues parameter specifies an array of PROPVARIANT structures.

For example, if the property range is specified as VT_VECTOR | VT_UI4, range information can be retrieved through the structure member

rgpropvar[n].caul.pElems[range_specifier]

where n is the index number of the property that is inspected and range_specifier is one of the following:

Range Specifier | Meaning
WIA_RANGE_MAX | Maximum value to which the property may be set.
WIA_RANGE_MIN | Minimum value to which the property may be set.
WIA_RANGE_NOM | Normal or default property value.
WIA_RANGE_STEP | Increment or decrement between property values.

If the property has a list of valid values, applications determine them through the ppvValidValues parameter upon completion of this method.

For example, if the property range is specified as VT_VECTOR | VT_UI4, the list of valid property values can be retrieved through the structure member

rgpropspecValues[n].caul.pElems[list_specifier]

where n is the index number of the property that is inspected and list_specifier is one of the following:

Range Specifier | Meaning
WIA_LIST_COUNT | Total number of list elements excluding the nominal value.
WIA_LIST_NOM | Nominal value for the property.
WIA_LIST_VALUES | The index number of the first value.

Programs also use the ppvValidValues parameter to retrieve valid flag values. For instance, if the property flags are specified as VT_UI4, valid flag values can be determined through the structure member

rgpropspec[n].caul.pElems[flag_specifier]

where n is the index number of the property that is inspected, and flag_specifier is one of the following:

Range Specifier | Meaning
WIA_FLAG_NOM | The nominal value for the property.
WIA_FLAG_NUM_ELEMS | Total number of list elements excluding the nominal value.
WIA_FLAG_VALUES | All values with all valid flag bits set.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IPropertyStorage


IWiaPropertyStorage::GetPropertyStream

The IWiaPropertyStorage::GetPropertyStream method retrieves the property stream of an item.

HRESULT GetPropertyStream(
  GUID *pCompatibilityID,
  IStream **ppIStream
);

Parameters

pCompatibilityID
[out] Receives a unique identifier for a set of property values.
ppIStream
[out] Pointer to a stream that receives the item properties. For more information, see IStream.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications use this method to get a snapshot of the current properties of an item. These are subsequently restored by calling IWiaPropertyStorage::SetPropertyStream.

Applications can use the pCompatibilityID parameter to check if a device supports a specific set of property values before attempting to write these values to the device.

When it is finished using the item's property stream, the application must release it.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IPropertyStorage


IWiaPropertyStorage::SetPropertyStream

The IWiaPropertyStorage::SetPropertyStream sets the property stream of an item in the tree of IWiaItem objects of a WIA hardware device.

HRESULT SetPropertyStream(
  GUID *pCompatibilityID,
  IStream *pIStream
);

Parameters

pCompatibilityID
[in] Specifies a unique identifier for a set of property values.
pIStream
[in, unique] Pointer to the property stream that is used to set the current item's property stream.

Return Values

If the method succeeds, the method returns S_OK. If the method fails, it returns a standard COM error code.

Remarks

Applications use the pCompatibilityID parameter to check whether a device supports a specific set of property values before attempting to write these values to the device.

Set pIStream to NULL to check whether the device driver accepts the CompatibilityID specified by pCompatibilityID.

If the application obtained the property stream of the item using the IWiaPropertyStorage::GetPropertyStream method, the application must release it. For more information, see IStream.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.
Library: Use wiaguid.lib.

See Also

IPropertyStorage


Structures

This section presents information about the following structures used by WIA:

  • WIA_DATA_CALLBACK_HEADER
  • WIA_DATA_TRANSFER_INFO
  • WIA_DEV_CAP
  • WIA_DITHER_PATTERN_DATA
  • WIA_FORMAT_INFO


WIA_DATA_CALLBACK_HEADER

The WIA_DATA_CALLBACK_HEADER is transmitted to an application during a series of calls by the WIA run-time system to the IWiaDataCallback::BandedDataCallback method.

typedef struct _WIA_DATA_CALLBACK_HEADER
{
  LONG lSize;
  GUID guidFormatID;
  LONG lBufferSize;
  LONG lPageCount;
} WIA_DATA_CALLBACK_HEADER,*PWIA_DATA_CALLBACK_HEADER;

Members

lSize
Must contain the size of this structure in bytes. Should be initialized to sizeof(WIA_DATA_CALLBACK_HEADER).
guidFormatID
Indicates the image clipboard format. For a list of clipboard formats, see SetClipboardData. This parameter is queried during a callback to the IWiaDataCallback::BandedDataCallback method with the lMessage parameter set to IT_MSG_DATA_HEADER.
lBufferSize

Specifies the size in bytes of the buffer needed for a complete data transfer. This value can be zero, which indicates that the total image size is unknown. (when using compressed data formats, for example). In this case, the application should dynamically increase the size of its buffer. For more information, see Common WIA Item Property Constants in WIA_IPA_ITEM_SIZE.

lPageCount
Specifies the page count. Indicates the number of callbacks to the IWiaDataCallback::BandedDataCallback method with the lMessage parameter set to IT_MSG_NEW_PAGE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.


WIA_DATA_TRANSFER_INFO

The WIA_DATA_TRANSFER_INFO structure is used by applications to describe the buffer used to retrieve bands of data from WIA devices. It is primarily used in conjunction with the methods of the IWiaDataTransfer interface.

typedef struct _WIA_DATA_TRANSFER_INFO
{
  ULONG ulSize;
  ULONG ulSection;
  ULONG ulBufferSize;
  BOOL bDoubleBuffer;
  ULONG ulReserved1;
  ULONG ulReserved2;
  ULONG ulReserved3;
} WIA_DATA_TRANSFER_INFO, *PWIA_DATA_TRANSFER_INFO;

Members

ulSize
Contains the size of this structure. Must be set to sizeof(WIA_DATA_TRANSFER_INFO) before your application passes this structure to any WIA interface methods.
ulSection
Specifies an optional handle to a shared section of memory allocated by the application. If this member is set to NULL, IWiaDataTransfer::idtGetBandedData allocates the shared memory itself.
ulBufferSize
The size in bytes of the buffer that is used for the data transfer.
bDoubleBuffer
Contains TRUE if the device is double buffered, FALSE if the device is not double buffered.
ulReserved1
Reserved for use by the WIA system DLLs. Must be set to zero.
ulReserved2
Reserved for use by the WIA system DLLs. Must be set to zero.
ulReserved3
Reserved for use by the WIA system DLLs. Must be set to zero.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.


WIA_DEV_CAP

Applications use the WIA_DEV_CAP structure to enumerate device capabilities. A device capability is defined by an event or command that the device supports. For more information, see IEnumWIA_DEV_CAPS.

typedef struct _WIA_DEV_CAP
{
  GUID guid;
  ULONG ulFlags;
  BSTR bstrName;
  BSTR bstrDescription;
  BSTR bstrIcon;
  BSTR bstrCommandline
} WIA_DEV_CAP,*PWIA_DEV_CAP, WIA_EVENT_HANDLER, *PWIA_EVENT_HANDLER;

Members

guid
Specifies a GUID that identifies the device capability. This member can be set to any of the values specified in WIA Device Commands or WIA Event Identifiers.
ulFlags
Used when enumerating event handlers. The only valid value is WIA_IS_DEFAULT_HANDLER, that indicates that the currently registered handler should be used.
bstrName
Specifies a string that contains a short version of the capability name.
bstrDescription
Specifies a string that contains a description of the capability that is displayed to the user.
bstrIcon
Specifies a string that represents the location and resource ID of the icon that represents this capability or handler. The string must be of the following form: drive:\path\module,n, where n is the icon's negated resource ID (that is, if the resource ID of the icon is 100, then n is -100).
bstrCommandline
Specifies a string that represents command line arguments.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.


WIA_DITHER_PATTERN_DATA

The WIA_DITHER_PATTERN_DATA structure specifies a dither pattern for scanners. It is used in conjunction with the scanner device property constant WIA_DPS_DITHER_PATTERN_DATA.

typedef struct _WIA_DITHER_PATTERN_DATA
{
  LONG lSize;
  BSTR bstrPatternName;
  LONG lPatternWidth;
  LONG lPatternLength;
  LONG cbPattern;
  BYTE *pbPattern;
} WIA_DITHER_PATTERN_DATA, *PWIA_DITHER_PATTERN_DATA;

Members

lSize
Specifies the size of this structure in bytes. Should be set to sizeof(WIA_DITHER_PATTERN_DATA).
bstrPatternName
Specifies a string that contains the name of this dither pattern.
lPatternWidth
Indicates the width of the dither pattern in bytes.
lPatternLength
Indicates the length of the dither pattern in bytes.
cbPattern
Specifies the total number of bytes in the array pointed to by the pbPattern member.
pbPattern
Specifies a pointer to a buffer that contains the dither pattern.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.


WIA_FORMAT_INFO

The WIA_FORMAT_INFO structure specifies valid format and media type pairs for a device.

typdef struct _WIA_FORMAT_INFO
{
  GUID guidFormatID;
  LONG lTymed;
} WIA_FORMAT_INFO, *PWIA_FORMAT_INFO;

Members

guidFormatID
GUID that identifies the format.
lTymed
The media type that corresponds to the guidFormatID member.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in wia.h.


Constants

The following topics cover WIA constants:

  • WIA Device Commands
  • WIA Property Constants
  • Property Attributes
  • Image Intent Constants
  • WIA Event Identifiers
  • WIA Device Type Specifiers
  • WIA Item Type Flags
  • Error Codes


WIA Device Commands

The following constants form the set of valid WIA hardware device commands:

WIA_CMD_SYNCHRONIZE
Causes the device's minidriver to synchronize cached items with the hardware device. If the device supports the IWiaItem::AnalyzeItem method, issuing this command causes the minidriver to discard the analysis results and reset the item to its initial state.
WIA_CMD_TAKE_PICTURE
Causes a WIA device to acquire an image.
WIA_CMD_DELETE_ALL_ITEMS
Tells the device to delete all items that can be deleted from the tree of IWiaItem objects that represent the device. Item deletion is prevented by setting the item's properties. For details, see IWiaPropertyStorage::SetPropertyStream and Property Attributes.
WIA_CMD_CHANGE_DOCUMENT
Used for document scanners. Causes the scanner to load the next page in its document handler.
WIA_CMD_UNLOAD_DOCUMENT
Used for document scanners. Tells the device to unload all remaining pages in its document handler.


WIA Property Constants

WIA property constants are divided into the following groups:

  • Device Information Property Constants
  • Common Device Property Constants
  • Camera Device Property Constants
  • Scanner Device Property Constants
  • Common WIA Item Property Constants
  • Camera WIA Item Property Constants
  • Scanner WIA Item Property Constants


Device Information Property Constants

Device Information Properties are properties that describe the setup and installation of the device. These properties are available through the WiaDevMgr interface and also through the root item. Device information properties are prefixed with WIA_DIP (DeviceInformationProperty), and are supplied by WIA.

Property | Requirement | Type | Access
WIA_DIP_DEV_ID | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_VEND_DESC | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_DEV_DESC | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_DEV_TYPE | WIA-supplied | VT_I4 | Read Only
WIA_DIP_PORT_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_DEV_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_UI_CLSID | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_SERVER_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_DIP_REMOTE_DEV_ID | WIA-supplied | VT_BSTR | Read Only

WIA_DIP_DEV_ID

A device ID that is unique per physical device. This ID is composed of the Still Image class name followed by the device index. This ID is generated by the operating system.

WIA_DIP_VEND_DESC

The device manufactures name.

WIA_DIP_DEV_DESC

A description of the device.

WIA_DIP_DEV_TYPE

A device type constant: scanner or camera. Currently, device types are defined as follows.

Type | Definition
stiDeviceTypeDefault | When enumerating devices, any device that matches.
stiDeviceTypeScanner | Device that is represented as a scanner (see the WIA_DPS_DOCUMENT_HANDLING_CAPABILITIES to determine if the scanner is flatbed or sheetfed).
stiDeviceTypeDigitalCamera | Device that is represented as a camera.
stiDeviceTypeStreamingVideo | Device that is represented as streaming video.

WIA_DIP_PORT_NAME

Name of the port through which the device is connected.

WIA_DIP_DEV_NAME

A user-readable device name.

WIA_DIP_UI_CLSID

The class ID of the UI component.

WIA_DIP_SERVER_NAME

The name of the server where the WIA server for this device is running.


Common Device Property Constants

In addition to device information properties, WIA devices have property values stored in the registry that applications read and write. They are associated with the IWiaItem object. Device properties represent device information such as connection status, and device time. Each device property has an associated device property string.

The Device Property Constants and their associated strings listed here are common to most or all WIA hardware devices:

Property | Requirement | Type | Access
WIA_DPA_FIRMWARE_VERSION | Mandatory | VT_BSTR | Read Only
WIA_DPA_CONNECT_STATUS | Optional | VT_BSTR | Read Only
WIA_DPA_DEVICE_TIME | Optional | VT_UI2 | VT_VECTOR | Read/Write or Read Only (see text)
WIA_IPA_ITEM_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_IPA_FULL_ITEM_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_IPA_ITEM_FLAGS | WIA-supplied | VT_I4/WIA_PROP_FLAG | Read Only

WIA_DPA_FIRMWARE_VERSION

Firmware version number. The value for the firmware version number is up to the device. For example, "4.2.3".

WIA_DPA_CONNECT_STATUS

Device connect status. This is meant mainly for serial devices or other non-Plug and Play devices where the operating system cannot determine if the device is connected. There are only two defined values for this property, as follows.

Connect Status | Definition
WIA_DEVICE_NOT_CONNECTED | Device is not connected
WIA_DEVICE_CONNECTED | Device is connected and operational

WIA_DPA_DEVICE_TIME

Current device time. If the device clock can be set, this property is Read/Write, otherwise it is Read Only. WIA devices report time in the following format.

typedef struct _SYSTEMTIME {
  WORD wYear;
  WORD wMonth;
  WORD wDayOfWeek;
  WORD wDay;
  WORD wHour;
  WORD wMinute;
  WORD wSecond;
  WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME, *LPSYSTEMTIME;

This property is implemented for devices that are not plug and play capable and cannot determine their connection status during the lock operation. Most devices do not require this property.

WIA_IPA_ITEM_NAME

Name of the item. The value is "\ROOT" for the root item.

WIA_IPA_FULL_ITEM_NAME

The full name of the item. For the root item the value has the form "DeviceNumber\Root", where DeviceNumber is an identifier assigned by the operating system.

WIA_IPA_ITEM_FLAGS

Flags that specify the item type. For the root item (a device), only the WiaItemTypeDevice, WiaItemTypeRoot, and WiaItemTypeFolder flags are set. Non-folder items have WiaItemTypeFile flag set and may have the WiaItemTypeImage or WiaItemTypeAudio flags set as well.


Camera Device Property Constants

WIA hardware devices have property values that are stored in the Windows registry. For more information, see Common Device Property Constants. The following device property constants, with their associated strings, are specific to digital cameras:

Property | Requirement | Type | Access
WIA_DPC_PICTURES_TAKEN | Mandatory | VT_I4 | Read Only
WIA_DPC_PICTURES_REMAINING | Optional | VT_I4 | Read Only
WIA_DPC_EXPOSURE_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_EXPOSURE_COMP | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_EXPOSURE_TIME | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FNUMBER | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FLASH_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FOCUS_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_ZOOM_POSITION | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_PAN_POSITION | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_TILT_POSITION | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_TIMER_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_TIMER_VALUE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_POWER_MODE | Optional | VT_I4 | Read Only
WIA_DPC_BATTERY_STATUS | Optional | VT_I4 | Read Only
WIA_DPC_FOCUS_MANUAL_DIST | Optional | VT_I4 | Read Only
WIA_DPC_THUMB_WIDTH | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_THUMB_HEIGHT | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_PICT_WIDTH | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_PICT_HEIGHT | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_DIMENSION | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_COMPRESSION_SETTING | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FOCUS_METERING | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_TIMELAPSE_INTERVAL | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_TIMELAPSE_NUMBER | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_BURST_INTERVAL | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_BURST_NUMBER | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_EFFECT_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_DIGITAL_ZOOM | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_SHARPNESS | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_CONTRAST | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_CAPTURE_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_CAPTURE_DELAY | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_EXPOSURE_INDEX | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_EXPOSURE_METERING_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FOCUS_METERING_MODE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FOCUS_DISTANCE | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_FOCAL_LENGTH | Optional | VT_I4 | Read Only
WIA_DPC_RGBGAIN | Optional | VT_I4 | Read/Write or Read Only
WIA_DPC_WHITE_BALANCE | Optional | VT_I4 | Read/Write or Read Only

WIA_DPC_PICTURES_TAKEN

Number of pictures taken.

WIA_DPC_PICTURES_REMAINING

Number of pictures the device may still capture based on the current device capture settings.

WIA_DPC_EXPOSURE_MODE

Camera exposure mode.

Exposure Mode | Description
EXPOSURE_MODE_MANUAL | The shutter speed and aperture are set by the user.
EXPOSUREMODE_AUTO | The shutter speed and aperture are automatically set by the camera.
EXPOSUREMODE_APERTURE_PRIORITY | The aperture is set by the user, and the camera automatically sets the shutter speed.
EXPOSUREMODE_SHUTTER_PRIORITY | The shutter speed is set by the user, and the camera automatically sets the aperture.
EXPOSUREMODE_PROGRAM_CREATIVE | The shutter speed and aperture are automatically set by the camera, optimized for still subject matter.
EXPOSUREMODE_PROGRAM_ACTION | The shutter speed and aperture are automatically set by the camera, optimized for scenes containing fast motion.
EXPOSUREMODE_PORTRAIT | The shutter speed and aperture are automatically set by the camera, optimized for portrait photography.

WIA_DPC_EXPOSURE_COMP

Exposure compensation when using automatic exposure mode. Legal values are from –200 to 200 in increments of 50. These values represent the range –2.0 to +2.0.

WIA_DPC_EXPOSURE_TIME

Manual exposure time. Units are milliseconds. The camera may represent the range of manual exposure settings it supports through the property attributes. Manual exposure time is only used when the camera is in manual exposure mode.

WIA_DPC_FNUMBER

Manual F-number setting for use when the camera is in F-number exposure mode. Exposure mode is represented as camera F-number x 100. For example, Number 5.0 = 500.

WIA_DPC_FLASH_MODE

Camera flash mode. Flash modes include the following.

Flash Mode | Definition
WIA_FLASH_MODE_AUTO | Camera determines whether to flash.
WIA_FLASH_MODE_FILL | Camera flashes, regardless of light conditions.
WIA_FLASH_MODE_OFF | Camera will not flash.
WIA_FLASH_MODE_REDEYE_AUTO | Camera determines whether to flash, using red eye reduction.
WIA_FLASH_MODE_REDEYE_FILL | Camera flashes, regardless of light conditions, using red eye reduction.
WIA_FLASH_MODE_EXTERNALSYNC | Camera syncs external flash units.

WIA_DPC_FOCUS_MODE

Specifies the focus mode of the digital camera.

Focus Mode | Description
FOCUSMODE_MANUAL | The focus is set by the user.
FOCUSMODE_AUTO | The focus is automatically set by the camera.
FOCUSMODE_MACROAUTO | The focus is automatically set by the camera to a macro (short-range) setting.

WIA_DPC_ZOOM_POSITION

Reserved, do not use.

WIA_DPC_PAN_POSITION

Specifies the pan position for aiming the camera.

WIA_DPC_TILT_POSITION

Specifies the tilt position for aiming the camera.

WIA_DPC_TIMER_MODE

Automatic picture timer mode.

Timer Mode | Description
WIA_TIMER_MODE_OFF | Do not use timer when taking a picture through automatic control.
WIA_TIMER_MODE_ON | User timer when taking a picture through automatic control.

WIA_DPC_TIMER_VALUE

Automatic picture timer time setting in milliseconds. This value is only used when taking a picture through computer control and when the timer mode is on.

WIA_DPC_POWER_MODE

This property is used to determine whether the device is operating on battery or line power.

Power Mode | Description
WIA_POWER_MODE_LINE | AC or other power adapter.
WIA_POWER_MODE_BATTERY | Running off batteries.

WIA_DPC_BATTERY_STATUS

Camera Battery life remaining, represented as a value from 100 (full charge) to 0.

WIA_DPC_FOCUS_MANUAL_DIST

Reserved, do not use.

WIA_DPC_THUMB_WIDTH

The width, in pixels, of thumbnails created for captured images. The list of valid values for this property have a one-to-one correspondence to the list of valid values for the WIA_DPC_THUMB_HEIGHT property.

WIA_DPC_THUMB_HEIGHT

The height, in pixels, of thumbnails created for captured images. The list of valid values for this property have a one-to-one correspondence to the list of valid values for the WIA_DPC_THUMB_WIDTH property.

WIA_DPC_PICT_WIDTH

The width to use for newly captured images. the list of valid values for this property has a one-to-one correspondence to the list of valid values for the WIA_DPC_PICT_HEIGHT property.

WIA_DPC_PICT_HEIGHT

The height to usefor newly captured images. The list of valid values for this property has a one-to-one correspondence to the list of valid values for the WIA_DPC_PICT_WIDTH property.

WIA_DPC_DIMENSION

Reserved, do not use.

WIA_DPC_COMPRESSION_SETTING

A numeric value that specifies relative image quality. This property is device-specific.

WIA_DPC_FOCUS_METERING

Reserved, do not use.

WIA_DPC_TIMELAPSE_INTERVAL

The time, in milliseconds, between image captures in a time-lapse capture operation.

WIA_DPC_TIMELAPSE_NUMBER

The number of images the device attempts to capture during a time-lapse capture.

WIA_DPC_BURST_INTERVAL

The time, in milliseconds, between image captures during a burst operation.

WIA_DPC_BURST_NUMBER

The number of images the device attempts to capture during a burst operation.

WIA_DPC_EFFECT_MODE

Specifies the special image acquisition mode of the camera.

Effect Mode | Description
EFFECTMODE_STANDARD | The standard mode for the camera.
EFECTMODE_BW | Capture a grayscale image.
EFFECTMODE_SEPIA | Capture a sepia image.

WIA_DPC_DIGITAL_ZOOM

The effective zoom ration of the digital camera's acquired image scaled by a factor of 10. No digital zoom (1X) corresponds to a value of 10, which is the standard scene size captured by the camera. A value of 20 corresponds to a 2X zoom where 1/4 of the standard scene size is captured by the camera.

WIA_DPC_SHARPNESS

The perceived sharpness of captured images. This property can use either an enumeration or a range.

WIA_DPC_CONTRAST

The perceived contrast of captured images. This property can use either an enumeration or a range.

WIA_DPC_CAPTURE_MODE

Sets the image-capturing mode.

Capture Mode | Description
CAPTUREMODE_NORMAL | Normal mode for the camera.
CAPTUREMODE_BURST | Capture more than one image in quick succession as defined by the values of WIA_DPC_BURST_NUMBER and WIA_DPC_BURST_INTERVAL.
CAPTURMODE_TIMELAPSE | Capture more than one image in succession as defined by WIA_DPC_TIMELAPSE_NUMBER and WIA_DPC_TIMELAPSE_INTERVAL.

WIA_DPC_CAPTURE_DELAY

The time, in milliseconds, between the firing of the capture trigger and the actual initiation of the data capture. For no pre-capture delay, set this property to zero.

This property is not intended to be used to describe the time between frames for single-initiation multiple captures such as burst or time-lapse.

WIA_DPC_EXPOSURE_INDEX

Specifies the film speed for digital cameras that can emulate ISO (ASA/DIN) speed settings. Typically, a device supports discrete enumerated values, but continuous control over a range is possible.

A value of 0xFFFF corresponds to Automatic ISO setting.

WIA_DPC_EXPOSURE_METERING_MODE

Specifies the mode the camera uses to automatically adjust the exposure setting.

Exposure Metering Mode | Description
EXPOSUREMETERING_AVERAGE | Set the exposure based on an average of the entire scene.
EXPOSUREMETERING_CENTERWEIGHT | Set the exposure based on a center-weighted average.
EXPOSUREMETERING_MULTISPOT | Set the exposure based on a multi-spot pattern.
EXPOSUREMETERING_CENTERSPOT | Set the exposure based on a center spot.

WIA_DPC_FOCUS_METERING_MODE

Specifies the mode the camera uses to automatically adjust the focus.

Focus Metering Mode | Description
FOCUSMETERING_CENTERSPOT | Adjust the focus based on a center spot.
FOCUSMETERING_MULTISPOT | Adjust the focus based on a multi-spot pattern.

WIA_DPC_FOCUS_DISTANCE

The distance, in millimeters, between the image-capturing plane of the digital camera and the point of focus.

A value of 0xFFFF corresponds to a setting greater than 655 meters.

WIA_DPC_FOCAL_LENGTH

The 35mm equivalent focal length, in 100ths of a millimeter.

WIA_DPC_RGBGAIN

A null-terminated Unicode string that represents the red, green, and blue gain applied to image data, respectively. For example, "4:25:50" (null-terminated) represents a red gain of 4, a green gain of 25, and a blue gain of 50.

WIA_DPC_WHITE_BALANCE

Specifies how the digital camera weights color channels.

White Balance | Description
WHITEBALANCE_MANUAL | White balance is set directly with the WIA_DPC_RGBGAIN property.
WHITEBALANCE_AUTO | The camera uses an automatic mechanism to set the white balance.
WHITEBALANCE_ONEPUSH_AUTO | The camera determines the white balance setting when a user presses the capture button while pointing the camera at a white surface.
WHITEBALANCE_DAYLIGHT | The camera sets the white balance to a value appropriate for use in daylight conditions.
WHITEBALANCE_FLORESCENT | The camera sets the white balance to a value appropriate for use with a flourescent light source.
WHITEBALANCE_TUNGSTEN | The camera sets the white balance to a value appropriate for use with a tungsten light source.
WHITEBALANCE_FLASH | The camera sets the white balance to a value appropriate for use with an electonic flash.


Scanner Device Property Constants

WIA hardware devices have property values that are stored in the Windows registry. For more information, see Common Device Property Constants. The following device property constants, with their associated strings, are specific to digital image scanners:

Property Name | Requirement | Type | Access
WIA_DPS_HORIZONTAL_BED_SIZE | See text | VT_I4 | Read Only
WIA_DPS_VERTICAL_BED_SIZE | See text | VT_I4 | Read Only
WIA_DPS_HORIZONTAL_SHEET_FEED_SIZE | See text | VT_I4 | Read Only
WIA_DPS_VERTICAL_SHEET_FEED_SIZE | See text | VT_I4 | Read Only
WIA_DPS_SHEET_FEEDER_REGISTRATION | See text | VT_I4 | Read Only
WIA_DPS_HORIZONTAL_BED_REGISTRATION | See text | VT_I4 | Read Only
WIA_DPS_VERTICAL_BED_REGISTRATION | Optional | VT_I4 | Read Only
WIA_DPS_PLATEN_COLOR | Optional | RGBQUAD | Read Only
WIA_DPS_PAD_COLOR | See text | RGBQUAD | R/W
WIA_DPS_DOCUMENT_HANDLING_CAPABILITIES | See text | VT_I4/WIA_PROP_FLAG | Read Only
WIA_DPS_DOCUMENT_HANDLING_STATUS | See text | VT_I4/WIA_PROP_FLAG | Read Only
WIA_DPS_DOCUMENT_HANDLING_SELECT | See text | VT_I4/WIA_PROP_FLAG | R/W
WIA_DPS_DOCUMENT_HANDLING_CAPACITY | See text | VT_I4 | Read Only
WIA_DPS_OPTICAL_XRES | Mandatory | VT_I4 | Read Only
WIA_DPS_OPTICAL_YRES | Optional | VT_I4 | Read Only
WIA_DPS_ENDORSER_CHARACTERS | Optional | VT_BSTR | Read Only
WIA_DPS_ENDORSER_STRING | Optional | VT_BSTR | R/W
WIA_DPS_SCAN_AHEAD_PAGES | Optional | VT_I4 | R/W
WIA_DPS_MAX_SCAN_TIME | Mandatory | VT_I4 | Read Only
WIA_DPS_PAGES | See Text | VT_I4 | R/W
WIA_DPS_PAGE_SIZE | Optional | VT_I4 | R/W
WIA_DPS_TRANSPARENCY | Optional | VT_I4/WIA_PROP_FLAG | Read Only
WIA_DPS_TRANSPARENCY_SELECT | Optional | VT_I4/WIA_PROP_FLAG | R/W
WIA_DPS_WARM_UP_TIME | Optional | VT_I4 | Read Only
WIA_DPS_PAGE_WIDTH | Optional | VT_I4 | R/W
WIA_DPS_PAGE_HEIGHT | Optional | VT_I4 | R/W
WIA_DPS_PREVIEW | See Text | VT_I4 | R/W
WIA_DPS_FILTER_SELECT | Optional | VT_I4 | R/W
WIA_DPS_DITHER_SELECT | Optional | VT_I4 | R/W
WIA_DPS_DITHER_PATTERN_DATA | Optional | VT_I4 | R/W

WIA_DPS_HORIZONTAL_BED_SIZE

Specifies the maximum width, in thousandths of an inch, that is scanned in the horizontal (X) axis from the platen of a flatbed scanner at the current resolution. This property also applies to automatic document feeders, that move sheets to the platen of a flatbed scanner for scanning. Scanners that have a platen will implement this property. Other scanner types will instead implement the WIA_DPS_HORIZONTAL_SHEET_FEED_SIZE property.

WIA_DPS_VERTICAL_BED_SIZE

Specifies the maximum height, in thousandths of an inch, that is scanned in the vertical (Y) axis from the platen of a flatbed scanner at the current resolution. This property also applies to automatic document feeders, that move sheets to the platen of a flatbed scanner for scanning. Scanners that have a platen will implement this property. Other scanner types will instead implement the WIA_DPS_VERTICAL_SHEET_FEED_SIZE property.

WIA_DPS_HORIZONTAL_SHEET_FEED_SIZE

Specifies the maximum width, in thousandths of an inch, that is scanned in the horizontal (X) axis from a handheld or sheet feed scanner at the current resolution. This property also applies to automatic document feeders that scan without moving sheets to the platen of a flatbed scanner. This property is mandatory for sheed-fed and hand-held scanners..

WIA_DPS_VERTICAL_SHEET_FEED_SIZE

Specifies the maximum height, in thousandths of an inch, that is scanned in the vertical (Y) axis from a handheld or sheet feed scanner at the current resolution. This property also applies to automatic document feeders that scan without moving sheets to the platen of a flatbed scanner. Scanners that have a paper path that does not use a platen will implement this property.

WIA_DPS_SHEET_FEEDER_REGISTRATION

Indicates how the sheet is positioned horizontally on the scanning head of a handheld or sheet feed scanner. It is used to predict where a document is placed across the scan head. It takes one of the following constants.

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.

On scanners that support more than one scan head, this property is relative to the top scan head. Sheet-fed and hand-held scanners must implement this property..

WIA_DPS_HORIZONTAL_BED_REGISTRATION

Indicates how the sheet is positioned horizontally on the platen of a flatbed scanner. It is used to predict where a document is placed across the platen. It takes one of the following constants.

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

On scanners that support more than one scan head, this property is relative to the top scan head. Scanners that have a platen implement this property.

WIA_DPS_VERTICAL_BED_REGISTRATION

Indicates how the sheet is positioned vertically on the platen of a flatbed scanner. It is used to predict where a document is placed on the platen. It takes one of the following constants.

Constant | Description
TOP_JUSTIFIED | The sheet is positioned to the top with respect to the platen.
CENTERED | The sheet is centered on the platen.
BOTTOM_JUSTIFIED | The sheet is positioned to the bottom with respect to the platen.

On scanners that support more than one scan head, this property is relative to the top scan head. Scanners that have a platen will implement this property.

WIA_DPS_PLATEN_COLOR

Specifies the color of the platen in back of the sheet to be scanned.

The format of the color information is RGBQUAD.

typedef struct tagRGBQUAD {
  WORD   Blue;
  WORD   Green;
  WORD   Red;
  WORD   wReserved;
} RGBQUAD;

WIA_DPS_PAD_COLOR

Color used to pad when there is not enough image data to fill a requested buffer. This property is implemented for scanners that pad the buffer.

The binary value represents the color value of a single pixel in the current mode. On scanners that allow the pad value to be programmed, this property is read/write; otherwise, the property is read only.

The format of the color information is RGBQUAD.

typedef struct tagRGBQUAD {
  WORD    rgbBlue;
  WORD    rgbGreen;
  WORD    rgbRed;
  WORD    rgbReserved;
} RGBQUAD;

WIA_DPS_DOCUMENT_HANDLING_CAPABILITIES

This property reports the document handling capabilities of a scanner. Scanners that have an automatic document feeder, sheet-fed scanners, and hand-held scanners must implement this property. If this property is not present, the application can assume that the scanner does not have an automatic document feeder. The document handling capability flags include the following:

Flags | Description
FEED | The scanner has an automatic document handler installed.
FLAT | The scanner has a flatbed platen.
DETECT_FLAT | The scanner can detect a document on the flatbed platen.
DETECT_SCAN | The scanner can detect a document in the feeder only by scanning.
DETECT_FEED | The scanner can detect a document in the feeder.
DETECT_DUP | The scanner can detect a duplex scan request from the user.
DETECT_FEED_AVAIL | The scanner can tell when the automatic document feeder is installed.
DETECT_DUP_AVAIL | The scanner can tell when the duplexer is installed.
DUP | The scanner has a duplexer.

WIA_DPS_DOCUMENT_HANDLING_STATUS

This property reports the real-time document handling status of a scanner. Scanners that have an automatic document feeder, sheet-fed scanners, and hand-held scanners must implement this property. The status flags include the following.

Flags | Description
FEED_READY | The document handler has a page ready to feed.
FLAT_READY | The scanner has a document on the flatbed platen.
DUP_READY | The scanner has detected a duplex request from the user.
FLAT_COVER_UP | The flat bed cover is up.
PATH_COVER_UP | The paper path cover is up.
PAPER_JAM | There is a document jam in the paper path.

WIA_DPS_DOCUMENT_HANDLING_SELECT

On scanners with an automatic document feeder, this property selects the document-handling mode. The mode flags include the following.

Flags | Description
FEEDER | Scan from the document feeder.
FLATBED | Scan from flatbed platen.
DUPLEX | Place feeder in duplex mode.
AUTO_ADVANCE | Enables automatic feeding of the next document after a scan.
FRONT_FIRST | Scan the front (top) of a document first when doing duplex scanning.
BACK_FIRST | Scan the back (bottom) of a document first when doing duplex scanning.
FRONT_ONLY | Scan only the front (top) of a document.
BACK_ONLY | Scan only the back (bottom) of a document.
PREFEED | Enable pre-feed mode. Pre-position next document while scanning.

Because this property is read/write, the driver implements two values for this property: a valid value and a current value. The bits in the valid value indicate values the driver and device support.

For example, if the scanner supports allowing the application to select feeder mode, the FEEDER bit in the valid value for this property is set. The application selects feeder mode by setting the FEEDER bit in the current value.

Scanners have a device item associated with each scan head in the scanner. These items, together with the "Document Handling Select" property, completely specify the source of a scan. The following examples are provided to clarify the use of the "Document Handling Select" property on different scanner hardware configurations:

  • For a flatbed or hand held scanner with no automatic document handling, this property would not be implemented.
  • If a duplex scanner does not support programmable (front/back) page order, either FRONT_FIRST or BACK_FIRST must still be available as a flag so that applications can detect the page order. An error should be generated if an application tries to change the order.
  • A non-duplex scanner with automatic document handling must support either the FRONT_ONLY or BACK_ONLY flag so that applications can detect the page orientation. An error should be generated if an application tries to change the page orientation.

WIA_DPS_DOCUMENT_HANDLING_CAPACITY

This property reports the maximum number of pages that the document handler input tray can accept.

WIA_DPS_OPTICAL_XRES

Horizontal Optical Resolution. Highest supported horizontal optical resolution in DPI. Most devices respond with 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.

WIA_DPS_OPTICAL_YRES

Vertical Optical Resolution. Highest supported vertical optical resolution in DPI. Most devices will respond with 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.

WIA_DPS_ENDORSER_CHARACTERS

Returns a string that contains all of the valid characters that are printed by the endorser.

WIA_DPS_ENDORSER_STRING

Specifies a string that is printed onto the document when it is scanned. The endorser string supports using tokens that are replaced with values by the system. The following tokens are supported.

Token | Description
$DATE$ | The date in the form YYYY/MM/DD.
$DAY$ | The day in the form DD.
$MONTH$ | The month of the year in the form MM.
$PAGE_COUNT$ | The number of pages transferred.
$TIME$ | The time of day in the form HH:MM:SS.
$YEAR$ | The year in the form YYYY.

WIA_DPS_SCAN_AHEAD_PAGES

Specifies the number of pages that are scanned ahead to local scanner or driver memory on scanners that support scan ahead. A value of zero disables scan ahead. The following negative value constant is supported.

Constant | Description
WIA_SCAN_AHEAD_ALL | Scan ahead as far as possible.

Doing normal data transfers on the buffered scan head item retrieves the buffered pages. Device and item properties may not be changed during a scan-ahead operation. Scanners that support only WIA_SCAN_AHEAD_ALL would report only this value as min, max, and nominal in the valid values for one property.

WIA_DPS_MAX_SCAN_TIME

This property reports the maximum time to scan a page with the current property settings in milliseconds. Applications use this value for detecting hung device error conditions.

WIA_DPS_PAGES

Specifies the number of pages to scan. The following zero value constant is supported. Applications that do not support multi-page scans should set this value to one, if it is present. Sheet-fed and hand-held scanners must support this property.

Constant | Description
ALL_PAGES | Scan all pages in the input tray, or until the buffer is full.

WPS_DPS_PAGE_SIZE

Provides a mechanism for the application to specify to the device and driver the paper size to scan. The driver should set the extents based on this value.

Constant | Description
WIA_PAGE_LETTER | Letter-sized paper.
WIA_PAGE_LEGAL | Legal-sized paper.
WIA_PAGE_A4 | A4-sized paper.

WIA_DPS_TRANSPARENCY

Indicates the capabilities and status of an alternate light source/path (transparency adapter) in the scanner for scanning transparencies or slides. The following flags are defined:

Flag | Description
LIGHT_SOURCE_PRESENT_DETECT | The scanner detects when the transparency adapter is present.
LIGHT_SOURCE_PRESENT | A transparency adapter is present.
LIGHT_SOURCE_DETECT_READY | The scanner detects when media is placed on the transparency scanning bed.
LIGHT_SOURCE_READY | The user selected the transparency adapter at the scanner.

WIA_DPS_TRANSPARENCY_SELECT

Used by the application to select the alternate light source/path or transparency adapter. The following flags are defined:

Flag | Description
LIGHT_SOURCE_SELECT | Turns on the transparency adapter.

WIA_DPS_WARM_UP_TIME

Indicates to the application how long, in milliseconds, it takes the scanner and/or lamp to warm up before scanning commences. The application can display a progress indicator to the user based on this value. If the device requires no warm-up, the value should be zero.

WIA_DPS_PAGE_WIDTH

Indicates the maximum width of the page to be scanned in thousandths of an inch.

WIA_DPS_PAGE_HEIGHT

Indicates the maximum height of the page to be scanned in thousandths of an inch.

WIA_DPS_PREVIEW

This property indicates whether or not the device supports preview scans. For example, sheet-fed and hand-held scanners cannot preview. The application should set this property when it does a preview scan so that the device can be optimized for previewing. This property is mandatory for sheet-fed and hand-held scanners.

WIA_DPS_FILTER_SELECT

Reserved for future use.

WIA_DPS_DITHER_SELECT

Reserved for future use.

WIA_DPS_DITHER_PATTERN_DATA

Reserved for future use.


Common WIA Item Property Constants

The following Device Property Constants must be supported by all IWiaItem and IWiaDrvItem interfaces:

Property Name | Requirement | Type | Access
WIA_IPA_ITEM_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_IPA_FULL_ITEM_NAME | WIA-supplied | VT_BSTR | Read Only
WIA_IPA_ITEM_TIME | Mandatory | VT_UI2/ VT_VECTOR | Read Only
WIA_IPA_ITEM_FLAGS | WIA-supplied | VT_I4/ WIA_PROP_FLAG | Read Only
WIA_IPA_ACCESS_RIGHTS | Mandatory | VT_I4/ WIA_PROP_FLAG | See text
WIA_IPA_DATATYPE | Mandatory | VT_I4 | See text
WIA_IPA_DEPTH | Mandatory | VT_I4 | See text
WIA_IPA_PREFERRED_FORMAT | Mandatory | CLSID | Read Only
WIA_IPA_FORMAT | Mandatory | CLSID | See text
WIA_IPA_COMPRESSION | Mandatory | VT_I4 | See text
WIA_IPA_TYMED | Mandatory | VT_I4 | R/W
WIA_IPA_CHANNELS_PER_PIXEL | Mandatory | VT_I4 | Read Only
WIA_IPA_BITS_PER_CHANNEL | Mandatory | VT_I4 | See text
WIA_IPA_PLANAR | Mandatory | VT_I4 | Read Only
WIA_IPA_PIXELS_PER_LINE | Mandatory | VT_I4 | Read Only
WIA_IPA_BYTES_PER_LINE | Mandatory | VT_I4 | Read Only
WIA_IPA_NUMBER_OF_LINES | Mandatory | VT_I4 | Read Only
WIA_IPA_GAMMA_CURVES | Optional | VT_I4 | R/W
WIA_IPA_ITEM_SIZE | Mandatory | VT_I4 | Read Only
WIA_IPA_MIN_BUFFER_SIZE | Mandatory | VT_I4 | Read Only
WIA_IPA_REGION_TYPE | Optional | VT_BSTR | Read Only
WIA_IPA_COLOR_PROFILE | WIA-supplied | VT_BSTR | R/W
WIA_IPA_APP_COLOR_MAPPING | Optional | VT_I4 | R/W
WIA_IPA_PROP_STREAM_COMPAT_ID | Optional | CLSID | R/W

WIA_IPA_ITEM_NAME

Name of the item object, for example, "\Image0001".

WIA_IPA_FULL_ITEM_NAME

Complete item name, that includes hierarchy. The full hierarchy includes the Plug and Play device index followed by the root item name, ROOT, followed by the item name. For example, a picture at the highest level in a camera could be named:

0001\Root\Image0001

WIA_IPA_ITEM_TIME

Time the image was captured. WIA devices report time in the following format.

typedef struct _SYSTEMTIME {
  WORD wYear;
  WORD wMonth;
  WORD wDayOfWeek;
  WORD wDay;
  WORD wHour;
  WORD wMinute;
  WORD wSecond;
  WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME, *LPSYSTEMTIME;

WIA_IPA_ITEM_FLAGS

Flags that specify the item type and accessibility.

Item Flag | Description
WiaItemTypeFree | Item is freed, or is uninitialized.
WiaItemTypeImage | Item contains image data.
WiaItemTypeFile | Item contains data.
WiaItemTypeFolder | Item may have children.
WiaItemTypeRoot | Item is the root.
WiaItemTypeAnalyze | Item was created by analysis.
WiaItemTypeAudio | Item contains audio data.
WiaItemTypeDevice | Item represents device and may not be deleted.
WiaItemTypeDeleted | Item has been deleted.
WiaItemTypeDisconnected | Device backing item is disconnected.
WiaItemTypeHasAttachments | Item has attatchments, such as audio annotation, as children.
WiaItemTypeHPanorama | For folders only. Images in this folder represent parts of a horizontal panorama.
WiaItemTypeVPanorama | For folders only. Images in this folder represent parts of a vertical panorama.
WiaItemType2DPanorama | For folders only. Images in this folder represent parts of a 2D panorama.
WiaItemTypeBurst | For folders only. Images in this folder were taken in a continuous time sequence.
WiaItemTypeStorage | For folders only. This folder represents a storage unit on the imaging device, such as a flash card.

Items that represent folders normally have the WiaItemTypeFolder flag set and the WiaItemTypeImage, WiaItemTypeFile, and WiaItemTypeAudio flags cleared. Non-folder items have WiaItemTypeFile flag set and may have the WiaItemTypeImage and WiaItemTypeAudio flags set as well.

WIA_IPA_ACCESS_RIGHTS

This flag controls access to the item as well as whether the item is deleted. This property is read only for scanners and read/write for cameras, depending on whether the camera supports changing the access rights

.

Access Right | Description
WIA_ITEM_READ | Item has read-only access.
WIA_ITEM_WRITE | Item has write-only access.
WIA_ITEM_CAN_BE_DELETED | Item has delete-only access.
WIA_ITEM_RD | Item has read and delete access.
WIA_ITEM_RWD | Item has read, write, and delete access.

WIA_IPA_DATATYPE

This property indicates the image type of the item. This property is read-only for cameras and read/write for scanners.

Data Type | Description
WIA_DATA_THRESHOLD | One bit-per-pixel black-and-white threshold. Data over the current value of WIA_IPS_THRESHOLD is converted to white; data under this value is converted to black.
WIA_DATA_DITHER | Scan data is dithered using the currently selected dither pattern.
WIA_DATA_GRAYSCALE | Scan data represents intensity. The palette is a fixed, equally-spaced gray scale with a depth specified by WIA_IPA_DEPTH property.
WIA_DATA_COLOR | Scan data is red, green, blue (RGB) color. The full color format is described using the following WIA properties: WIA_IPA_CHANNELS_PER_PIXEL WIA_IPA_BITS_PER_CHANNEL WIA_IPA_PLANAR WIA_IPA_PIXELS_PER_LINE WIA_IPA_BYTES_PER_LINE WIA_IPA_NUMBER_OF_LINES
WIA_DATA_COLOR_THRESHOLD | Same as WIA_DATA_COLOR except that the threshold value is used when scanning the data. Color values over the WIA_IPS_THRESHOLD value are converted to full brightness; colors under this value are converted to black.
WIA_DATA_COLOR_DITHER | Same as WIA_DATA_COLOR except that the data is dithered using the currently selected dither pattern.

WIA_IPA_DEPTH

Requested number of bits per pixel. On devices that allow for multiple color-space resolutions per data type, this property is a list of values (a WIA_PROP_LIST) specifying the color-space resolutions. On devices that allow only a single color-space resolution per data type, this is a read-only property that tracks the WIA_IPA_DATATYPE set above, otherwise it is read/write. This property is always read only for cameras.

WIA_IPA_PREFERRED_FORMAT

The preferred data format the driver or device supplies to the application.

Format Type | Description
IMGFMT_MEMORYBMP | Windows bitmap without a header file.
IMGFMT_BMP | Windows bitmap with header file.
IMGFMT_EMF | Extended Windows metafile.
IMGFMT_WMF | Windows metafile.
IMGFMT_JPEG | JPEG compressed format.
IMGFMT_PNG | W3C PNG format.
IMGFMT_GIF | GIF image format.
IMGFMT_TIFF | Tag Image File Format.
IMGFMT_EXIF | Exchangeable File Format.
IMGFMT_PHOTOCD | Eastman Kodak file format.
IMGFMT_FLASHPIX | FlashPix format.
IMGFMT_ICO | Microsoft icon file format.

WIA_IPA_FORMAT

This property controls the data format returned to the application.

This property is read/write for devices that support more than one format. Otherwise, it is read only.

Format Type | Description
IMGFMT_MEMORYBMP | Windows bitmap without a BITMAPFILEHEADER header.
IMGFMT_BMP | Windows bitmap with a BITMAPFILEHEADER header.
IMGFMT_EMF | Extended Windows metafile.
IMGFMT_WMF | Windows metafile.
IMGFMT_JPEG | JPEG compressed format.
IMGFMT_PNG | W3C PNG format.
IMGFMT_GIF | GIF image format.
IMGFMT_TIFF | Tag Image File Format.
IMGFMT_EXIF | Exchangeable File Format.
IMGFMT_PHOTOCD | Eastman Kodak file format.
IMGFMT_FLASHPIX | FlashPix format.
IMGFMT_ICO | Microsoft icon file format.

The valid values for this property match the values returned by drvGetWiaFormatInfo based on the setting of WIA_IPA_TYMED. When WIA_IPA_TYMED is set to TYMED_CALLBACK, the valid values for this property include at least IMGFMT_MEMORYBMP. When WIA_IPA_TYMED is set to TYMED_FILE, the valid values for this property include at least IMGFMT_BMP.

WIA_IPA_COMPRESSION

Specifies the compression within the given data format. Useful for data formats like TIFF and DIB that have optional compressed modes.

This property is read/write for devices that support more than one compression type. For all other devices, it is read only.

Compression Type | Description
WIA_COMPRESSION_NONE | No compression.
WIA_COMPRESSION_BI_RLE4 | DIB 4 bit run length encoding.
WIA_COMPRESSION_BI_RLE8 | DIB 8 bit run length encoding.
WIA_COMPRESSION_G3 | TIFF CCITT G3

WIA_IPA_TYMED

Specifies data transfer type.

Transfer Type | Description
TYMED_CALLBACK | Use callback based data transfer.
TYMED_MULTIPAGE_CALLBACK | Use callback based data transfer for multipage or finished file scans.
TYMED_FILE | Use file based data transfer.
TYMED_MULTIPAGE_FILE | Use file based data transfer for multipage or finished file scans.

WIA_IPA_CHANNELS_PER_PIXEL

Number of color channels per pixel. Typical values are 1 for black and white data; 3 for RGB.

WIA_IPA_BITS_PER_CHANNEL

Bits per color channel. 1 for 1 bit per pixel black and white; 8 for 8-bit-per-pixel RGB. This property is read/write for scanners that support different bits-per-pixel settings. Otherwise it is read only.

WIA_IPA_PLANAR

Describes whether the data is returned in a planar or packed-pixel format.

WIA_IPA_PIXELS_PER_LINE

Number of pixels per line in the current image. This is a read-only property and is set by the device based on the scan settings.

WIA_IPA_BYTES_PER_LINE

Bytes per line of scan data. Some scanners may pad scan lines with extra bytes to make the scan line a fixed number of DWORDS. This is a read-only property and is set by the device, based on the scan settings.

WIA_IPA_NUMBER_OF_LINES

Number of lines in the final image. This is a read-only property and is set by the device, based on the scan settings.

WIA_IPA_GAMMA_CURVES

Gamma Correction curves for each color channel. Format is TBD.

WIA_IPA_ITEM_SIZE

Total data transfer size including data and data-specific header information, if the size is known. If the size is not known, this property must be set to zero.

WIA_IPA_MIN_BUFFER_SIZE

This property is used to specify the minimum buffer size used in data transfers. If the data transfer is done via callback, it may be as small as 64K, but if the transfer is to file, then it is the number of bytes needed to transfer a page of data at a time.

WIA_IPA_REGION_TYPE

This property is used to specify the type of region the image analysis has created. The following region types are supported:

Region Type | Description
WIA_TEXT_ITEM | Region contains text.
WIA_PHOTO_ITEM | Region contains a photo.
WIA_DRAWING_ITEM | Region contains a line drawing.
WIA_LOGO_ITEM | Region contains a logo.
WIA_HANDWRITING_ITEM | Region contains handwriting.
WIA_CHART_ITEM | Region contains a chart or graph.
WIA_TABLE_ITEM | Region contains tabular data.

WIA_IPA_COLOR_PROFILE

This property specifies the International Color Consortium (ICC) color profile for the images produced by the item.

When the WIA_IPA_APP_COLOR_MAPPING property is set, the current value of this property indicates the color profile for images produced by the WIA item. If the color mapping property is not set, the driver will map images from the current value of this property to sRGB.

This property should not be set by the application or driver. It is managed by WIA based on user input. The valid values setting lists the profiles the user has associated with the device.

WIA_IPA_APP_COLOR_MAPPING

By default, it is the responsibility of the driver to map images from the user-selected profile to SRGB. If an application uses the ICM system to handle color profiles, it sets this property to instruct the driver to stop mapping automatically. The images is then in the color space specified by the WIA_IPA_COLOR_PROFILE property.

WIA_IPA_PROP_STREAM_COMPAT_ID

This property specifies a CLSID that represents a set of device property values. If a device driver implements this feature, applications use this property to determine if the device supports a set of values.


Camera WIA Item Property Constants

The following constants form the set of valid WIA camera item properties:

Property Name | Requirement | Type | Access
WIA_IPC_THUMBNAIL | Mandatory | VT_UI1/VT_VECTOR | TBD
WIA_IPC_THUMB_WIDTH | Mandatory | VT_I4 | Read Only
WIA_IPC_THUMB_HEIGHT | Mandatory | VT_I4 | Read Only
WIA_IPC_AUDIO_AVAILABLE | Optional | VT_I4 | Read Only
WIA_IPC_AUDIO_DATA_FORMAT | Optional | VT_CLSID | Read Only
WIA_IPC_AUDIO_DATA | Optional | VT_UI1/VT_VECTOR | Read Only
WIA_IPC_XCOORDINATE | Optional | VT_I4 | Read Only
WIA_IPC_YCOORDINATE | Optional | VT_I4 | Read Only
WIA_IPC_SEQUENCE | Optional | VT_I4 | Read-Only
WIA_IPC_TIMEDELAY | Optional | VT_I4 | Read-Only

WIA_IPC_THUMBNAIL

The thumbnail data. This is a fixed format consisting of raw, 24 bit, DWORD aligned, Blue-Green-Red color order, DIB bits with no DIB header.

WIA_IPC_THUMB_WIDTH

Specifies the width of the thumbnail in pixels.

WIA_IPC_THUMB_HEIGHT

Specifies the height of the thumbnail in pixels.

WIA_IPC_AUDIO_AVAILABLE

The camera item has audio data available.

WIA_IPC_AUDIO_DATA_FORMAT

Audio formats for WIA are TBD.

WIA_IPC_AUDIO_DATA

Camera Audio data.

WIA_IPC_XCOORDINATE

Indicates the relative horizontal position of this image in a multi-image panorama. The numbers are not required to be sequential or start at any particular value. The values increase from left to right.

WIA_IPC_YCOORDINATE

Indicates the relative vertical position of this image in a multi-image panorama. The numbers are not required to be sequential or start at any particular value. The values increase from bottom to top.

WIA_IPC_SEQUENCE

Indicates the relative temporal position of this image in a mutli-image time sequence. The numbers are not required to be sequential or start at any particular value. The values increase with time.

WIA_IPC_TIMEDELAY

Indicates the amount of time, in milliseconds, that transpired between the capture of the current image and the previous image.


Scanner WIA Item Property Constants

The following constants specify the valid set of WIA scanner item properties:

Property Name | Requirement | Type | Access
WIA_IPS_CUR_INTENT | Mandatory | VT_I4 | R/W
WIA_IPS_XRES | Mandatory | VT_I4 | R/W
WIA_IPS_YRES | Mandatory | VT_I4 | See text
WIA_IPS_XPOS | Mandatory | VT_I4 | R/W
WIA_IPS_YPOS | Mandatory | VT_I4 | R/W
WIA_IPS_XEXTENT | Mandatory | VT_I4 | R/W
WIA_IPS_YEXTENT | Mandatory | VT_I4 | R/W
WIA_IPS_PHOTOMETRIC_INTERP | Mandatory | VT_I4 | See text
WIA_IPS_BRIGHTNESS | Mandatory | VT_I4 | R/W
WIA_IPS_CONTRAST | Mandatory | VT_I4 | R/W
WIA_IPS_ORIENTATION | Optional | VT_I4 | Read Only
WIA_IPS_ROTATION | Optional | VT_I4 | R/W
WIA_IPS_MIRROR | Optional | VT_I4 | See text
WIA_IPS_THRESHOLD | Mandatory | VT_I4 | R/W
WIA_IPS_PREVIEW | Optional | VT_I4 | R/W
WIA_IPS_INVERT | Optional | VT_I4 | R/W
WIA_IPS_WARM_UP_TIME | Optional | VT_I4 | Read Only

WIA_IPS_CUR_INTENT

Allows a driver to preset item properties based on the intended use of the image of an application. To provide an intent, use an intended image type flag and an intended size/quality flag OR'ed together. Note that an image cannot be both grayscale and color.

Intended image type flags | Description
WIA_INTENT_NONE | Default value. Do not preset any properties.
WIA_INTENT_IMAGE_TYPE_COLOR | Preset properties for color content.
WIA_INTENT_IMAGE_TYPE_GRAYSCALE | Preset properties for grayscale content.
WIA_INTENT_IMAGE_TYPE_TEXT | Preset properties for text content.
WIA_INTENT_IMAGE_TYPE_MASK | Mask for all of the image type flags.

Intended image size/quality flags | Description
WIA_INTENT_MINIMIZE_SIZE | Preset properties to minimize image size.
WIA_INTENT_MAXIMIZE_QUALITY | Preset properties to maximize image quality.
WIA_INTENT_SIZE_MASK | Mask for all of the size/quality flags.

WIA_IPS_XRES - Horizontal Resolution

Specifies the current horizontal (X) axis resolution, in dots per inch (DPI).For scanners that do not support the independent setting of horizontal and vertical resolutions, the vertical resolution tracks the Horizontal Resolution property. To find out if the scanner supports independent resolutions, query the Vertical Resolution property.

The following properties are dependent on the Horizontal Resolution property for the independent resolution case:

Horizontal Start Position

Horizontal Extent

Pixels per Line

Bytes Per Line

File Size

In addition, the following properties are also reliant in the dependent resolution case:

Vertical Start Position

Vertical Extent

Number of Lines

This property is either a range or a list.

WIA_IPS_YRES - Vertical Resolution

For scanners that support the independent setting of horizontal and vertical resolution, this property specifies the current vertical (Y) axis resolution, in DPI. It is implemented as read/write. For scanners that do not support independent setting of horizontal and vertical resolutions, this property is implemented as read-only and tracks the WIA_IPS_XRES property.

The following properties are dependent on the Vertical Resolution property:

Vertical Start Position

Vertical Extent

Number of Lines

File Size

WIA_IPS_XPOS - Horizontal Start Position

The horizontal start position in pixels of the image to be scanned.

WIA_IPS_YPOS - Vertical Start Position

The vertical start position in pixels of the image to be scanned.

WIA_IPS_XEXTENT - Horizontal Extent

The width of the scan in pixels.

WIA_IPS_YEXTENT - Vertical Extent

The height of the scan in lines.

WIA_IPS_PHOTOMETRIC_INTERP

Photometric interpretation. The default color interpretation of image data.

WIA_PHOTO_WHITE_1 : white is 1, black is 0.

WIA_PHOTO_WHITE_0 : white is 0, black is 1.

For devices or drivers that support selectable photometric interpretation, the access for this property is read/write. For all others, it is read only.

WIA_IPS_BRIGHTNESS

The image brightness values available within the scanner. All scanners must support the following brightness constants.

It is up to the scanner driver to supply a range of valid values for this proeprty. Applications query the device for the valid values. Smaller values make the image darker. Larger values make the image brighter..

WIA_IPS_CONTRAST

The image contrast values available within the scanner. All scanners must support the following constants.

It is up to the scanner driver to supply a range of valid values for this proeprty. Applications query the device for the valid values. Smaller values make the image darker. Larger values make the image brighter.

WIA_IPS_ORIENTATION

If a scanner can support the detection of document orientation, this property is implemented. The orientation flags include the following.

Constant | Description
PORTRAIT | The image data is in portrait orientation(0 degrees rotation).
LANSCAPE | The image data is in landscape orientation (the page is rotated 90 degrees counter-clockwise).
ROT180 | The image data is in an upside-down orientation (180 degrees rotation).
ROT270 | The image data is in an upside-down landscape orientation (the page is rotated 270 degrees counter-clockwise).

WIA_IPS_ROTATION

If a scanner supports internal rotation during scanning, this property is implemented. The rotation flags include the following.

Constant | Description
PORTRAIT | The driver or device will not rotate the image (0 degrees counter-clockwise).
LANSCAPE | The driver or device rotates the image 90 degrees counter-clockwise.
ROT180 | The driver or device rotates the image 180 degrees counter-clockwise.
ROT270 | The driver or device rotates the image 270 degrees counter-clockwise.

WIA_IPS_MIRROR

If a scanner supports the detection of document mirroring, this property is implemented with read-only access. If a scanner supports mirroring during scanning, this property is implemented with read/write access. The mirroring flags include the following.

Constant | Description
MIRRORED | The image data is in mirrored orientation, or requests the device to mirror-invert the image.

WIA_IPS_THRESHOLD

Specifies the dividing line between black and white. This is the value the scanner uses to threshold, when the WIA_IPA_DATATYPE property is set to WIA_DATA_THRESHOLD. Higher positive values represent lighter pixel values.

The device driver specifies a range of valid values for this property. Applications query the device for the range of valid values.

WIA_IPS_PREVIEW

This property indicates whether or not the device supports preview scans. For example, sheet-fed and hand-held scanners do not preview. The application should set this property when it does a preview scan so that the device is optimized for previewing.

WIA_IPS_INVERT

Specifies a photo-negative scan.

WIA_IPS_WARM_UP_TIME

Indicates to the application how long, in milliseconds, it takes the scanner and/or lamp to warm up before scanning commences. The application displays a progress indicator to the user based on this value. If the device requires no warm-up, the value should be zero.


Property Attributes

All item objects have properties. The properties have attributes. For instance, property attributes indicate whether a property is read from, written to, or deleted. They also indicate the valid property values. The following constants are valid property attributes:

Property Attribute | Meaning
WIA_PROP_CACHEABLE | The device can cache the property's value.
WIA_PROP_FLAG | The property has a list of legal flag values. Flag values are combined using a bitwise OR operation.
WIA_PROP_LIST | The property has a list of legal values.
WIA_PROP_NONE | The WIA hardware device does not support the property.
WIA_PROP_RANGE | The property has a range of valid values.
WIA_PROP_READ | The application can read the property's value.
WIA_PROP_RW | The application can read and write the property's value.
WIA_PROP_WRITE | The application can write the property's value.


Image Intent Constants

Image intent constants specify what type of data the image is meant to represent. The following are valid image intent constants:

Intent | Meaning
WIA_INTENT_NONE | No intent specified.
WIA_INTENT_BEST_PREVIEW | Specifies the best quality preview.
WIA_INTENT_IMAGE_TYPE_COLOR | Specifies that the image is a color illustration.
WIA_INTENT_IMAGE_TYPE_GRAYSCALE | Specifies that the image is grayscale data.
WIA_INTENT_IMAGE_TYPE_TEXT | Specifies that the image is a text image such as a fax or scanned document.

The intent constants are combined with image size and quality constants using a bitwise OR operation. The image size quality constants are as follows:

Constant | Meaning
WIA_INTENT_MINIMIZE_SIZE | Use a lower quality scan to minimize the size of the file that contains the image.
WIA_INTENT_MAXIMIZE_QUALITY | Use a higher quality scan to maximize the quality of the image.


WIA Event Identifiers

WIA event identifiers are globally unique identifiers (GUID) defined by the WIA system. The following are valid WIA event GUIDs:

GUID | Meaning
WIA_EVENT_DEVICE_CONNECTED | A WIA hardware device was connected to the user's computer or started.
WIA_EVENT_DEVICE_DISCONNECTED | A WIA hardware device was disconnected from the user's computer or stopped
WIA_EVENT_ITEM_CREATED | An item was added to the tree of IWiaItem objects for a WIA device.
WIA_EVENT_ITEM_DELETED | An item was deleted from the tree of IWiaItem objects for a WIA device.
WIA_EVENT_STORAGE_CREATED | A storage unit, such as a flash card, was added to the device. The application should recreate the item tree that represents this device.
WIA_EVENT_STORAGE_DELETED | A storage unit, such as a flash card, was removed from the device. The application should recreate the item tree that represents this device.


WIA Device Type Specifiers

WIA Device Type Specifiers are constants that indicate the type of device attached to a user's computer. The following are valid WIA Device Type Specifiers:

Device Type | Meaning
StiDeviceTypeDefault | Generic WIA device. During device enumerations, this constant is used to enumerate all WIA devices.
StiDeviceTypeDigitalCamera | The device is a camera.
StiDeviceTypeScanner | The device is a scanner.
StiDeviceTypeStreamingVideo | The device contains streaming video.


WIA Item Type Flags

The following constants specify the WIA item type:

Type Constant | Meaning
WiaItemTypeAnalyze | This item supports the IWiaItem::AnalyzeItem method.
WiaItemTypeAudio | The item is an audio file. Only valid for items that also have the WiaItemTypeFile attribute.
WiaItemTypeBurst |
WiaItemTypeDeleted | The item is marked as deleted from the tree.
WiaItemTypeDevice | The item represents a connected device.
WiaItemTypeDisconnected | The item represents a disconnected device.
WiaItemTypeFile | The item is a file.
WiaItemTypeFolder | The item is a folder.
WiaItemTypeFree | The item is uninitialized or has been deleted.
WiaItemTypeGenerated |
WiaItemTypeHasAttatchments | The item has file attatchments.
WiaItemTypeHPanorama | The item represents a horizontal panoramic image.
WiaItemTypeImage | The item is an image file. Only valid for items that also have the WiaItemTypeFile attribute.
WiaItemTypeRoot | Identifies the root item in the device's tree of item objects.
WiaItemTypeStorage |
WiaItemTypeTransfer | The item represents a WIA data transfer.
WiaItemTypeVideo | The item represents streaming video.
WiaItemTypeVPanorama | The item represents a vertical panoramic image.


Error Codes

WIA functions and methods can return error codes from the following list:

Error Code | Meaning
WIA_ERROR_DEVICE_LOCKED | The scanner head is locked.
WIA_ERROR_EXCEPTION_IN_DRIVER | The device driver threw an exception.
WIA_ERROR_GENERAL_ERROR | An unknown error has occurred with the WIA device.
WIA_ERROR_INCORRECT_HARDWARE_SETTING | There is an incorrect setting on the WIA device.
WIA_ERROR_INVALID_DRIVER_RESPONSE | The response from the driver is invalid.
WIA_ERROR_PAPER_JAM | Paper is jammed in the scanner's document feeder.
WIA_ERROR_PAPER_EMPTY | The user requested a scan and there are no documents left in the document feeder.
WIA_ERROR_PAPER_PROBLEM | An unspecified problem occurred with the scanner's document feeder.
WIA_ERROR_OFFLINE | The WIA device is not online.
WIA_ERROR_BUSY | The WIA device is busy.
WIA_ERROR_WARMING_UP | The WIA device is warming up.
WIA_ERROR_USER_INTERVENTION | An unspecified error has occurred with the WIA device that requires user intervention. The user should ensure that the device is turned on, online, and any cables are properly connected.
WIA_ERROR_ITEM_DELETED | The WIA device was deleted. It can no longer be accessed.
WIA_S_NO_DEVICE_AVAILABLE | No WIA device of the selected type is available.
WIA_ERROR_DEVICE_COMMUNICATION | An unspecified error occurred during an attempted communication with the WIA device.
WIA_ERROR_INVALID_COMMAND | The device does not support this command.


WIA Scripting Model

WIA provides automation objects for use in scripting languages, such as JScript® and Visual Basic® Scripting Edition development software, and high-level programming languages such as Visual Basic® development system.

The following table describes WIA scripting objects and how they are used.

Object | Description
Wia | The top-level WIA scripting object. Use the Wia object to enumerate and connect to devices, and to handle hardware device events.
DeviceInfo | The DeviceInfo object provides access to information about device properties.
Item | This object represents WIA device, file, and folder items. A WIA hardware device and its images or scanning beds is represented as a hierarchical tree of Item objects.

Both the DeviceInfo object and the Item object are associated with collection objects. For information about using collection objects, see Using WIA Collection Objects.

The following topics cover general information about using the WIA scripting model:

  • Syntax Conventions
  • Using WIA Collection Objects
  • WIA Property Constant Definitions


Syntax Conventions

The following table lists the terms used in syntax statements for the WIA scripting model reference.

Term | Description
Filename | The path and name of a file.
objDeviceInfo | A DeviceInfo object.
objDeviceInfoCollection | A collection of DeviceInfo objects.
objItem | An Item object.
objItemCollection | A collection of Item objects.
objWia | A Wia object.
PropID | A WIA property constant.
var | A VARIANT value.


Using WIA Collection Objects

A collection is an object that contains one or more objects. Collections provide an efficient way of grouping similar objects. WIA provides collections for the DeviceInfo and Item objects.

Use collections to enumerate the objects they contain. For example, the following VBScript example obtains a collection of DeviceInfo objects from the Wia.Devices method and then uses a For...Each loop to iterate through the collection:

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    ' Do something with the DeviceInfo object.
Next
</SCRIPT>

For more information about collections, see Collection Methods in the Automation section of the COM Programmer's Reference.


WIA Property Constant Definitions

The following is a list of WIA property friendly names and numerical IDs. They are presented as Visual Basic constant definitions, for convenient inclusion in applications or scripts.

const DeviceID = 2
const Manufacturer = 3
const Description = 4
const Type = 5
const Port = 6
const Name = 7
const Server = 8
const RemoteDevID = 9
const UIClassID = 10
const FirmwareVersion = 1026
const ConnectStatus = 1027
const DeviceTime = 1028
const PicturesTaken = 2050
const PicturesRemaining = 2051
const ExposureMode = 2052
const ExposureCompensation = 2053
const ExposureTime = 2054
const FNumber = 2055
const FlashMode = 2056
const FocusMode = 2057
const FocusManualDist = 2058
const ZoomPosition = 2059
const PanPosition = 2060
const TiltPostion = 2061
const TimerMode = 2062
const TimerValue = 2063
const PowerMode = 2064
const BatteryStatus = 2065
const Dimension = 2070
const HorizontalBedSize = 3074
const VerticalBedSize = 3075
const HorizontalSheetFeedSize = 3076
const VerticalSheetFeedSize = 3077
const SheetFeederRegistration = 3078
const HorizontalBedRegistration = 3079
const VerticalBedRegistraion = 3080
const PlatenColor = 3081
const PadColor = 3082
const FilterSelect = 3083
const DitherSelect = 3084
const DitherPatternData = 3085
const DocumentHandlingCapabilities = 3086
const DocumentHandlingStatus = 3087
const DocumentHandlingSelect = 3088
const DocumentHandlingCapacity = 3089
const HorizontalOpticalResolution = 3090
const VerticalOpticalResolution = 3091
const EndorserCharacters = 3092
const EndorserString = 3093
const ScanAheadPages = 3094
const MaxScanTime = 3095
const Pages = 3096
const PageSize = 3097
const PageWidth = 3098
const PageHeight = 3099
const Preview = 3100
const TransparencyAdapter = 3101
const TransparecnyAdapterSelect = 3102
const ItemName = 4098
const FullItemName = 4099
const ItemTimeStamp = 4100
const ItemFlags = 4101
const AccessRights = 4102
const DataType = 4103
const BitsPerPixel = 4104
const PreferredFormat = 4105
const Format = 4106
const Compression = 4107
const MediaType = 4108
const ChannelsPerPixel = 4109
const BitsPerChannel = 4110
const Planar = 4111
const PixelsPerLine = 4112
const BytesPerLine = 4113
const NumberOfLines = 4114
const GammaCurves = 4115
const ItemSize = 4116
const ColorProfiles = 4117
const BufferSize = 4118
const RegionType = 4119
const ColorProfileName = 4120
const ApplicationAppliesColorMapping = 4121
const StreamCompatibilityID = 4122
const ThumbData = 5122
const ThumbWidth = 5123
const ThumbHeight = 5124
const AudioAvailable = 5125
const AudioFormat = 5126
const AudioData = 5127
const PicturesPerRow = 5128
const SequenceNumber = 5129
const TimeDelay = 5130
const CurrentIntent = 6146
const HorizontalResolution = 6147
const VerticalResolution = 6148
const HorizontalStartPostion = 6149
const VerticalStartPosition = 6150
const HorizontalExtent = 6151
const VerticalExtent = 6152
const PhotometricInterpretation = 6153
const Brightness = 6154
const Contrast = 6155
const Orientation = 6156
const Rotation = 6157
const Mirror = 6158
const Threshold = 6159
const Invert= 6160
const LampWarmUpTime = 6161


Wia

The Wia object is the entry point for all WIA scripting functionality. Any application that uses the WIA scripting model must create a Wia object. Use the Wia object to enumerate and create devices, and to receive notification of hardware events.

Methods

The following table lists the method for the Wia object.

Method | Description
Create | Establishes a connection to the specified WIA device.

Properties

The following table lists the property for the Wia object.

Property | Description
Devices | A collection of DeviceInfo objects that represents all the WIA devices installed on the machine.

Events

The following table lists the events for the Wia object.

Event | Description
OnDeviceConnected | A new device was installed on the machine.
OnDeviceDisconnected | A device was removed from the machine.
OnTransferComplete | WIA completed a file data transfer.


Wia.Create

The Create method of the Wia object makes a connection to the specified WIA device, and returns an Item object that represents the device.

objItem = objWia.Create(
  Device
);

Parameters

Device
[in] Specifies the WIA device to which to connect.

Return Values

If successful, this method returns an Item object that represents a WIA hardware device (a root item).

Remarks

The Device parameter specifies a DeviceInfo object by passing the object itself, its index from a collection object, or the value of its Id property. Pass Nothing to display a dialog box that allows a user to select a device.

Example

The following VBScript examples demonstrate the use of the Create method.

The first example passes a DeviceInfo object to the Create method. Note that passing the object's Id property causes exactly the same behavior.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objItem

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    Set objItem = objWia.Create(objDeviceInfo)
Next
</SCRIPT>

In the next example, the caller passes the index of the DeviceInfo object in the collection to the Create method.

<SCRIPT LANGUAGE = "VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objItem

Set objWia = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For i = 0 To objDeviceInfoCollection.Count-1
    Set objItem = objWia.Create(i)
Next
</SCRIPT>

The next example passes Nothing to the Create method to display a dialog box that allows a user to select a device.

<SCRIPT LANGUAGE = "VBScript">
Dim objWia
Dim objItem

Set objWia = objWia.Create(Nothing)
</SCRIPT>


Wia.Devices

Collection of DeviceInfo objects that represents all of the devices installed on the machine. Read-only.

objDeviceInfoCollection = objWia.Devices

Example

The following example illustrates the use of the Devices collection to enumerate the devices on a system.

<SCRIPT LANGUAGE = "VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo

Set objWia = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    ! Do something with the DeviceInfo object
Next
</SCRIPT>


Wia.OnDeviceConnected

Event that occurs when a new WIA hardware device is connected.

objWia_OnDeviceConnected()

Remarks

WIA notifies the script or application whenever a new hardware device is connected to the machine. Implement the objWia_OnDeviceConnected() subroutine to allow the script or application to respond to the device connection.

For example, you might want a script to refresh the Devices collection when a new device is installed.


Wia.OnDeviceDisconnected

Event that occurs when a new WIA hardware device is disconnected.

objWia_OnDeviceDisconnected()

Remarks

WIA notifies the script or application whenever a hardware device is disconnected from the machine. Implement the objWia_OnDeviceDisconnected() subroutine to allow the script or application to respond to the device disconnection.

For example, you might want a script to refresh the Devices collection when a device is removed from the machine.


Wia.OnTransferComplete

Event that occurs when a data transfer is completed successfully.

objWia_OnTransferComplete()

Remarks

WIA notifies the script or application when a data transfer, image or sound, completes successfully. Implement the objWia_OnTransferComplete() subroutine to allow your script or application to respond to the completion of the data transfer.

For example, you might want a script to display an image after it is transferred.


DeviceInfo

The DeviceInfo object provides access to the properties of a WIA hardware device. It also, through its Create method, provides a way for the application or script to connect to the device and obtain an Item object that represents the device. Use the Wia.Devices method to obtain a collection of DeviceInfo objects.

Methods

The following table lists the methods for the DeviceInfo object.

Method | Description
Create | Establishes a connection to the WIA device.
GetPropById | Returns a value of the property using its ID.

Properties

The following table lists the properties for the DeviceInfo object.

Property | Description
Id | The ID of the WIA device.
Name | The text name of the WIA device as it appears in the UI.
Manufacturer | The manufacturer of the device.
Port | The port to which the device is connected.
Type | The type of the device (camera or scanner).
UIClsid | The CLSID of the manufacturer's device UI.


DeviceInfo.Create

The Create method of the DeviceInfo object makes a connection to the WIA device specified by the DeviceInfo object, and returns an Item object that represents the device.

objItem = objDeviceInfo.Create()

Parameters

None.

Return Values

This method returns the Item object that represents the device that is created.

Remarks

Use the DeviceInfo.Create method to create a connection to a WIA hardware device after enumerating the Wia.Devices collection. The method returns an Item object that represents the device (a root item).

Example

The following example demonstrates the use of the DeviceInfo.Create method.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objItem

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    Set objItem = objDeviceInfo.Create()
Next
</SCRIPT>


DeviceInfo.GetPropById

The GetPropById method of the DeviceInfo object uses a device property's ID to return its value.

var = objDeviceInfo.GetPropById(
  PropID
);

Parameters

PropID
[in] Specifies the ID of the property.

Return Values

This method returns the value of the property specified by PropID.

Remarks

Use this method to find the value of a device property from its ID. For a list of property IDs, see WIA Property Constant Definitions. For information about WIA properties themselves, see WIA Property Constants.

Example

The following example demonstrates the use of the GetPropById method to retrieve a property value.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim PropValue

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    PropValue = objDeviceInfo.GetPropById(WIA_DIP_DEV_TYPE)
Next
</SCRIPT>


DeviceInfo.Id

The ID of the WIA hardware device. Read-only.

var = objDeviceInfo.ID


DeviceInfo.Manufacturer

The manufacturer of the WIA hardware device.

var = objDeviceInfo.Manufacturer


DeviceInfo.Name

The name of the WIA hardware device as it appears in the UI.

var = objDeviceInfo.Name


DeviceInfo.Port

The port to which the WIA hardware device is connected.

var = objDeviceInfo.Port


DeviceInfo.Type

The type of WIA hardware device. Possible values are DigitalCamera, Scanner, and Default.

var = objDeviceInfo.Type


DeviceInfo.UIClsid

The CLSID of the manufacturer-provided UI for this WIA hardware device. The value is a string representation of a GUID.

var = objDeviceInfo.UIClsid


Item

WIA hardware devices are represented as heirarchical trees of Item objects. The root item in this tree represents the device itself, while child items represent images, folders, or scanning beds.

Use the Item object to transfer data to a file, to navigate the item tree for a particular device, or to retrieve information about an image or a device.

Methods

Method | Description
GetItemsFromUI | Displays a dialog box that allows a user to select images to transfer from the device or folder.
GetPropById | Returns a value of the property using its ID.
Transfer | Transfers an image or sound from a device to a specified file.

Properties

Property | Description
Children | A collection of Item objects that represent the children of the folder or device. Applies only to devices and folders.
ConnectStatus | The status of the connection of the device. Applies only to devices.
FirmwareVersion | The firmware version of the WIA hardware device. Applies only to devices.
FullName | The full name of the item.
Height | The height, in pixels, of the image. Applies only to images.
ItemType | The type of the item. This can be device, image, file, folder, or audio.
Name | The name of the item as it appears in the UI.
PictureHeight | The height, in pixels, of images taken by the digital camera. Applies only to devices.
PictureWidth | The width, in pixels, of images taken by the digital camera. Applies only to devices.
ThumbHeight | The height, in pixels, of the thumbnail image.
ThumbNail | The URL for the thumbnail image.
ThumbWidth | The width, in pixels, of the thumbnail image.
Time | The current time. Applies only to devices.
Width | The width, in pixels, of the image. Applies only to images.


Item.GetItemsFromUI

The GetItemsFromUI method of the Item object displays a dialog box that allows a user to select images and audio to transfer from a device.

objItemCollection = objItem.GetItemsFromUI(
  Flags,
  Intent
);

Parameters

Flags
[in] Specifies dialog box behavior. Currently, this parameter can be set to zero, to indicate normal operation, or WIA_DEVICE_DIALOG_SINGLE_IMAGE to restrict the user to selecting a single image.
Intent
[in] Specifies what type of data the image is intended to represent. For a list of image intent values, see Image Intent Constants.

Return Values

This method returns a collection of Item objects that represent the items selected by the user. If no items are selected, the collection is empty.

Example

The following example demonstrates the use of the GetItemsFromUI method to allow a user to select images from a dialog box.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objRootItem
Dim objSelectedItems

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    Set objRootItem = objWia.Create(objDeviceInfo)
    Set objSelectedItems = objRootItem.GetItemsFromUI(0, 0)
    ' Do something with selected items.
Next
</SCRIPT>

Remarks

This method applies only to devices (root items). The method returns a collection of Item objects that represent the images or audio clips selected by the user.

If no items are selected by the user, the method returns an empty collection.


Item.GetPropById

The GetPropById method of the Item object uses the ID of an item property to return its value.

var = objItem.GetPropById(
  PropID
);

Parameters

PropID
[in] Specifies the ID of the property.

Return Values

This method returns the value of the property specified by PropID.

Remarks

Use this method to find the value of an item property from its ID. For a list of property IDs, see WIA Property Constant Definitions. For information about the properties themselves, see WIA Property Constants.

Example

The following example demonstrates the use of the GetPropById method to retrieve a property value.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objRootItem
Dim objSelectedItems
Dim objItem
Dim PropValue

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    objRootItem=objDeviceInfo.Create()
    objSelectedItems=objRootItem.GetItemsFromUI(0, 0)
    For Each objItem In objSelectedItem
    PropValue = objItem.GetPropById(DeviceType)
    Next
Next
</SCRIPT>


Item.Transfer

The Transfer method of the Item object transfers data from a device to a file. This method applies only to file type items.

None objItem.Transfer(
  Filename,
  Asynchronous
);

Parameters

Filename
[in] Specifies the name of the file to which the data is transferred.
Asynchronous
[in] A boolean value that specifies whether the transfer should be executed as an asynchronous call. Set this value to True if the call should be asynchrounous (see Remarks).

Return Values

None.

Remarks

This method applies only to file type items. The method checks that the item supports this method before it attempts to complete the data transfer.

Use "clipboard" as the Filename parameter to transfer an item to the clipboard.

Set the Asynchronous value to False for transfers within any application or script that runs in an environment that terminates a process at the end of a script, such as Windows® Scripting Host. Otherwise, the script may end, and the process terminate, before the transfer completes.

The Transfer method has no return value. Upon completion of a transfer, this method sends an OnTransferComplete event to the script or application.

Example

The following example demonstrates th use of the Transfer method to transfer data from a device.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objRootItem
Dim objSelectedItems
Dim objItem

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    Set objRootItem = objWia.Create(objDeviceInfo)
    Set objSelectedItems = objRootItem.GetItemsFromUI(0, 0)
    For Each objItem In objSelectedItems
        objItem.Transfer("c:\Folder\Filename.bmp")
    Next
Next
</SCRIPT>


Item.Children

The Children property of the Item object returns a collection of Item objects. The items in this collection represent items that are direct children of this item in the hierarchical tree. Read-only.

objItemColleciton = objItem.Children

Remarks

Use this property to navigate the hierarchical tree of Item objects that represent a device, the folders and the files that reside on the device.

The Children property is a collection of Item objects only from the level directly beneath this Item object in the tree. To navigate further levels down the tree, use this property recursively.

If the item cannot or does not have any child items, this property returns an empty collection.

Example

The following example demonstrates the use of the Children property to retrieve and enumerate a collection of the child items of a device. If the device is a digital camera, the collection typically contains folder and image items. If the device is a scanner, the collection typically contains items that represent scanning beds.

<SCRIPT LANGUAGE="VBScript">
Dim objWia
Dim objDeviceInfoCollection
Dim objDeviceInfo
Dim objRootItem
Dim objItemCollection
Dim objItem

Set objWIA = CreateObject("Wia.Script")

Set objDeviceInfoCollection = objWia.Devices

For Each objDeviceInfo In objDeviceInfoCollection
    Set objRootItem = objWia.Create(objDeviceInfo)
    objItemCollection = objRootItem.Children
    For Each objItem In objItemCollection
        ' Do something with the child item
    Next
Next
</SCRIPT>


Item.ConnectStatus

The connection status of the device. This property applies only to items of type device (root items). Possible values are "connected", "disconnected", or NULL (if this property does not apply to the item). Read-only.

val = objItem.ConnectStatus


Item.FirmwareVersion

The firmware version of the device. This property applies only to items of type device (root items). Read-only.

val = objItem.FirmwareVersion


Item.FullName

The full name of the item as it appears in the UI. Read-only.

val = objItem.FullName


Item.Height

The height, in pixels, of the item. Read only.

val = objItem.Height

Remarks

If the item is a digital camera, the Height property represents the height of images that this camera generates. If the item is a scanner, this property represents the height of the scanning bed. If the item is an image, this property represents the actual height of the image.


Item.ItemType

The type of this item. Read-only.

val = objItem.ItemType

Return Values

The following values are possible:

Value | Description
device | The item is a WIA hardware device.
folder | The item is a folder that contains other items.
file | The item is an image or audio file.
audio | The item is an audio clip.
image | The item is an image.

Remarks

An item can have more than one type. For example, every image is of both "image" and "file" types. ItemType returns a string that includes all valid types for the item, separated by semicolons. For example, "image;file". There are no spaces in this string, and there is not a semicolon at the end.


Item.Name

The name of the item as it appears in the UI. Read-only.

val = objItem.Name


Item.PictureHeight

The height, in pixels, of images produced by this digital camera. Applies only to digital cameras. Read-only.

val = objItem.PictureHeight


Item.PictureWidth

The width, in pixels, of images produced by this digital camera. Applies only to digital cameras. Read-only.

val = objItem.PictureWidth


Item.ThumbHeight

The height, in pixels, of the thumbnail image. This property returns 0 if this item does not support thumbnails. Read-only.

val = objItem.ThumbHeight


Item.ThumbNail

The path and filename of the thumbnail image. This property is NULL if the item does not support thumbnails, or if a path cannot be built. Read-only.

val = objItem.ThumbNail


Item.ThumbWidth

The width, in pixels, of the thumbnail image. This property returns 0 if this item does not support thumbnails. Read-only.

val = objItem.ThumbWidth


Item.Time

The current time. Applies only to devices. Read-only.

val = objItem.Time


Item.Width

The width, in pixels, of the item. Read only.

val = objItem.Width

Remarks

If the item is a digital camera, the Width property represents the width of images that the camera generates. If the item is a scanner, this property represents the width of the scanning bed. If the item is an image, this property represents the actual width of the image.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.