Windows Portable Devices Team Blog : WDK

Sensors and Windows

wpdblog — Thu, 17 Dec 2009 20:03:00 GMT

Prior to the introduction of WPD, developers wrote a significant amount of code to integrate data from sensors into their Windows applications. But, with the release of WPD, it was possible to create a driver that handled communications between the operating system and the remote device. And, once the driver was written, a developer could write an application with a minimal code footprint—200 lines or less—to retrieve sensor data. For an example, refer to the downloadable whitepaper and code at: http://wpdtempsensor.codeplex.com/. (For an example WPD driver, refer to the WpdBasicHardwareDriver that ships in the Windows Driver Kit.)

For Windows 7, Microsoft introduced the Sensors and Location platform. This platform includes both a driver model for IHVs and an API for application developers. Microsoft recently released a sample driver, sample firmware, and a sample application on the MSDN Code Gallery to demonstrate the use of this new platform. See: http://code.msdn.microsoft.com/motionsensor. This sample, like the WPD sample above, interacts with the Parallax BS2 microcontroller; and, it’s intended as an enhancement (or replacement) of the WPD sample.

So, you may be wondering: “When should I use WPD to support my sensors and when should I use the Sensors and Location Platform?” Good question. The answer is straightforward. If you’re targeting Microsoft Windows XP or Microsoft Windows Vista: Use WPD. If you’re targeting Windows 7, use the new Sensors and Location Platform.

One of the key enhancements of the Sensor Platform is its class extension. The sample sensor driver uses the extension to fire both state-change events and data-update events. So, if the sensor is powered-down or disconnected, the driver calls a single class extension method: PostStateChange. And, each time the sensor sends new data, the driver calls the class extension’s PostEvent method. The class extension, and these methods, make it very easy to support a “push” model for applications where the app registers to receive event notifications.

Another enhancement is the platform’s “organization” of the sensor universe. The platform identifies specific categories and subcategories of sensors. So, for example, an application can retrieve all of the connected Passive Infrared sensors by invoking GetSensorsByCategory and specifying “BioMetric” as the specific category of interest. (The application developer doesn’t need to look for an identifier supplied by a hardware vendor for a particular passive infrared sensor.)

By the way, if you were to compare the source code for the WpdBasicHardwareDriver and the SensorParallaxSample driver, you’d notice a number of similarities. This is by-design because the WPD and Sensor platform drivers are built on top of the User Mode Driver Framework (WUDF). The code which configures the serial port, the code that creates the I/O Target, and the code that parses the packets returned by the sensor originated in the WpdBasicHardwareDriver and was ported to the Sensors and Location Platform.

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

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.

Driver Dev Guide: Client Context Management

wpdblog — Wed, 06 Jun 2007 02:41:00 GMT

Client Context Management in WPD Drivers

A WPD driver provides the communication channel between applications and the physical device. There can be multiple WPD applications running at any time, and the driver needs to handle requests from different clients and identify the clients based on the queued requests. In other words, the driver needs an efficient and easy way to store client data on a per-connection basis, and retrieve the data per request. Fortunately, UMDF supports context areas, a generic mechanism to save data with a framework object. A WPD driver can allocate a data structure or object to hold the data, assign it to the framework object's context area, and retrieve the context at a later time. The appropriate per-connection WDF framework object to use is the WDF file object.

Step 1: Assigning the Context

The driver assigns the context when the client opens a connection to it. When a WPD application calls IPortableDevice::Open, the WPD API creates a handle to the driver using Win32 CreateFile. Under the hood, UMDF initializes an IWDFFile object and forwards it, along with the Creation request, to the driver's IQueueCallbackCreate::OnCreateFile method. The IWDFFile in this case represents a Win32 HANDLE that is used for subsequent communication from this client to the driver.

A example of a CreateFile callback implementation is WpdWudfSampleDriver's CQueue::OnCreateFile. A driver-specific ContextMap COM object is used to store client data (application name, version, in-progress enumeration and resource contexts, etc). Note that the use of COM objects as context data is NOT required by UMDF - UMDF sees the context data as an opaque PVOID. If you are using a COM object for storing context data, your driver needs to maintain the reference count for that COM object, and ensure that its resources are freed in the appropriate cleanup methods.

To save context data, the driver initializes a new ContextMap object, and calls IWDFObject::AssignContext for the IWDFFile object handed in by UMDF. The parameters for AssignContext are the pointers to an IObjectCleanup object [containing the context cleanup code], and the newly-created ContextMap [containing the data to store]. IObjectCleanup::OnCleanup will be called when the file object is destroyed during CloseHandle. See "Step 3" for further details on how to implement OnCleanup.

In addition, only one context can be assigned to the file object (or any UMDF framework object). Subsequent calls to AssignContext will fail if a context has already been assigned. To add/remove client-specific data dynamically, one way is to implement a mapping object for managing the data (e.g. WpdWudfSampleDriver's ContextMap object), and assign a pointer to that mapping object as file object's context.

Step 2: Retrieving and Saving Context Information

To access the client data during requests, the WPD driver gets the context from the IWDFFile object.

The sequence is:

Call IWDFIoRequest::GetFileObject to get the IWDFFile object.
Call IWDFObject::RetrieveContext on the IWDFFile object to access the context area. In the sample driver, this will be the pointer to the ContextMap object that was created in CQueue::OnCreateFile during IPortableDevice::Open.
Add/remove data to the ContextMap object directly when processing the WPD commands. Each client connection (i.e. IPortableDevice::Open) will have its own IWDFFile object and ContextMap object.

Example code from WpdWudfSampleDriver:

CQueue::OnDeviceIoControl - Retrieving the context map from the WDF request's file object
WpdBaseDriver::OnSaveClientInfo - Adding client information to the context map when processing the WPD_COMMAND_COMMON_SAVE_CLIENT_INFORMATION command

Step 3: Cleaning up the Context

When the client application calls IPortableDevice::Close, the WPD API will in turn call CloseHandle on the Win32 handle associated with that open connection. Before destroying the IWDFFile object in response to the CloseHandle, UMDF calls the file object's IObjectCleanup::OnCleanup method that the driver passed into AssignContext during OnCreateFile.

An example implementation of the IQueueCleanup callback is WpdWudfSampleDriver's CQueue::OnCleanup. This method retrieves the ContextMap stored in the IWDFObject object (in this case, the instance of IWDFFile from OnCreateFile) and frees the allocated memory, including the objects that the ContextMap holds. To avoid memory leaks, ensure that the objects are properly cleaned up, and (if applicable) decrement the reference count.

References

A great WDF book is Developing Drivers with WDF by Orwick/Smith. Chapter 5 (pages 124-125) covers techniques for object-specific context data storage using UMDF. The WpdWudfSampleDriver sample code is available in the Windows Driver Kit.

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

Which version of the WDK do I download?

wpdblog — Wed, 16 May 2007 22:24:00 GMT

To develop WPD drivers for Vista SP1:

- Build them using the Vista WDK (version 6000) or from the Longhorn Server Beta 3 WDK build environments.

- WPD drivers built using Longhorn Server WDK Beta 3 will not run on Vista RTM or Windows XP, this is because the version 1.7 WDF Co-installer shipped in the Beta 3 release does not support downlevel operating systems (Vista RTM, XP, Server 2003).

To develop WPD drivers for Vista RTM:

- Build them from the Vista WDK (version 6000)

- The drivers can run on Windows XP with INF changes and Windows Media Player 11 or Format SDK Redistributable 11 installed

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

Getting a WPD Sample Driver working with Windows Media Player 11

wpdblog — Tue, 08 May 2007 22:25:00 GMT

We mentioned in a previous post that the WPD sample drivers are not designed to enumerate in Windows Media Player 11 (WMP11) due to compatibility issues. This post covers the changes needed to enable the WPD Comprehensive Sample Driver (WpdWudfSampleDriver) to appear as a portable device in WMP11 and simulate a sync.

The WpdWudfSampleDriver is featured in this post because it contains a lot more functionality than the WpdHelloWorldDriver, and is closer to meeting the requirements of WMP11 than the WpdHelloWorldDriver. More specifically, the WpdWudfSampleDriver simulates the following additional functionality:

1. Creating and transferring data objects on the device.

2. Rendering information profiles for creating content to the device.

3. Setting properties on objects.

4. Posting device events.

5. Bulk property operations.

In the list above, items 1-3 provide basic compatibility with WMP11. Device events are a "good to have" feature, for application responsiveness to changes in the device content and device state. Bulk property operations are optional, but also provide improved application responsiveness - multiple properties for objects can be sent in batches, instead of multiple per-object "GetProperty" requests.

During sync, the WpdWudfSampleDriver simulates file and folder creation by allowing content to be created and transferred to the device. The data is not persisted by the driver, and will exist as long as the sample driver is still loaded. Once the driver is disconnected (e.g. disable in Device Manager), the data goes away. Typically, your WPD driver would be sending this data to your physical device and persisting it there, so this should not be an issue for real devices.

Modifications to the WpdWudfSampleDriver to Enumerate and Sync in WMP11

Some of the changes below involve updating the fake contents on the device for illustration. The same property requirements will apply for your own driver or device objects.

1. Add WPD_DEVICE_SYNC_PARTNER as a writable property for the "Device" object. This is needed by WMP11 for setting up a sync partnership with the device.

In deviceobjectfakecontent.h:

class DeviceObjectFakeContent : public FakeContent
{
  ...

    virtual HRESULT GetAllValues(
        IPortableDeviceValues*  pValues)
    {
	...
        // Add WPD_DEVICE_SYNC_PARTNER
        hrSetValue = pValues->SetStringValue(WPD_DEVICE_SYNC_PARTNER, SyncPartner);
        if (hrSetValue != S_OK)
        {
            CHECK_HR(hrSetValue, "Failed to set WPD_DEVICE_SYNC_PARTNER");
            return hrSetValue;
        }
        ...
    }	

    virtual HRESULT WriteValue(
        const PROPERTYKEY& key,
        const PROPVARIANT& Value)
    {
        ...
        else if(IsEqualPropertyKey(key, WPD_DEVICE_SYNC_PARTNER))
        {
            if (Value.vt == VT_LPWSTR)
            {
               SyncPartner = Value.pwszVal;
            }
            else
            {
                hr = E_INVALIDARG;
                CHECK_HR(hr, "Failed to set WPD_DEVICE_SYNC_PARTNER because type was not VT_LPWSTR");
            }
        }
	...
    }
   ...

private:
    ...
    CAtlStringW SyncPartner;
};

2. Add WPD_OBJECT_NON_CONSUMABLE as a writable property for all objects. This allows simulating the saving of sync settings into a file on the device called WMPInfo.xml. This file is created by WMP11 on the device and marked as "Non Consumable," with Format = WPD_OBJECT_FORMAT_UNSPECIFIED and Content Type = WPD_CONTENT_TYPE_UNSPECIFIED.

In fakecontent.h:

class FakeContent
{

    virtual HRESULT WriteValue(
        const PROPERTYKEY& key,
        const PROPVARIANT& Value)
    {
        ...
        else if (IsEqualPropertyKey(key, WPD_OBJECT_NON_CONSUMABLE))
        {
            if(Value.vt == VT_BOOL)
            {
                NonConsumable = Value.boolVal;
            }
            else
            {
                hr = E_INVALIDARG;
                CHECK_HR(hr, "Failed to set WPD_OBJECT_NON_CONSUMABLE because type was not VT_BOOL");
            }
        }
        ...
    }
   ...
};

3. Add support for WPD_OBJECT_ORIGINAL_FILE_NAME in for all objects. This involves updating the support properties and fixed attributes tables, and overriding FakeGenericFileContent::GetAllValues() to return this property in addition to the standard properties.

In helpers.cpp:

const PROPERTYKEY* g_SupportedPropertiesForFakeContentFormat[] =
{
    ...
    &WPD_OBJECT_ORIGINAL_FILE_NAME,
    ...
};

KeyAndAttributesEntry g_FixedAttributesTable [] =
{     
    ...
    {&FakeContent_Format, &WPD_OBJECT_ORIGINAL_FILE_NAME, 
         UnspecifiedForm_CanRead_CannotWrite_CannotDelete_Fast},
    // Properties for the device object
    ...
}

In fakecontent.h:

class FakeGenericFileContent : public FakeContent
{
public:

    virtual HRESULT GetAllValues(
        IPortableDeviceValues*  pStore)
    {
        HRESULT             hr          = S_OK;
        PropVariantWrapper  pvValue;

        // Call the base class to fill in the standard properties
        hr = FakeContent::GetAllValues(pStore);
        if (FAILED(hr))
        {
            CHECK_HR(hr, "Failed to get basic property set");
            return hr;
        }

        // Add WPD_OBJECT_ORIGINAL_FILE_NAME
        pvValue = FileName;
        hr = pStore->SetValue(WPD_OBJECT_ORIGINAL_FILE_NAME, &pvValue);
        if (hr != S_OK)
        {
            CHECK_HR(hr, ("Failed to set WPD_OBJECT_ORIGINAL_FILE_NAME"));
            return hr;
        }

        return hr;
    }
    ...
};

4. Add support for creation of folders. These folders need to support WPD_OBJECT_ORIGINAL_FILE_NAME. This allows WMP11 to create the "Album", "Artist" folders on the device during the sync operation.

One way to do this is to define a new FakeFolderContent class that inherits from FakeContent, and return WPD_OBJECT_ORIGINAL_FILE_NAME in FakeFolderContent::GetAllValues().

Added new header file: fakefoldercontent.h

class FakeFolderContent : public FakeContent
{
public:
    ...

    virtual HRESULT GetAllValues(
        IPortableDeviceValues*  pStore)
    {
        HRESULT             hr          = S_OK;
        PropVariantWrapper  pvValue;

        // Call the base class to fill in the standard properties
        hr = FakeContent::GetAllValues(pStore);
        if (FAILED(hr))
        {
            CHECK_HR(hr, "Failed to get basic property set");
            return hr;
        }

        // Add WPD_OBJECT_ORIGINAL_FILE_NAME
        pvValue = FileName;
        hr = pStore->SetValue(WPD_OBJECT_ORIGINAL_FILE_NAME, &pvValue);
        if (hr != S_OK)
        {
            CHECK_HR(hr, ("Failed to set WPD_OBJECT_ORIGINAL_FILE_NAME"));
            return hr;
        }

        return hr;
    }
};

All top level folders (e.g. Video Folder, Music Folder) in the sample driver can then initialize a FakeFolderContent instead of a FakeContent. The value of WPD_OBJECT_ORIGINAL_FILE_NAME is usually the same as WPD_OBJECT_NAME. Assign the value of FileName in FakeDevice::CreateContentObject() whenever an object is created, so that it will be returned during subsequent "Get Property" queries.

In fakedevice.h:

class FakeDevice
{
    ...   
    HRESULT InitializeContent(
        IPortableDeviceClassExtension *pPortableDeviceClassExtension)
    {
        ...
        
        // Add Media folder: Music folder
        pContent = new FakeFolderContent();
        if (pContent)
        {
            ...
            pContent->FileName  = pContent->Name;  // Set Original File Name property
            ...
        }

        // Repeat for other types of folders declared here
        ...

        // Add generic file content objects to storage 1
        for(DWORD dwIndex = 0; dwIndex < NUM_VERTICAL_OBJECTS; dwIndex++)
        {
            m_dwLastObjectID++;

            pContent = new FakeGenericFileContent();
            if (pContent)
            {
                ...
                pContent->FileName = pContent->Name;
                ...
            }
        }
        ...
    }

    HRESULT CreateContentObject(
        LPCWSTR                 pszObjectName,
        LPCWSTR                 pszParentID,
        REFGUID                 guidContentType,
        IPortableDeviceValues*  pObjectProperties,
        FakeContent**           ppContent)
    {
        ...
        if(guidContentType == WPD_CONTENT_TYPE_FOLDER)
        {
            FakeContent* pContent = NULL;

            pContent = new FakeContent();
            if (pContent)
            {
                ...
                pContent->FileName = pszObjectName;
                ...
            }
        }
   }
   ...
};

5. Modify WpdWudfSampleDriver.INF to set EnableLegacySupport to 3 so that the WMDM compatibility component is registered and enabled for this device when it installs.

; Enable support for legacy WIA and WMDM applications
HKR,,"EnableLegacySupport",0x10001,3

6. When returning the list of rendering information profiles in SetRenderingProfiles(), return an additional profile for WPD_OBJECT_FORMAT_WMV. This profile contains a single WPD_PROPERTY_ATTRIBUTE_FORM_ENUMERATION entry with an IPortableDevicePropVariantCollection containing the list of valid FourCC Codec VT_UI4 values.

This step is needed because the sample driver reports support for WMV. In your real driver implementation, you don't need this step unless your device needs to support WPD_OBJECT_FORMAT_WMV. WMP11 has additional requirements on the attributes of FourCC Codec property, and would not enumerate any content on the device otherwise [Symptom: you will see the device in the Sync Pane, but no content under the device].

In helpers.cpp:

HRESULT GetVideoProfile(
    IPortableDeviceValues** ppProfile)
{
    HRESULT hr = S_OK;
    CComPtr<IPortableDeviceValues> pProfile;
    CComPtr<IPortableDeviceValues> pFourCCCode;

    hr = CoCreateInstance(CLSID_PortableDeviceValues,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IPortableDeviceValues,
                          (VOID**) &pProfile);
    CHECK_HR(hr, "Failed to CoCreateInstance CLSID_PortableDeviceValues");

    if (hr == S_OK)
    {
        hr = CoCreateInstance(CLSID_PortableDeviceValues,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IPortableDeviceValues,
                              (VOID**) &pFourCCCode);
        CHECK_HR(hr, "Failed to CoCreateInstance CLSID_PortableDeviceValues");
    }

    // Set the value for WPD_OBJECT_FORMAT to indicate this profile applies to WMV objects
    if (hr == S_OK)
    {
        hr = pProfile->SetGuidValue(WPD_OBJECT_FORMAT, WPD_OBJECT_FORMAT_WMV);
        CHECK_HR(hr, "Failed to set WPD_OBJECT_FORMAT");
    }

    // Set the value for WPD_VIDEO_FOURCC_CODE
    if (hr == S_OK)
    {
        CComPtr<IPortableDevicePropVariantCollection> pFourCCCodeEnumElements;

        if (hr == S_OK)
        {
            hr = CoCreateInstance(CLSID_PortableDevicePropVariantCollection,
                                  NULL,
                                  CLSCTX_INPROC_SERVER,
                                  IID_IPortableDevicePropVariantCollection,
                                  (VOID**) &pFourCCCodeEnumElements);
            CHECK_HR(hr, "Failed to CoCreateInstance 
                     CLSID_PortableDevicePropVariantCollection");
        }

        if (hr == S_OK)
        {
            hr = pFourCCCode->SetUnsignedIntegerValue(
                                 WPD_PROPERTY_ATTRIBUTE_FORM, 
                                 WPD_PROPERTY_ATTRIBUTE_FORM_ENUMERATION);
            CHECK_HR(hr, "Failed to set WPD_PROPERTY_ATTRIBUTE_FORM 
                          for WPD_VIDEO_FOURCC_CODE");
        }

        if (hr == S_OK)
        {
            // Only 1 sample value is set here, add more as appropriate for your device
            PROPVARIANT pvValue;
            PropVariantInit(&pvValue);
            pvValue.vt = VT_UI4;
            pvValue.ulVal = MAKEFOURCC('W', 'M', 'V', '3');
            hr = pFourCCCodeEnumElements->Add(&pvValue);
            CHECK_HR(hr, "Failed to populate the FourCC Code Enumeration Elements");
        }

        if (hr == S_OK)
        {
            hr = pFourCCCode->SetIPortableDevicePropVariantCollectionValue(
                                 WPD_PROPERTY_ATTRIBUTE_ENUMERATION_ELEMENTS, 
                                 pFourCCCodeEnumElements);
            CHECK_HR(hr, "Failed to set WPD_PROPERTY_ATTRIBUTE_ENUMERATION_ELEMENTS 
                          for WPD_VIDEO_FOURCC_CODE");
        }

        // Now set the Video FourCC Code property to be pFourCCCode
        if (hr == S_OK)
        {
            hr = pProfile->SetIPortableDeviceValuesValue(
                              WPD_VIDEO_FOURCC_CODE, 
                              pFourCCCode);
            CHECK_HR(hr, "Failed to add the WPD_VIDEO_FOURCC_CODE attributes 
                          to the WPD_OBJECT_FORMAT_WMV rendering profile");
        }
    }

    // Set the output result
    if (hr == S_OK)
    {
        hr = pProfile->QueryInterface(IID_PPV_ARGS(ppProfile));
        CHECK_HR(hr, "Failed to QI for IPortableDeviceValues");
    }

    return hr;
}

HRESULT SetRenderingProfiles(
    IPortableDeviceValues*          pValues)
{
    ...
    CComPtr<IPortableDeviceValues>  pVideoProfile;
    ...

    // Get the video profile
    if (hr == S_OK)
    {
        hr = GetVideoProfile(&pVideoProfile);
        CHECK_HR(hr, "Failed to get video profile properties");
    }

    // Add the profile to the collection
    if (hr == S_OK)
    {
        hr = pProfiles->Add(pVideoProfile);
        CHECK_HR(hr, "Failed to add video profile to profile collection");
    }
    ...
}

Known Issue with Multiple Storages

When a device that contains multiple storages is disconnected, one of the storages will still remain in the treeview. This is a known bug in WMP11. Since the WpdWudfSampleDriver emulates multiple storages, you'll see this bug when you disable the driver from Device Manager while WMP11 is running.

Update [August 7, 2009]: The WDK 7.0.0 now contains an updated WpdWudfSampleDriver sample that supports enumeration in Windows Media Player. You can get the latest WDK here. 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.

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

New Driver and Application Whitepapers Are Here

wpdblog — Mon, 07 May 2007 21:51:00 GMT

We've published two new WPD developer-centric whitepapers at the Microsoft WHDC website for WinHEC.

The first covers how to do WMDRM metering and license synchronization from a WPD application; the second describes how to port the existing WPD "Hello World" sample driver to communicate with a Parallax Basic Stamp II microcontroller to read temperature sensor data. Both contain sample code.

I. Accessing WMDRM APIs from a WPD Application:

http://www.microsoft.com/whdc/device/media/WMDRM_API.mspx

This whitepaper describes how to associate a WPD device instance with a WMDM device instance for MTP devices; the WMDM device instance is then used for calling Windows Media Digital Rights Management (WMDRM) application interfaces. To build the sample WPD application, you need the Windows Media Format SDK v11 and the Windows SDK (v6000).

II. Creating a WPD Driver for a Microcontroller-Based Sensor:

http://www.microsoft.com/whdc/device/media/WPD_drv.mspx

This sample is based on the Parallax Basic Stamp II microcontroller to provide an example of a simple hardware device that can have a WPD driver for it. Parallax provides an activity kit that contains the hardware components for this sample driver. To build the driver, you need the Windows Driver Kit (v6000).

References

All WPD-related whitepapers are posted here.

More information on downloading the various SDKs.

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

Driver Dev Guide: Supporting WPD_CLIENT_EVENT_COOKIE

wpdblog — Fri, 04 May 2007 03:13:00 GMT

WPD Applications can specify a unique string "cookie" in the client information when calling IPortableDevice::Open:

WPD_CLIENT_EVENT_COOKIE

VT_LPWSTR

Client supplied cookie returned by the driver in events posted as a direct result of operations issued by this client.

This is in addition to the client information properties described on MSDN, and declared in PortableDevice.h.

Depending on the application, this value will typically contain the application's DLL name or CLSID, or a unique application-generated identifier if the application supports multiple instances of itself running simultaneously. The actual string contents does not matter to the driver, it is passed back to the application when events are sent.

When your driver sends an event and sets the cookie in the event parameters, the application can retrieve the cookie to determine if the event is a result of actions that originated from itself or another program. For example, Application A creates an object on the device, and receives an ObjectAdded event containing its client event cookie, it can choose not to refresh its view of the device contents because the view has been updated at the time the object was created. If Application B creates another object on the device, Application A will receive an ObjectAdded event with a different cookie (or no cookie), and knows that it needs to refresh the device contents view, because the object was added by some other client application.

In an environment where there can be two or more client applications communicating with your driver (Explorer is virtually guaranteed to be one client through the WPD Shell Namespace Extension), supporting the event cookie mechanism is a good WPD programming practice that may help reduce the client traffic to your device in response to events, and to streamline application-side event handling.

How to support WPD_CLIENT_EVENT_COOKIE in your WPD driver:

1. Add a handler for the WPD_COMMAND_COMMON_SAVE_CLIENT_INFORMATION command. The WpdWudfSampleDriver from the WDK contains an example of this in WpdBaseDriver::OnSaveClientInfo().

2. In OnSaveClientInfo(), if the application sets WPD_CLIENT_EVENT_COOKIE in the client information parameters, save the cookie with your context info. Some applications may choose not to send this cookie, in which case your driver does not have to do anything here.

LPWSTR pszEventCookie = NULL; 

hr = pClientInfo->GetStringValue(WPD_CLIENT_EVENT_COOKIE, &pszEventCookie);

if (hr == S_OK && pszEventCookie != NULL)
{
    // Store the cookie value with the client context
    pContext->EventCookie = pszEventCookie;
}

CoTaskMemFree(pszEventCookie);

3. When posting events, if the client event cookie is available, send it along with the event parameters. In the sample driver, this code will be added to the PostWpdEvent() function.

HRESULT hrEventCookie = GetClientEventCookie(pCommandParams, &pszEventCookie);

if (hrEventCookie == S_OK && pszEventCookie != NULL)
{
    // Add it to the event parameters
    // The application's OnEvent callback will match this with its cookie
    hrEventCookie = pEventParams->SetStringValue(WPD_CLIENT_EVENT_COOKIE, pszEventCookie);
}

CoTaskMemFree(pszEventCookie);

And here's an outline of the GetClientEventCookie() helper function. It uses the client information context supplied in the command parameters to look up the saved client cookie in the context map.

ClientContext* pClientContext = NULL;   // This is a context helper object defined by the sample driver

hr = pCommandParams->GetStringValue(WPD_PROPERTY_COMMON_CLIENT_INFORMATION_CONTEXT, &pszClientContext);

if (hr == S_OK)
{
    hr = GetClientContext(pCommandParams, pszClientContext, (IUnknown**)&pClientContext);

    if (hr == S_OK && pClientContext != NULL && pClientContext->EventCookie.GetLength() > 0)
    {
       // Allocate the cookie string to return 
       *ppszEventCookie = AtlAllocTaskWideString(pClientContext->EventCookie);
    }

    if (pClientContext != NULL) 
         pClientContext->Release();

    CoTaskMemFree(pszClientContext);
}

For an overview on posting events, refer to this post.

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

Installing the Sample Drivers on XP and Vista

wpdblog — Tue, 03 Apr 2007 03:16:00 GMT

A question was raised today on how to run the WPD sample drivers on Windows XP. WPD drivers and applications can run downlevel on Windows XP as long as the WPD and UMDF runtimes are both installed.

Compiling a WPD Driver for your OS

For the driver to run on Windows XP, it has to be built using a Windows XP x86 build environment provided by the Windows Driver Kit (v6000 or later). Similarly, for running on Windows Vista, use one of the Windows Vista build environments.

If the runtime OS does not match the build environment, you may get a "Code 10 - This Device Cannot Start" in error message in Device Manager after installing the driver.

Installing WPD on the XP machine

Either one of these supply the WPD runtime components for Windows XP:

1. Install Windows Media Player 11, or

2. Install the Windows Media Format SDK 11 redistributable: WMFDist11-WindowsXP-X86-ENU.exe package, typically under c:\WMSDK\WMFSDK11\Redist folder from a Windows Media Format 11 SDK install.

Obtaining the WUDF Co-Installer

The UMDF runtime is distributed and installed by referencing its co-installer in the driver INF. For Windows Vista and XP, the recommended co-installer to use is the version that is distributed in the Windows Driver Kits: under the \WinDDK\6001.xxxxx\redist\wdf\ folder. Copy this to the same location as your updated driver INF before installing your driver.

Modifying the Sample Driver INF

The following example shows the INF changes to enable the WpdHelloWorldDriver to install in Windows XP using the v1.7 UMDF co-installer. The actual version number would depend on what was provided in the WDK. The modified/added entries are highlighted in red, and the same updates would apply to both WPD driver samples.

The changes involve adding a CopyFiles directive that references WUDFUpdate_01007.dll, and updating the AddReg entries to use UMDF v1.7.

[SourceDisksFiles]
WpdHelloWorldDriver.dll=1
WUDFUpdate_01007.dll=1
...

[Basic_Install.CoInstallers]
AddReg=Basic_Install.CoInstallers_AddReg
CopyFiles=CoInstallers_CopyFiles
...

; Add the co-installer DLL to the CopyFiles list
[CoInstallers_CopyFiles]
WUDFUpdate_01007.dll

...

; Update the registration to use the correct binary
[Basic_Install.CoInstallers_AddReg]
HKR,,CoInstallers32,0x00010000,"WUDFUpdate_01007.dll"

...

; Update the UMDF version to 1.7.0
[WpdHelloWorldDriver_Install]
UmdfLibraryVersion=1.7.0

...

; Set the Co-Installer CopyFiles destination to system32
[DestinationDirs]
System32Copy=12,UMDF ; copy to system32\drivers\umdf
Basic_Install.CoInstallers_CopyFiles=11
...

The same updated INF will also work on Windows Vista, as long as the UMDF co-installer DLL is provided with your driver files during install AND you've compiled the driver DLL with the correct WDK build environment (see the first section of this post).

On Windows Vista, installing the WPD runtime components is not required because WPD is available inbox for most SKUs.

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

Driver Dev Guide: WPP Tracing in your WPD Driver

wpdblog — Sun, 01 Apr 2007 21:14:00 GMT

WPP Software Tracing is the recommended way to log trace and error messages in your WPD driver. WPP, short for Windows Software Trace PreProcessor, provides an efficient real-time event logging mechanism. In addition, WPP traces include the system timestamp and can be used as a way to measure performance, for example by calculating the elapsed time between function calls.

From OutputDebugString to WPP

The WPD sample drivers in the Windows Driver Kit (WDK) log error messages using a CHECK_HR function that wraps around OutputDebugString. While OutputDebugString is simple to use during development, it necessitates an active debugger connection in order to view the traces, and should be used minimally in shipping code. WPP tracing is much more lightweight, flexible, and preferable for a range of tracing applications: logging errors for diagnosing failures, tracing code execution during development, to name a few.

How to switch your WPD driver's tracing from OutputDebugString to WPP transparently:

Step 1. Remove the original CHECK_HR() function definition (it can be found in WpdHelloWorldDriver.cpp or WpdWudfSampleDriver.cpp for the WPD samples) and its declaration in stdafx.h.

Step 2. Add the following code (include the WPP config comment blocks) to stdafx.h:

// TODO: Choose a different trace ID for your WPD driver
#define MYDRIVER_TRACING_ID      L"Microsoft\\WPD\\MyWpdDriver"

// TODO: Choose a different trace control GUID for your WPD driver
// TODO: Define trace flag bits for your WPD driver

#define WPP_CONTROL_GUIDS                                                   \
    WPP_DEFINE_CONTROL_GUID(                                                \
        MyWpdDriverCtrlGuid, (da5fbdfd,1eae,4ecf,b426,a3818f325ddb),        \
                                                                            \
        WPP_DEFINE_BIT(TRACE_FLAG_ALL)                                      \
        WPP_DEFINE_BIT(TRACE_FLAG_DRIVER)                                   \
        WPP_DEFINE_BIT(TRACE_FLAG_DEVICE)                                   \
        )                             

//
// Prefer trace statement that is based on
//     - the standard trace LEVEL (evntrace.h), and
//     - specific flag bit.
//
#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)
               
#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

//
// This comment block is scanned by the trace preprocessor to define our
// Trace and TraceEvents function.
//
// begin_wpp config
// FUNC Trace{FLAG=TRACE_FLAG_ALL}(LEVEL, MSG, ...);
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

// MACRO: CHECK_HR
// Configuration block that defines trace macro. It uses the PRE/POST macros to include
// code as part of the trace macro expansion. CHECK_HR is equivalent to the code below:
//
// {if (hrCheck != S_OK){  // This is the code in the PRE macro
//     DoTraceMessage(TRACE_FLAG_ALL,  "%!STDPREFIX!" MSG " hr= %!HRESULT!", ..., hrCheck)
// ;}}                              // This is the code in the POST macro
//                                 

// begin_wpp config
// USEPREFIX (CHECK_HR,"%!STDPREFIX!");
// FUNC CHECK_HR{FLAG=TRACE_FLAG_ALL}(hrCheck, MSG, ...);
// USESUFFIX (CHECK_HR, " hr= %!HRESULT!", hrCheck);
// end_wpp

#define WPP_FLAG_hrCheck_PRE(FLAGS, hrCheck) {if(hrCheck != S_OK) {
#define WPP_FLAG_hrCheck_POST(FLAGS, hrCheck) ; } }
#define WPP_FLAG_hrCheck_ENABLED(FLAGS, hrCheck) WPP_FLAG_ENABLED(FLAGS)
#define WPP_FLAG_hrCheck_LOGGER(FLAGS, hrCheck) WPP_FLAG_LOGGER(FLAGS)

Step 3. Add a RUN_WPP directive to your sources file:

RUN_WPP= $(SOURCES) -scan:stdafx.h

Step 4. Add the WPP initialization and cleanup routines to DllMain:

// DLL Entry Point
extern "C" BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved)
{
    if(DLL_PROCESS_ATTACH == dwReason)
    {
        g_hInstance = hInstance;
      
        //
        // Initialize tracing.
        //
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);
    }
    else if (DLL_PROCESS_DETACH == dwReason)
    {
        //
        // Cleanup tracing.
        //
        WPP_CLEANUP();
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Step 5. For each .cpp file, add a #include <filename>.tmh after the regular includes:

//
// WpdBaseDriver.cpp
//

#include "stdafx.h"
#include "WpdBaseDriver.h"

// Include the WPP generated Trace Message Header (tmh) file for this .cpp
#include "WpdBaseDriver.tmh"

...

Repeat Step 5 for all other .CPP files.

Step 6. Rebuild your driver. Since we replaced the CHECK_HR function with an equivalent WPP macro that has the same signature (our WPP changes were "under the hood"), no changes are needed for any code that uses CHECK_HR. You can continue to use CHECK_HR the same way as before :).

The WPP preprocessor will process stdafx.h for tracing macros, and generate a Trace Message Header (tmh) file for each cpp file in the obj folders.

Inspecting the preprocessor output for each .CPP file that calls CHECK_HR (generated using make WpdBaseDriver.pp), you will notice that all CHECK_HR trace statements have been wrapped by WPP function calls, while the tracing text and WPP functions are defined in WpdBaseDriver.tmh.

The most common WPP-related compilation errors you may encounter are due to mismatched format identifiers and parameters (e.g. if your format string contains an extra %d that does not match an argument) or missing entries in the WPP_CONTROL_GUIDS macro.

More WPP Tracing Macros

We've also defined TraceEvents and Trace functions in stdafx.h that are general purpose WPP trace macros wrapping DoTraceMessage. These can be used for both error and non-error trace logging using a combination of levels and flags. For examples on how to use them in your driver, refer to the UMDF sample drivers in the WDK.

To understand the WPP declarations used in stdafx.h, customize the CHECK_HR macro, or to define your own tracing macros, visit the WPP macros guide which describes the WDK tracedrv sample in detail.

Generating and Viewing Traces

To generate traces, you can use Traceview (UI) or Tracelog (command line). TraceView also allows you to view traces in real-time as they are logged. These are available in the WDK. A quick way to get started is to create a new log session from Traceview using the PDB file that contains the private symbols for your driver. Alternatively, you use a .CTL file that specifies your driver as a trace provider (replace own values below):

da5fbdfd-1eae-4ecf-b426-a3818f325ddb    MyWpdDriverCtlGuid

Converting Binary Traces to A Human-Readable Form

WPP traces log to a binary ETL format. To convert them to text, supply Trace Format (TMF and TMC) files that can be generated from the .PDB file using TracePDB. For more details, refer to the tracing tools section in the MSDN docs.

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

Driver Dev Guide: How to Post Events from your WPD Driver

wpdblog — Sat, 17 Mar 2007 01:57:00 GMT

DimeBy8 wrote a great post on how a WPD application can receive driver-initiated WPD PnP events; this post will describe the driver's side of our eventing story. While this mechanism is "under the covers" for most WPD application developers, it helps to get an end-to-end picture of how stuff works in WPD land, especially if you are thinking about writing a WPD driver and application for vertical scenarios that involve posting and receiving custom events.

Standard WPD Events and Parameters

Here is the list of standard WPD events. These GUIDs are defined in PortableDevice.h. When you begin accessing these events as a WPD application or driver), you may soon realize a missing piece of information: what/where are the parameters for these events? The Event parameters are described in more detail in the Basic WPD Device Driver Requirements WHDC whitepaper, under Requirements for Event Parameters.

A snippet from the whitepaper that describes the required parameters for WPD_EVENT_OBJECT_UPDATED:

WPD_EVENT_OBJECT_UPDATED

This event is sent after an object has been updated so that any connected client should refresh its view of that object.

Parameters

WPD_EVENT_PARAMETER_PNP_DEVICE_ID

Required.

WPD_EVENT_PARAMETER_EVENT_ID

Required.

WPD_OBJECT_PERSISTENT_UNIQUE_ID

Required.

WPD_EVENT_PARAMETER_OBJECT_PARENT_PERSISTENT_UNIQUE_ID

Required.

WPD_EVENT_PARAMETER_CHILD_HIERARCHY_CHANGED

Required if the object hierarchy at any level under this object has changed.

Event parameters matter when you're sending a standard WPD event from your driver. For example, when receiving WPD_EVENT_OBJECT_UPDATED, applications may utilize information such as WPD_OBJECT_PERSISTENT_UNIQUE_ID to determine which object's properties would need to be refreshed in their properties view.

*Aside: One consequence of supporting any WPD event that requires the Persistent Unique ID of objects is that your driver needs to support this property (but this is a required property anyway for most content objects). The list of required properties is also covered in Basic WPD Device Driver Requirements.

Posting a WPD Event from Your Driver

Now that you know what parameters to send with a WPD event, posting the event is a three step process:

Initialize an IPortableDeviceValues to hold the event parameters.
Serialize the IPortableDeviceValues to a BYTE buffer.
Call IWDFDevice::PostEvent with the EventGuid = WPD_EVENT_NOTIFICATION and the serialized buffer. Only WdfEventBroadcast events are supported, which means all WPD applications that call IPortableDevice::Advise can receive the event your driver posts.

BYTE* pBuffer  = NULL;
DWORD cbBuffer = 0;

// Populate the event parameters
hr = pIPortableDeviceValues->SetGuidValue(WPD_EVENT_PARAMETER_EVENT_ID, WPD_EVENT_OBJECT_UPDATED);

// Set other required event parameters here ....

if (hr == S_OK)
{
    // Serialize the event parameters to a buffer 
    hr = pWpdSerializer->GetBufferFromIPortableDeviceValues(pIPortableDeviceValues, &pBuffer, &cbBuffer);
}

// Send the event.
if (hr == S_OK)
{
    hr = pIWDFDevice->PostEvent(WPD_EVENT_NOTIFICATION, WdfEventBroadcast, pBuffer, cbBuffer);
}

// Cleanup ...
CoTaskMemFree(pBuffer);
pBuffer = NULL;

Defining a Custom WPD Event (and adding it to WpdInfo/WpdMon's Vocab!)

WPD's extensibility mechanism allows for custom events to be defined very easily. You define a new GUID for your custom event, and define PROPERTYKEYs for your event parameters (or reuse existing PROPERTYKEYs). On the application side, check for this custom event GUID the same way as you handle a WPD event, and process the event. Your driver should also report these new event(s) when responding to WPD_COMMAND_CAPABILITIES_GET_SUPPORTED_EVENTS and WPD_COMMAND_CAPABILITIES_GET_EVENT_OPTIONS.

Both the WPDInfo and WPDMon WDK tools can receive and display custom WPD events in the raw GUID form, which means you already have a handy way to validate your driver's event posting functionality without needing to write a WPD application.

You can even "teach" our tools to translate the custom event GUID to its symbolic name. This can be done by adding an entry to the WpdInfo.GUIDs file (this is a text file usually located in the same folder path as the tool exes), and restarting the tools to reload this file. In a similar way, symbolic names for your custom PROPERTYKEYs can go into WpdInfo.Properties file, custom commands in WpdInfo.Commands, etc.

It's important to note that updating these WpdInfo.* dictionary files only enables the WPD tools in your PC to translate custom GUIDs and PROPERTYKEYs to symbolic string like names, other WPD applications and drivers know nothing on these custom values that are specific to your driver and application.

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

WPDMon Gotchas

wpdblog — Tue, 06 Feb 2007 02:40:00 GMT

If you're developing a WPD driver or a WPD application, you may have come across the WPD Monitor tool (a.k.a. WpdMon).

This is a tool that displays WPD traffic between applications and a WPD driver for diagnostic purposes. Plug and Play (PnP) messages and Raw (DeviceIoControl) traffic are also viewable. WpdMon is available in the Windows Driver Kits, e.g. c:\WinDDK\6000\tools\wpd\x86.

Known issues in WpdMon

Issue #1 WPDMon.exe is not showing any traces

Make sure that you have installed WpdMon according to the instructions in WpdMon.htm (also found under e.g. c:\WinDDK\6000\tools\wpd\x86).

1. Ensure that all WPD devices are unplugged
2. For 32-bit systems, copy the Shim DLL to the AppPatch directory (“copy WpdMonShim.dll %windir%\AppPatch”) from an Administrator Command Prompt. On 64-bit systems, copy the Shim DLL to the AppPatch64 directory (“copy WpdMonShim.dll %windir%\AppPatch\AppPatch64”)
3. Register the shim (“Regsvr32 %windir%\AppPatch\WpdMonShim.dll” for 32-bit, or “Regsvr32 %windir%\AppPatch\AppPatch64\WpdMonShim.dll” for 64-bit) from an Administrator Command Prompt.
4. Plug WPD devices back in
5. The WPD Monitor Application (WpdMon.exe) is now ready to capture WPD API/DDI traffic, and can be copied and run directly from any directory. It requires administrator privileges, so you need to right click on WpdMon.exe from Explorer and select "Run Elevated", or launch WpdMon from an Administrator Command Prompt.

Issue #2 I've installed WpdMon according to the instructions in WpdMon.htm, but I still can't see any traces

Ensure that you've launched WpdMon with Administrator privileges. Either right click on the WpdMon.exe from Explorer and select "Run Elevated", or launch WpdMon from an Administrator Command Prompt.

Ensure that you have Monitor -> API Traffic checked to enable WPD API tracing.

If you have a Root Enumerated WPD device (such as one of the WPD driver samples from the WDK) running before WpdMon was installed, the Windows User Mode Driver Framework (WUDF) driver process (WUDFHost.exe) is still running, You'll need to force WUDFHost.exe process to restart so that the WpdMonShim dll can load:

1. Launch WpdMon.exe with Administrator privileges
2. From Device Manager, select the WPD device (under Portable Devices)
3. Right click "Disable" to disable the WPD device
4. Right click "Enable" to re-enable the WPD device
5. WpdMon.exe should now show traces

Issue #3 I see a lot of traces in WpdMon and would like to save them to a file, but the "File -> Save Viewer Output As" dialog keeps getting out of scope

WpdMon logs to both the window and a Wpdmon.htm file, both in the same directory as WpdMon.exe. Sometimes when there is a lot of WPD API traffic going on, the WpdMon window would update rapidly and grab the window focus from the File->Save As dialog.

There are two ways to get around this:

1. Uncheck "Log to Viewer" from the Options menu to disable logging to Window, or

2. If you need the Viewer output, uncheck "Auto Scroll Viewer Output" from the Options menu to disable the scrolling. You will have to scroll down manually to view the latest traces.

Setting up WpdMon.ini

You can configure default WpdMon settings by modifying the WpdMon.ini file. This is useful in situations where you want WpdMon to log to HTML silently, for example.

1. Close WpdMon
2. Open WpdMon.ini in a text editor (e.g. Notepad)
3. Under the [General] section, set the following options (0=disable, 1=enable).

LogToViewer=0
LogToHTMLFile=1

4. Reopen WpdMon

WpdMon.ini also contains settings to disable/enable API, Raw and PnP tracing by default. You can set Enabled=1 under each parser section (e.g. [APIParser]) to enable the WPD API traces. Enabled=0 will disable the API tracing. You can turn this on/off dynamically while WpdMon is running, to start and stop the tracing.

Issue #4 I lost the instructions since WpdMon.exe overwrote the tool readme:

WpdMon automatically saves traces to WpdMon.htm. Unfortunately, this file bears the same name as the tool readme and will overwrite the readme when WpdMon.exe is launched. You may want to save a copy of the original WpdMon.htm as backup before running WpdMon, or refer to an identical copy from a different OS architecture that was not overwritten, e.g. in c:\WinDDK\6000\tools\wpd\amd64\wpdmon.htm).

Issue #5 WpdMon keeps logging even after I've closed my WPD application

Sometimes when WpdMon captures and processes a lot of realtime WPD traffic, there can be a delay between the actual WPD operation and tracing display. This is normal as the window may take some time to display all the traces. You can speed things up by minimizing the WpdMon window, and then clicking on something else in Explorer so that the WpdMon is not in focus.

Once the minimized WpdMon window stops flickering, restore the window, and scroll down to refresh it.

If you still see intermittent traffic, it is possibly because other WPD applications (e.g. Explorer via the WPD Shell Namespace Extension or Windows Media Player) are communciating with your driver/device.

Still can't get WpdMon to show API traces for debugging your driver?

If you are developing a WPD driver and need tracing information, a good alternative is to convert your driver traces to WPP tracing. This post describes how to migrate the CHECK_HR macro used in our sample drivers to use WPP traces "under the covers", and should provide you with a good start for adopting WPP for your driver logging needs.

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

Debugging Your WPD Driver with Visual Studio 8

wpdblog — Fri, 02 Feb 2007 00:12:00 GMT

WPD drivers are based on the Windows Driver Foundation (WDF) – User-Mode Driver Framework (UMDF) platform. UMDF drivers provide greater stability and security than kernel-mode drivers while providing comparable performance. And, UMDF drivers allow the use of user-mode debuggers such as Visual Studio 8. (Debugging a driver in user-mode tends to be faster than debugging in kernel-mode because an error only affects the current process rather than the entire computer.)

General Visual Studio 8 Debugging Tips
Once your driver is installed, you can create a debugging project in Visual Studio 8 by following these steps:

1. Open Visual Studio 8 and select “File/New/Project from Existing Code…” menu.

2. Follow the steps in the “Welcome to the Create Project form Existing Code Files Wizard” (specifying the language, the location of your driver source files, a project name, and so on).

3. Open your newly created project.

4. Select the “Debug/Attach to Process…” menu and then choose WudfHost.exe in the list of Available Processes that appears in the “Attach to Process” dialog.

Once you complete the above steps, you can begin setting breakpoints in your driver’s source code and debug your driver.

Tips for Debugging WPD Driver Initialization Code
A WPD driver’s initialization code (for example, the code found in WpdBaseDriver::Initialize() in the two WPD sample drivers that ship with the Windows Driver Kit), executes during the installation of your driver. In order to debug this initialization code, you’ll need to accomplish the following tasks:

1. Create a debugging project in Visual Studio 8 (as described in the previous section).

2. Open an instance of regedit.exe and specify a delay period (in seconds) for the WudfHost.exe process. This delay is specified using the following key: \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a…}\HostProcessDbgBreakOnStart

3. Force the WUDFHost.exe process to reload. This can be done in a couple of ways, depending on what your device configuration is:

a) From Device Manager, Disable and then Enable your device's WPD devnode

b) If your device has a physical connection to the PC, unplug and then re-reconnect your device.

4. Upon driver reload, start Visual Studio 8, open your debug project, and attach to the WudfHost.exe process. As a side effect, you may see Device Manager hanging when you reload the driver, while WudfHost.exe is waiting for a debugger to connect.

The delay which you set for the …\HostProcessDbgBreakOnStart value provides the necessary time to start the debugger prior to the installation of your driver. (For example, a value of 0x00000040 would delay the installation for 64 seconds.) This delay allows you time to attach to the process, set a breakpoint in your initialization code, and begin debugging.

For more information about the HostProcessDbgBreakOnStart value, refer to this MSDN topic.

Update [August 7, 2009]: The WDF team has provided an excellent tool that makes debugging both kernel mode and user mode WDF drivers much easier. The WDFVerifier is available in the Windows Driver Kit (WDK). For details, refer to the WDFVerifier MSDN page. In addition, we recommend these in-depth posts by Bob Kjelgaard, an SDET from the WDF team, covering basic and advanced usages of WdfVerifier:

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

Building Driver Samples from the WDK

wpdblog — Wed, 31 Jan 2007 10:37:00 GMT

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.

Getting Your Feet Wet .... with WPD Development

wpdblog — Tue, 23 Jan 2007 21:42:00 GMT

Here’s a common question we get from developers:

“I read about WPD from the MSDN library, but where do I download the samples, tools and build environment that are mentioned in the docs?“

Writing a WPD Application

To get started on developing a WPD application, download the Windows SDK. This contains the header and library files, build environment, and code for a sample WPD application.

Writing a WPD Driver

To get started on developing a WPD driver, download the Windows Driver Kit. This contains sample drivers, tools, build environment, and documentation for WPD and User Mode Driver Framework.

We recommend using WPDInfo and WPDMon as debugging and testing tools for driver development. These are bundled into the Windows Driver Kits. For more details on these tools, refer to the "WPD Tips" Whitepaper.

Need more tips and tricks? One of our WPD enthusiasts has written a blog with tons of WPD and Media Transfer Protocol (MTP) how-tos.

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