Building Driver Samples from the WDK

Help! The WPD driver sample doesn't build!  

Seeing this error while building the WPD driver samples using the Windows Driver Kit (WDK) build environment?

errors in directory c:\winddk\6000\src\umdf\wpd\wpdhelloworlddriver
NMAKE : fatal error U1073: don't know how to make 'C:\WinDDK\6000\lib\mfc\i386\atls.lib'
nmake.exe /nologo BUILDMSG=Stop. -i BUILD_PASS=PASS2 LINKONLY=1 NOPASS0=1 MAKEDLL=1 MAKEDIR_RELATIVE_TO_BASEDIR=src\umdf\wpd\wpdhelloworlddriver MAKEDIR_LOWERCASE=c:\winddk\6000\src\umdf\wpd\wpdhelloworlddriver failed - rc = 2

No worries, this is expected.  The is because the WDK build environment provides an older version of the ATL libraries than what WPD needs.  

To build the WPD driver samples provided with the WDK, follow these step-by-step instructions (MSDN library section: "Win32 and COM Development\Windows Driver Kit\Device and Driver Technology\Portable Devices\Windows Portable Devices\WPD Programming Guide\Familiarizing Yourself with the Sample Driver" ).

In a nutshell, you will need to install Visual Studio 2005, and reference the ATL libraries from there.  This build environment configuration only needs to be done the first time, and you'll be good to go for building our sample drivers.

Update [August 7, 2009]: The ATL-related build issues in the first section have finally been
addressed in the WDK for Windows 7 (a.k.a WDK 7.0.0).  You can get the
latest WDK here. To build the drivers, simply type "build -cZ" or "bcz" from the WDK command window for the target OS of your choice. See this WDK 7.0.0 RTM release note for the complete list of build environments and target operating systems applicable to the WPD driver samples.

 

Which sample should I use?  

To get a running start on writing a WPD driver, we recommend using the WpdHelloWorldDriver as a template, it covers some basic driver functionality such as retrieving properties, enumeration, and reporting device capabilities.    

More advanced driver functionality is demonstrated by the WpdWudfSampleDriver (a.k.a. the WPD Comprehensive Sample Driver), such as driver-initiated events, object management, and content transfer.  On Windows Vista, this sample driver is also visible from Windows Image Acquisition (WIA) camera applications (using the WPD-WIA compatibility layer).  More on WIA in future posts....

To develop a WPD driver that enumerates in Windows Media Player 11, you can start with the WpdWudfSampleDriver with a few extra modifications.

Update [August 7, 2009]:   The WDK 7.0.0 now contains an updated WpdWudfSampleDriver sample that supports enumeration in Windows Media Player.

 

Known issues in the sample drivers

Both sample drivers do not enumerate in Windows Media Device Manager (WMDM) applications (such as Windows Media Player) by default.   See the previous section for an example of enabling that with the comprehensive sample driver.

Both sample drivers install as "root enumerated" devices, i.e. they install using the Add Legacy Hardware option.  Hence, they are shown as always connected in Device Manager.   While this provides an easy way to install and test a device driver, this means that certain Plug-and-Play functionality may not be available (such as Autoplay in Windows Vista).   To enable Autoplay, one way is to install and configure a bus driver for your device (for a sample, refer to the Toaster Bus Driver in the WDK).

 

What tools can I use?

During development, we highly recommend using the WpdInfo GUI tool, which uses the WPD API to access your driver.  You can query driver capabilities, browse the object tree, send raw WPD commands, update properties, etc.  

Other useful WPD tools:

All these tools are developed in-house, and used extensively by us for development and troubleshooting. :)

Basic driver requirements

This whitepaper lists basic requirements that your driver should satisfy to work well with most WPD applications, such as the required properties that a particular object content type should support.   These requirements are also implemented as logo tests for the Windows Vista Cellular Handset Basic Logo for Windows Logo Program v3, but are generic enough to apply to any WPD driver.

 

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