Windows Image Acquisition (WIA) Driver Samples

The Windows Image Acquisition driver sample set contains samples and test tools for Windows Image Acquisition (WIA), a driver architecture and user interface for acquiring images from still image devices such as scanners.

PRODUCTION SCANNING WIA 2.0 DRIVER

The ProdScan directory contains a sample WIA 2.0 mini-driver. This sample shows how to add Production Scanning features to a WIA 2.0 mini-driver.

EXTENDED WIA 2.0 MONSTER DRIVER

The Wiadriverex directory contains a sample WIA 2.0 mini-driver. This sample shows how to write a WIA 2.0 mini-driver that uses the stream-based WIA 2.0 transfer model. It also shows an implementation of a very simple segmentation filter, image processing filter, and error handling extension for the WIA 2.0 mini-driver.

For more information, see Introduction to WIA.

Build the sample

You can build the sample in two ways: using the Visual Studio Integrated Development Environment (IDE) or from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild.exe).

Building the sample using Visual Studio

Open Visual Studio. From the File menu, select Open Project/Solution. Within your WDK installation, navigate to src\wia and open the wia.sln project file.

Right-click the solution in the Solution Explorer and select Configuration Manager.

From the Configuration Manager, select the Active Solution Configuration (for example, Windows 8.1 Debug or Windows 8.1 Release) and the Active Solution Platform (for example, Win32) that correspond to the type of build you are interested in.

From the Build menu, click Build Solution (Ctrl+Shift+B).

Windows Image Acquisition (WIA)

Windows Image Acquisition (WIA) is the still image acquisition platform in the Windows family of operating systems starting with WindowsВ Millennium Edition (WindowsВ Me) and WindowsВ XP.

Introduction

The WIA platform enables imaging/graphics applications to interact with imaging hardware and standardizes the interaction between different applications and scanners. This allows those different applications to talk to and interact with those different scanners without requiring the application writers and scanner manufactures to customize their application or drivers for each application-device combination.

Benefits of Windows Image Acquisition 2.0

WIA provides benefits to application developers, device manufacturers, and scanner users who need to interact with imaging hardware.

For Application Writers

• Windows runs a certification process for WIA drivers so WIA applications are guaranteed to be base-level compatible with all WIA-based scanners.
• WIA drivers are loaded in the WIA service process, thus providing a more stable driver environment.
• Applications can be initiated from the scanner scan button via push events supported by the WIA subsystem.
• The WIA includes a default segmentation filter that all drivers can take advantage of; this way, applications do not have to write code for multi-region scanning for purposes such as separating out a large number of photos spread over a flatbed scanner.

For Device Manufactures

• WIA driver certification process helps driver developers in establishing that their driver is WIA-compliant.
• WIA drivers can take advantage of a built-in segmentation filter, image processing filter and error handler, if they choose to do so.
• WIA-based scanners work right out of the box on Windows with Windows scanning applications such as Windows Fax and Scan and Paint.
• WIA drivers offer better integration with Windows such as the full device experience.
• WindowsВ Vista release includes a WSD-WIA class driver that enables all devices compliant with Web Services for Scanner (WS-Scan) protocol to work with WIA applications without any additional driver or software.

For Scanner Users

• WIA-based scanners can be used from Windows applications such Windows Fax and Scan and Paint without the need for any additional software.
• WIA-based applications and scanners can also take advantage of WIA add-ons such as the segmentation filter which enables such features as processing a number of pictures on the scanner and scanning them all to individual files without user intervention.
• WIA-based devices offers a much better integration with other Windows features such as the Device Stage feature for WindowsВ 7.
• WIA provides a more robust, stable and reliable scanning experience by isolating the driver and the application.

Development of Windows Image Acquisition

The imaging architecture in WindowsВ 2000 and WindowsВ 95 or later consisted of a low-level hardware abstraction, Still Image Architecture (STI), and a high-level set of APIs known as TWAIN. In WindowsВ XP and WindowsВ MeВ WIA was introduced. WIA is an imaging architecture that builds on STI and does not require TWAIN, although TWAIN is still supported alongside WIA.

WIA 1.0 was introduced in WindowsВ Me and WindowsВ XP and supports scanners, digital cameras and digital video equipment. WIA 2.0 was released with WindowsВ Vista. WIA 2.0 is targeted towards scanners but continues to offer support for legacy WIA 1.0 applications and devices through a WIA 1.0 to WIA 2.0 compatibility layer provided by the WIA service. However, video content support was removed from WIA for WindowsВ Vista. We recommend Windows Portable Devices (WPD) API for digital cameras and digital video equipment in the future. WIA 1.0 as well as STI TWAIN drivers are still supported directly on WindowsВ Vista and WindowsВ 7 alongside native WIA 2.0 device drivers and imaging applications.

Overview of Windows Image Acquisition

WIA provides a framework that allows a device to present its unique capabilities to the operating system and allows imaging applications to invoke those unique capabilities.

The WIA platform includes a data acquisition protocol, a Device Driver Model and Interface (DDI), an API and a dedicated WIA service. The platform also includes a set of built-in kernel mode drivers that support communication with imaging devices locally connected through USB, serial/parallel, SCSI and FireWire interfaces. The WIA subsystem also includes a transparent compatibility layer which allows TWAIN compatible applications to employ and use WIA-driver-based devices.

Network connected imaging devices that support Web Services for Devices (WSD) protocol can also be used from WIA-compliant imaging applications on WindowsВ Vista and WindowsВ 7 out of the box via a WSD-WIA class driver that shipped as part of WindowsВ Vista. The class driver converts WIA calls to WSD calls and vice versa and makes already existing WIA applications work with WSD based scanners without any additional driver.

WIA drivers are made up of a user interface (UI) component and a core driver component, loaded into two different process spaces: UI in the application space and the driver core in the WIA service space. The service runs in Local System context in WindowsВ XP and runs in Local Service context starting with Windows ServerВ 2003 and WindowsВ Vista for enhanced security against buggy or malicious drivers.

The WIA API set exposes imaging applications to still image acquisition hardware functionality by providing support for:

• Enumeration of available image acquisition devices.
• Creating connections to multiple devices simultaneously.
• Querying properties of devices in a standard and expandable manner.
• Acquiring device data by using standard and high performance transfer mechanisms.
• Maintaining image properties across data transfers.
• Notification of device status and scan event handling.

Windows added scripting support to WIA by releasing the WIA Automation Library in 2002 that was incorporated in WindowsВ Vista as Windows Image Acquisition (WIA) Automation Layer and continues to be a part of WindowsВ 7. The WIA Automation Library provides end-to-end image acquisition capabilities to automation-enabled application development environments and programming languages such as Microsoft Visual Basic 6.0, Active Server Pages (ASP), VBScript and C#.

For WindowsВ 7, WIAВ APIs have additional support to complement the already existing push-scanning support.

• Auto-configured device initiated scanning with scan parameters configured at the scanner on the device front panel.
• Automatic source selection for device-initiated scan.

Facts about Windows Image Acquisition 2.0

• The data transfer mechanism in WIA 2.0 is stream based. The stream abstraction removes the distinction between different transfer types and also allows exchange of mutually agreed-upon metadata between device and application.
• WIA 2.0 subsystem also includes a basic image processing filter driver add-on that is optionally replaceable by the scanner driver, if the driver chooses to provide a customized image processing filter. The built-in filter enables post processing of images acquired through the scanner. Image processing filter also enables live software previews when small settings such as brightness and contrast are adjusted.
• The segmentation filter is another handy WIA component that can be replaced by a more customized filter by the scanner driver. The segmentation filter can be used for multi-region scanning. Multi-region scanning, as an example, allows an application to automatically detect different scan regions without any user intervention, such as identifying a bunch of photos lying randomly on the scanner flatbed.
• WIA 2.0 provides a replaceable/extensible error handler to gracefully handle, and possibly recover from, software, hardware and configuration errors and delays. The error handler is another WIA component that can be replaced with a more customized version by the scanner driver. This extension provides status and error messages during data acquisitions such as «Lamp warming up,» «Cover open,» «Paper jam,» and so on. This extension also allows cleaner support for «Cancel operations.»

Developer Audience

The WIA API is designed for use by C/C++ programmers. Familiarity with the WindowsВ GUI and Component Object Model (COM) interfaces is required.

For developers familiar with Microsoft Visual BasicВ 6.0, Active Server Pages (ASP), or scripting, WIA provides an automation layer for WindowsВ XPВ Service PackВ 1 (SP1) or later that builds upon and simplifies access to the foundation provided by C/C++. For information about the automation layer, see Windows Image Acquisition Automation Layer.

The WIA Automation Layer supersedes Windows Image Acquisition (WIA)В 1.0 scripting.

Run-Time Requirements

Applications that use the WIAВ API require WindowsВ XP or later.

WIA Topics

The WIA topics are organized as shown in the following table.

About Microsoft Windows Image Acquisition Automation Layer

The Windows Image Acquisition (WIA) Automation Layer is a high-quality, full-featured image manipulation component that provides end-to-end image processing capabilities for Microsoft Visual BasicВ 6.0, Active Server Pages (ASP), and scripting languages. The WIA Automation Layer exposes features in WindowsВ XPВ Service PackВ 1 (SP1) or later to make it easy to acquire images on digital cameras, scanners, or Web cameras, and to rotate, scale, and annotate your image files. Earlier versions of Windows are not supported.

Other new features include the ability to:

• Access the properties of image files.
• Read and write image files and their properties to databases.
• Modify pixels including alpha values.
• Write ASP pages that generate thumbnail images on the fly.
• Take pictures with your Web camera.
• Automatically download pictures from cameras as soon as they are connected, even if a script is not already running.

This overview includes the following topics.

Object Hierarchy

The WIA Automation Layer is broken down into two types of objects. The first type of object is a creatable object. This is an object that can be directly created by calling the Microsoft Visual Basic function CreateObject. In addition, three creatable objects (DeviceManager, CommonDialog, and VideoPreview) are also controls that can be dropped on a form in Visual Basic. The second type of object is the supporting object. This object is not directly creatable but instead is returned from properties or methods. For example, the Connect method on a DeviceInfo object returns a Device object.

The following object hierarchy diagrams show the relationship between objects, collections, and reused objects for both creatable and supporting objects. The hierarchy diagrams use these symbols.

As you can see in the previous illustrations, the WIA Automation Layer reuses objects wherever possible to reduce the number of different objects you need to learn to use. For example, the Device, DeviceInfo, Filter, FilterInfo, Item, and ImageFile objects all reuse the Properties collection to expose their properties. Once you learn how to use the Properties collection on one object you will be able to use it on all the others.

Notice the naming convention in which a collection of objects uses the plural of that object name. For example, a Filters collection holds Filter objects.

Accessing Imaging Devices

The DeviceManager object and, to a limited degree, the VideoPreview object are the primary ways to access Imaging Devices. The Device object represents an active connection to an Imaging Device. From the Device object you can access its properties, access the items that might be stored on it, transfer those items to files on the computer, and run commands that cause the Imaging Device to do something. For example, you could access a digital camera’s date and time, transfer all its pictures to your computer or cause it to take a picture. These actions can be done in one of two ways, programmatically without any user intervention, or using the CommonDialog object to present dialog boxes that enable the user to precisely control the actions.

Manipulating Image Files

Once you have transferred pictures to your computer, you can use the ImageFile object to access the pictures. You can display them on forms, return them as binary data in ASP pages, or access their properties. Many digital cameras store a number of detailed properties in their pictures, from useful information like the date the picture was taken and a thumbnail image to interesting technical details like the model of camera, the focal length, aperture setting, and shutter speed. For more information about detailed properties, see Display all ImageFile Properties and Display Detailed Image Information.

In order to protect the original pictures that represent digital memories, the ImageFile object cannot directly modify the pictures. You can, however, use an ImageProcess object and one or more Filter objects to create a modified copy of the picture. The WIA Automation Layer provides filters that rotate, flip, crop, scale, stamp, modify properties, modify the individual pixels or change the file format to Tagged Image File Format (TIFF), JPEG, Portable Network Graphics (PNG), bitmap (BMP), or Graphics Interchange Format (GIF). For more information about filters, see How To Use Filters.

Example Code

All reference pages in this documentation set include example code or a link to examples in the Overviews/Tutorials section that illustrate how to use the API. Begin by reading Getting Started with Samples. This topic has the template code for a variety of development environments into which you can paste the reference examples. Shared Samples includes a number of examples that are applicable to a variety of applications.

The following examples are complete samples that you do not need to paste into template code.