Windows Portable Devices Team Blog : WIA

Windows 7 Driver Samples

wpdblog — Sat, 19 Sep 2009 00:24:00 GMT

The Windows Portable Devices Driver Kit in the Windows Driver Kit (WDK) comes bundled with five WPD sample drivers. Two of these drivers, WpdHelloWorldDriver and WpdWudfSampleDriver, were available in previous versions of the WDK. The remaining three drivers, WpdBasicHardwareDriver, WpdServiceSampleDriver, and WpdMultiTransportDriver, are new additions in the Windows 7 WDK. Together, these samples illustrate how to build a WPD driver for the different scenarios that WPD enables, including interaction with basic hardware, media synchronization, device services, and multi-transport.

We had mentioned these samples in a previous post on the Windows 7 Portable Devices Development Kits. The purpose of this post is to spend some time covering each sample in greater detail. Hopefully, this will help driver developers navigate the various WPD samples, and figure out which sample(s) best fit their driver requirements.

The following sections will describe each driver, the WPD commands that each implements, and the operating systems that each supports. In addition, we will provide the links to instructions for building and installing.

WpdHelloWorldDriver

Of all the sample drivers, the WpdHelloWorldDriver is the most simple. This driver supports and emulates four objects in software: a device object, a storage object, a folder object, and a text file object. WpdHelloWorldDriver was designed to provide the most basic scaffolding or skeleton required for developing a WPD driver; similar to the canonical "Hello World" program used for introducing a framework or programming language. If you are new to WPD driver development and need a kick start, we recommend starting with this sample.

The WpdHelloWorldDriver sample supports 22 commands. These commands cover the basic functionality that enables a WPD device to be browsed in Windows Explorer as a read-only device. The commands fall into four categories: object enumeration, object properties, object resources, and device capabilities. Like all WPD drivers, when this driver is installed and a WPD application calls a method to enumerate objects, set a property, open a resource, and so on, the driver will invoke a corresponding command handler for one of these supported commands.

This driver is supported on Windows XP, Windows Vista (x86, amd64), and Windows 7 (x86, amd64).

For instructions on how to build and install this driver, see: http://msdn.microsoft.com/en-us/library/dd573842.aspx

WpdBasicHardwareDriver

The WpdBasicHardwareDriver sample is new for Windows 7 and builds upon the WpdHelloWorldDriver. This sample stands apart from the other WPD samples in that it accesses real device hardware instead of emulating a software-only device. We provided this sample to demonstrate how a basic WPD driver can be built to interact with simple devices.

For our demonstration device, we targetted a “hobbyist” microcontroller that reads data from a variety of sensors. The sensors include: a 2-axis accelerometer, a 3-axis accelerometer, a temperature/humidity sensor, a pressure sensor, a distance sensor, a passive infrared sensor, a compass, a vibration sensor, and a light sensor. These sensor devices are controlled by a Parallax BS2 microcontroller attached to the PC via an RS232 port. In addition to the driver source code, we also provided some sample firmware code that retrieves the sensor data and sends them over the serial port to the PC.

The WpdBasicHardwareDriver sample supports an even smaller set of commands than the WpdHelloWorldDriver. In the interests of only providing the code that is necessary to demontrate the concepts, we removed some commands for object resources because the WpdBasicHardwareDriver does not need to support reading of files from the device. The remaining commands fall under these three categories: object enumeration, object properties, and device capabilities. To see this driver in action, you can use WpdMon to view the events corresponding to each sensor reading.

This sample also showcases how WPP Software Tracing can be used for error checking macros. A while ago, we had a post that describes how you can migrate your existing WPD driver from OutputDebugString to WPP Tracing. The WpdBasicHardwareDriver is now bundled with the macros.

This driver is supported on Windows XP, Windows Vista (x86, amd64), and Windows 7 (x86, amd64). If you plan to develop drivers that integrate sensors with Windows 7, we recommend using the Sensor API and Sensor Driver Model. If you need to develop drivers to integrate sensors with Windows Vista or Windows XP, WPD provides a viable solution.

For instructions on how to build and install this driver, see: http://msdn.microsoft.com/en-us/library/dd573829.aspx

WpdWudfSampleDriver

The WpdWudfSampleDriver is a comprehensive driver sample that demonstrates using the WPD DDI for media transfer scenarios. In addition to file browsing and transfer via Windows Explorer, this sample contains additional functionality that supports media synchronization with Windows Media Device Manager (WMDM) applications (e.g. Windows Media Player), and photo acquisition with Windows Image Acquisition (WIA) applications (e.g. Paint). All interactions with hardware are emulated in software (meaning that this driver talks to a "fake" device).

To enable the media transfer scenarios, the WpdWudfSampleDriver sample had to support a large set of commands, including the commands supported by the WpdHelloWorldDriver. These commands can be divided into eight categories: object enumeration, object management, object properties, bulk properties, object resources, capabilities, and storage.

In this version, we fixed a compatibility issue in the Vista WDK version of the sample driver code that prevents it from being properly enumerated in Windows Media Player.

This driver is supported on Windows XP, Windows Vista (x86, amd64), and Windows 7 (x86, amd64).

For instructions on how to build and install this driver, see: http://msdn.microsoft.com/en-us/library/dd573843.aspx

WpdMultiTransportDriver

The WpdMultiTransportDriver builds upon the WpdHelloWorldDriver and demonstrates how driver developers can take advantage of the Windows 7 support for Multiple Transports. For an overview on what multi transport is all about, check out our post two weeks ago about Multi-Transport support in Windows 7.

This driver emulates a transport driver and illustrates how to set the relevant multi-transport settings and generate the Functional Unique Identifier (FUID) during device arrival, in order to perform handshaking with the WPD Composite Driver. In addition, this sample supports multiple Windows Driver Framework I/O queues, where all the other WPD samples only support a single I/O queue.

Other than the multi-transport support, the WpdMultiTransportDriver sample is virtually identical as the WpdHelloWorldDriver, and supports the same set of WPD commands. A quick way to zero-in on the code modifications needed to support Multi-Transport is to use your favorite diff program to compare the WpdHelloWorldDriver and WpdMultiTransportDriver source folders.

Because multi-transport support is a new feature in Windows 7, this sample driver is only supported on Windows 7 (x86, amd64).

For instructions on how to build and install this driver, see: http://msdn.microsoft.com/en-us/library/dd573843.aspx

WpdServiceSampleDriver

The WpdServiceSampleDriver demonstrates how a driver can support Windows 7 Device Services. We covered an introduction to Device Services in another recent post. This driver emulates a basic Contacts device service that uses the Full Enumeration Sync device service. To support Device Services, this driver implements device services-specific WPD command sets: WPD_CATEGORY_SERVICE_COMMON, WPD_CATEGORY_SERVICE_CAPABILITIES, and WPD_CATEGORY_SERVICE_METHODS. These commands would allow an application to determine the capabilities of a service and invoke methods supported by the service. This driver also uses the new functionality in the WPD Class Extension (IPortableDeviceClassExtension) to register and unregister the Contacts device service interface. Last but not the least, to support object and property management, this sample also supports commands for object enumeration, object properties, bulk properties, object resources, and device capabilities.

The WpdServiceSampleDriver does not emulate a Media Transfer Protocol (MTP) device. Like most of the other WPD samples, it simulates a software-only device that is not tied to a specific protocol or transport. If you are looking to build firmware for an MTP device that supports device services, you should start with the Device Enabling Kit.

Device Services is a new feature we introduced in Windows 7, therefore this sample is only supported on Windows 7 (x86, amd64).

For instructions on how to build and install this driver, see: http://msdn.microsoft.com/en-us/library/dd573846.aspx

This posting is provided "AS IS" with no warranties and confers no rights.

WIA Camera Support in Windows Vista (Part 2 of 2)

wpdblog — Tue, 13 Feb 2007 21:33:00 GMT

In the previous post, we gave an overview of the WIA-WPD Compatibility Layer and how WIA Applications can register for WIA_EVENT_DEVICE_CONNECTED events.

In this post, we will cover a more advanced topic: customization for PTP and MTP devices. The WIA-WPD Compatibility Layer supports basic extensibility for custom WIA events and WIA properties. These events and properties were provided in the PTP WIA class driver that shipped with Windows XP.

Adding Custom PTP/MTP WIA Event Codes

To specify a list of supported PTP/MTP event codes the 'WiaEventCodes' entry should be provided.

The following example shows 3 custom event codes being reported.

HKR,,"WiaEventCodes",”0x0001,0x0002,0x0003”

For each event code specified in the 'WiaEventCodes' entry, a corresponding 'WiaEventCodeXXX' entry must exist that specifies the name of the event and the GUID to use when reporting the event to WIA applications. The entry should be constructed using the prefix ‘WiaEventCode + the event code specified in WiaEventCodes entry’. If the WiaEventCodeXXX entry is missing, the event will not be reported to WIA applications.

HKR,,"WiaEventCode0x0001”,”{20179E3D-139C-40D3-A0CA-962B33D67EE3},My Custom Event”
HKR,,"WiaEventCode0x0002”,”{259A62CF-D8FE-44D0-A747-B14F54A02133},My Amazing Event”
HKR,,"WiaEventCode0x0003”,”{639F80C6-94D1-48E2-9D8E-6D0F12237E48},My Super Event”

Adding Custom PTP/WIA Property Codes

To specify a list of supported PTP/MTP property codes the ‘WiaPropertyCodes’ entry should be provided. WIA properties will only appear on the root item. These properties are commonly used to control/program the device.

The following example shows 3 custom property codes being reported.

HKR,,"WiaPropertyCodes",”0x0001,0x0002,0x0003”

For each property code specified in the ‘WiaPropertyCodes’ entry, a corresponding ‘WiaPropertyCodeXXX’ entry must exist that specifies the name of the property and the WIA property code to use when reporting the property to WIA applications. The entry should be constructed using the prefix ‘WiaPropertyCode + the property code specified in WiaPropertyCodes entry’. If the WiaPropertyCodeXXX entry is missing, the event will not be reported to WIA applications.

HKR,,"WiaPropertyCode0x0001”,”My Custom Device Property”
HKR,,"WiaPropertyCode0x0002”,”My Amazing Device Property”
HKR,,"WiaPropertyCode0x0003”,”My Super Device Property”

Sending PTP Custom Commands through WIA

PTP extension commands can be sent to the vendor's driver using IWiaItemExtras::Escape. In Windows Vista, the WIA-WPD Compatibility Layer repackages PTP extension commands sent using this method into WPD MTP/PTP extension commands, which are dispatched to the WPD MTP class driver. This mechanism exists to support legacy WIA vendor applications that relied on custom PTP commands from Windows XP.

Sending MTP Custom Commands through WPD

WPD supports sending of custom MTP commands to the MTP driver using the IPortableDevice::SendCommand API. For a step-by-step description, visit DimeBy8's excellent post here.

WIA to WPD Content Type and Format Mapping

The following table maps WIA Item Types to the WPD_OBJECT_CONTENT_TYPE.

In addition to video and image content, the WIA-WPD Compatiliby Layer supports thumbnails and audio annotations for objects that have them. Any data objects that do not fall under these categories (e.g. music files) will not appear in WIA applications.

WPD Object	WPD Content Type	WIA Item	WIA Item Type
Device object	N/A	Root item	(WiaItemTypeFolder \| WiaItemTypeDevice \| WiaItemTypeRoot)
Folder object	WPD_CONTENT_TYPE_FOLDER	Folder Item	WiaItemTypeFolder
Functional Object	WPD_CONTENT_TYPE_FUNCTIONAL_OBJECT	Folder Item	WiaItemTypeFolder
Image Object	WPD_CONTENT_TYPE_IMAGE	Image Item	(WiaItemTypeImage \| WiaItemTypeFile \| WiaItemTypeTransfer)
Video Object	WPD_CONTENT_TYPE_VIDEO	Video Item	(WiaItemTypeVideo \| WiaItemTypeFile \| WiaItemTypeTransfer)
Audio Object (used for annotations)	WPD_CONTENT_TYPE_AUDIO	Audio Item	(WiaItemTypeAudio \| WiaItemTypeFile \| WiaItemTypeTransfer)
Other objects	WPD_CONTENT_TYPE_XXXX	N/A (These are ignored)	N/A (These are ignored)

The following table maps the WIA_IPA_Format property to the WPD_OBJECT_FORMAT property:

WIA_IPA_FORMAT

The formats will be mapped as follows:

WiaImgFmt_EXIF	WPD_OBJECT_FORMAT_EXIF
WiaImgFmt_JPEG	WPD_OBJECT_FORMAT_JFIF
WiaImgFmt_PNG	WPD_OBJECT_FORMAT_PNG
WiaImgFmt_GIF	WPD_OBJECT_FORMAT_GIF
WiaImgFmt_TIFF	WPD_OBJECT_FORMAT_TIFF
WiaAudFmt_WAV	WPD_OBJECT_FORMAT_WAVE
WiaAudFmt_MP3	WPD_OBJECT_FORMAT_MP3
WiaAudFmt_AIFF	WPD_OBJECT_FORMAT_AIFF
WiaAudFmt_WMA	WPD_OBJECT_FORMAT_WMA
WiaImgFmt_MPG	WPD_OBJECT_FORMAT_MPEG
WiaImgFmt_AVI	WPD_OBJECT_FORMAT_AVI
WiaImgFmt_ASF	WPD_OBJECT_FORMAT_ASF

Configuration of the WIA-WPD Compatibility Layer

The following section lists the customization options in the WIA-WPD Compatibility Layer that can be disabled/enabled by the device's INF [AddReg] section:

Report EXIF Image Format as JPG

Some WIA applications expect the EXIF image format to be reported as WiaImgFmt_JPG and not WiaImgFmt_EXIF. To "opt-in" for this functionality, vendors can add the following to your device's INF:

HKR,,"ReportJPGFormatForEXIF",0x10001,1

WIA Item Tree Behavior for DCF

If the WIA-WPD Compatibility layer encounters a storage that supports DCF, it will ‘shift’ the WIA item tree contents closer to the root item so items are easily found. This will reduce the number of folder levels an application or user will have to navigate to get to the image or video content stored on the device. This functionality can be disabled by adding the following to your device’s .INF [AddReg] section.

HKR,,"DisableDCFSpecialProcessing",0x10001,1

This posting is provided "AS IS" with no warranties, and confers no rights.

WIA Camera Support in Windows Vista (Part 1 of 2)

wpdblog — Tue, 13 Feb 2007 11:23:00 GMT

In this two-part post, we will cover WIA support for cameras on Windows Vista, and the migration from WIA to WPD for richer applications.

WIA-WPD Compatibility Layer

On Windows XP, Picture Transfer Protocol (PTP) cameras are accessible through the WIndows Image Acquisition (WIA) infrastructure. This is still supported on Windows Vista through the WIA-WPD Compatibility Layer (PortableDeviceWiaCompat.dll). This component is a WIA mini-driver that communicates to the inbox Media Transfer Protocol (MTP) class driver using the WPD API.

The following classes of devices have the WIA-WPD Compatibility Layer enabled:

1. PTP Cameras

2. MTP devices that report WPD_DEVICE_TYPE_CAMERA (subcomp = 2) or WPD_DEVICE_TYPE_VIDEO (subcomp = 6)

3. WPD devices that support WPD_CONTENT_TYPE_VIDEO or WPD_CONTENT_TYPE_IMAGE, and with the lowest bit set in the EnableLegacySupport entry under Device Parameters. This can be set in the driver INF:

HKR,,"EnableLegacySupport",0x10001,1

WIA Event Registration for Cameras

On Windows Vista, WIA imaging applications communicate to PTP cameras via the WPD-WIA Compatibility Layer and the Media Transfer Protocol (MTP) class driver. Windows Autoplay is supported, third party applications can register for WIA device-connected events and appear in the autoplay dialog. Note that some third-party WIA applications may require Elevation ("Run as Administrator") at first launch to in order to successfully register for WIA events.

1. Only Global WIA Event Registration for WIA_EVENT_DEVICE_CONNECTED is supported. Any WIA application that registers for this event will be listed in the Windows Autoplay dialog when any WIA-compatible PTP camera is connected.

2. Supported registration mechanisms: STI Proxy registration (IStillImage::RegisterLaunchApplication), WIA CLSID registration (IWiaDevMgr::RegisterEventCallbackCLSID), and WIA Program registration (IWiaDevMgr::RegisterEventCallbackProgram).

Custom Vendor Events

To enable Device-Specific WIA Event Registration for custom vendor events, there is an "opt-in" mechanism. There are 2 steps to this:

Step 1: The vendor camera driver INF will need to add the UseWiaAutoPlay setting in the Device Parameters section in the registry. This is a DWORD setting. If set to 1, the WPD-WIA Compatiliby Layer will mark "device connected" and custom vendor events as "action events." If unset, the default value is 0 (WIA autoplay is disabled).

HKR,,"UseWiaAutoPlay",0x10001,1

Step 2: The vendor's application calls the IWiaDevMgr APIs to create a Device-specific WIA event registration for their custom WIA event.

The overall effect of enabling device-specific registration is the WIA Autoplay dialog will appear for the custom event. This XP-style dialog is implemented by the WIA Service. It is recommended that applications only register via Windows Autoplay or WIA Autoplay, but not both. Windows Autoplay registration is preferred.

Image and Video Acquisition

On Windows Vista, the camera image import functionality of the Scanner and Camera Wizard is replaced by the Photo Acquisition Wizard and the Windows Photo Gallery. This is also known as the "Importing Pictures and Videos" dialog.

The Photo Acquisition wizard communciates to PTP cameras using WPD APIs (more specifically, it uses the WPD Namespace Extension). It does not use the WIA APIs.

Video Content Support

Video content support is removed from WIA for Windows Vista. The effect is video content on your device will not appear in WIA applications running on Windows Vista.

To access video content from your device, we recommend migrating your applciation to use the WPD API. WPD provides broader content coverage (supports both video and image content) on Windows Vista for camera devices. For instance, the Vista Photo Acquisition Wizard uses WPD to retrieve pictures and video from PTP devices.

For ease of migration, there is usually a straighforward correlation from WIA metadata to WPD object properties. For example, WiaImgFmt_AVI corresponds to WPD_CONTENT_TYPE_VIDEO and WPD_OBJECT_FORMAT_AVI. For more details, refer to the WPD video properties and video format GUIDs on MSDN.

Next Post...

Watch the next post for more details on custom PTP vendor commands through the WIA Escape mechanism, custom WIA property and event codes.

This posting is provided "AS IS" with no warranties, and confers no rights.