Windows Portable Devices Team Blog : WMDM

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.

Windows 7 Portable Device Development Kits

wpdblog — Sat, 12 Sep 2009 09:58:00 GMT

There are several different resources made available to portable device manufacturers to assist in device firmware and driver development, and to application developers wishing to create applications that interact with these portable devices. These resources are provided and maintained by members of the Windows Portable Devices team.

This post provides a description for the following development kits:

Windows 7 Portable Device Enabling Kit for MTP
Windows Portable Devices SDK
Windows Portable Devices Driver Kit
Windows Media Device Manager SDK
Microsoft Device Experience Development Kit
Windows Logo Kit

Windows 7 Portable Device Enabling Kit for MTP

This development kit is designed to assist portable device manufacturers in the development of Media Transfer Protocol (MTP) device firmware that is compatible with the various MTP device transports that Windows supports, and with Device Services. There are two packages provided for download:

Windows 7 Portable Device Enabling Kit for MTP - Tools
The tools kit includes design documentation and implementation guidelines, a Windows-based reference design, development tools, and the updated MTP Device Simulator.

Windows 7 Portable Device Enabling Kit for MTP - Reference Code
The reference code kit includes the core responder reference source code that is being made available under a separate Berkeley Software Distribution (BSD)–style license.

To download both packages of the Windows 7 Portable Device Enabling Kit for MTP, go to: http://www.microsoft.com/whdc/device/wpd/MTP-DEK_Win7.mspx

You are not required to license the reference code in order to use the tools and resources provided in the tools kit. This kit is free to download and use.

Windows Portable Devices SDK

The WPD SDK includes the WPD Application Programming Interface (API) that is supported in Windows 7, Windows Vista, and Windows XP operating Systems. Developers will use this API to write Windows applications in C++. Being a COM API, the WPD API is also accessible from Managed code, so C# .Net, and Visual Basic .Net applications can use COM Interoperability to invoke the same functionality that the C++ API provides. WPD applications can: explore a device, send and receive content, and even control the device, for example, take a picture or send a text message.

The WPD SDK includes two sample applications for C++/COM developers. The first, WpdApiSample, is a command-line desktop application that demonstrates how you would: enumerate connected devices, explore those devices, query device-objects for properties and attributes, send and retrieve data, and so on. The second sample, WpdServicesApiSample, is a command-line desktop application that demonstrates how you would explore a Contacts service on a device that is attached to your computer.

The WPD SDK also includes an Automation Object Model that is supported in Windows 7. Developers can use the Automation model to write web applications that accomplish tasks similar to those accomplished with the API. We provided an introduction to WPD Automation in this recent post.

The WPD SDK is included in the Windows SDK which can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en

The documentation for the WPD SDK (both the API and Automation Object Model) is found on MSDN at: http://msdn.microsoft.com/en-us/library/dd388998(VS.85).aspx

Windows Portable Devices Driver Kit

The WPD Driver Kit includes a Device Driver Interface (DDI) that is supported in Windows 7, Windows Vista, and Windows XP operating Systems. Developers will use this DDI to write drivers for devices that are not already supported by the MTP or Mass Storage class drivers that Microsoft distributes.

The WPD Driver Kit includes five sample device drivers which are described in the following table. In the next post, we covered each sample in more detail.

Sample Driver	Description
WpdHelloWorldDriver	This is the most basic WPD driver that emulates interaction with hardware. Supports four objects: device, storage, folder, and file. This provides the scaffolding or skeleton for developing a WPD driver.
WpdBasicHardwareDriver	Builds upon the WpdHelloWorldDriver and demonstrates interaction with simple hardware devices. Supports nine sensor devices: 2-axis accelerometer, 3-axis accelerometer, temperature/humidity sensor, pressure sensor, distance sensor, passive infrared sensor, compass, vibration sensor, and light sensor. These sensor devices are simple devices that are controlled by a Parallax BS2 microcontroller attached to the PC. 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.
WpdServiceSampleDriver	Demonstrates how a developer would extend the WpdHelloWorldDriver to support a simulated device with a Contacts device service.(Using this service, WPD applications can discover events, methods, and properties associated with the Contacts stored on the device. This sample emulates interaction with hardware.
WpdMultiTransportDriver	Demonstrates how developers can take advantage of the Windows 7 support for multiple transports. The sample emulates interaction with hardware and demonstrates support for the following transports: IP, Bluetooth, and USB. We covered an overview of Multi-transport support in Windows 7 here.
WpdWudfSampleDriver	A comprehensive sample driver that demonstrates what to enable in the WPD DDI for media transfer scenarios (such as music and photos). This sample supports media synchronization with Windows Media Player, and also emulates interaction with hardware.

The WPD Driver Kit is included in the Windows Driver Kit (WDK). For information about downloading the WDK, see: http://www.microsoft.com/whdc/devtools/wdk/WDKpkg.mspx

The documentation for the WPD Driver Kit is found on MSDN at: http://msdn.microsoft.com/en-us/library/dd419925.aspx

Windows Media Device Manager SDK

The Windows Media Device Manager (WMDM) SDK enables you to build desktop applications and components that can communicate with connected portable devices. WMDM enables your application or component to enumerate, explore, and exchange files with a device, query for metadata, and request play count information. Applications or components built on WMDM have a consistent API for communicating with a wide range of devices including Media Transfer Protocol (MTP), Mass Storage Class (MSC), RAPI, and other devices built on both the latest and previous versions of Windows Media technology.

The Windows Media Device Manager SDK is available at: http://msdn.microsoft.com/en-us/windows/bb190309.aspx.

Microsoft Device Experience Development Kit

The Microsoft Device Experience Development Kit provides detailed information and material that you would need to know in order to develop Device Stage™ experiences for Portable Devices. The development kit includes device development guides, planning worksheets, tutorials, and development samples that you can use when developing a Device Stage experience on Windows 7. For portable devices, Device Stage supports the industry-standard Media Transfer Protocol (MTP) 1.0 with device services that enable a new rich set of features in Windows 7.

The development kit along with other pertinent information to build a complete Windows Device Experience is available at: http://www.microsoft.com/whdc/device/DeviceExperience/default.mspx

The kit is free to download and use.

Windows Logo Kit

The primary use of the Windows Logo Kit (WLK) is for Windows Logo Program device certification. This kit can also be used for product development. We encourage its use during the product development cycle of hardware in order to ensure device compliance with both Windows and industry standards. The kit includes several tests designed to validate device implementation and behavior at multiple levels. There are tests for USB compliance, Media Transfer Protocol (MTP) compliance, and Windows Portable Devices (WPD) platform compliance that also cover device services validation.

There is a significant amount of information available about the WLK, including user guides and video tutorials. For more information about the WLK see: http://www.microsoft.com/whdc/winlogo/WLK/default.mspx

The kit is free to download and use.

Other Resources

Windows Portable Devices node on Windows Hardware Developer Central

http://www.microsoft.com/whdc/device/wpd/default.mspx

Windows Portable Devices on Microsoft Developer Network

http://msdn.microsoft.com/en-us/library/dd388998(VS.85).aspx

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.

WPD and WMDM Side-by-side: An Application Development Perspective

wpdblog — Sat, 24 Mar 2007 20:24:00 GMT

This post will compare WPD and the latest version of Windows Media Device Manager (WMDM), from an application developer's point of view.

Availability (aka SDK and Runtime Requirements)

The Windows SDK contains the complete build environment (headers, libs, sample code ...) for developing a WPD application for both 32 and 64-bit.

The Windows Media Format 11 SDK (WMFSDK11) provides headers and libs for WMDM 11. Since WMFSDK11 is released in 32-bit, only 32-bit WMDM applications can be built. On 64-bit Windows, a 32-bit WMDM application will run in SysWOW mode.

	WMDM 11	WPD
Operating Systems	Windows XP + Windows Media Format 11 Redistributable, Windows Vista	Windows XP + Windows Media Format 11 Redistributable, Windows Vista
Processors	X86, AMD64 (SysWOW mode only)	X86, AMD64
SDKs	Windows Media Format SDK 11	Windows SDK

Common Device-level Operations

Both WPD and WMDM support basic device-level operations: enumeration of connected devices, managing device-level properties, and querying of static device capabilities.

WMDM's IWMDMDeviceControl operations internally delegate to the service provider (through IMDSPDeviceControl), and would require the service provider to support these operations. While device playback control is not natively supported by the WPD API, WPD's extensibility mechanism makes it easy to add this as a custom command to your driver. For example, your WPD driver can support a custom Playback command that your application can invoke using IPortableDevice::SendCommand.

Operation	Example WMDM API	Suggested WPD API
Enumerate attached devices	IWMDeviceManager2::EnumDevices2	IPortableDeviceManager::GetDevices
Enumerating device content	IWMDMDevice::EnumStorage	IPortableDeviceContent::EnumObjects
Examine device capabilities	IWMDMDevice::GetFormatSupport, IWMDMDevice2::GetFormatCapability	IPortableDeviceCapabilities:: GetSupportedContentTypes, GetSupportFormats
Retrieve device properties	IWMDMDevice::GetManufacturer	IPortableDeviceManager:: GetDeviceManufacturer OR IPortableDeviceProperties::GetValues(WPD_DEVICE_OBJECT_ID)
Write device properties	IWMDMDevice3::SetProperty	IPortableDeviceProperties::SetValues(WPD_DEVICE_OBJECT_ID)
Controlling device playback	IWMDMDeviceControl::Play	-

Common Object-level Operations

A WPD object is analogous to a WMDM storage, and most WMDM storage operations have their equivalent WPD API. WPD is ObjectID-based, so each interface method that supports object-level operations receives an Object Identifier as a parameter. WMDM is interface-based, IWMDMStorage represents a storage or a file, and IWMDMStorageControl implements the operations on a storage or a file.

For data object creation, both WPD and WMDM support transfer of protected Windows Media Digital Rights Management (WMDRM) content.

Operation	Example WMDM API	Suggested WPD API
Enumerating objects	IWMDMDevice::EnumStorage, IWMDMEnumStorage::Next	IPortableDeviceContent::EnumObjects, IEnumPortableDeviceObjectIDs::Next
Create a folder object	IWMDMStorageControl::Insert3	IPortableDeviceContent:: CreateObjectWithPropertiesOnly
Create a data object	IWMDMStorageControl::Insert3	IPortableDeviceContent:: CreateObjectWithPropertiesAndData
Transfer object data from device	IWMDMStorageControl::Read	IPortableDeviceResources::GetStream
Move objects	IWMDMStorageControl::Move	IPortableDeviceContent::Move
Copy objects	-	IPortableDeviceContent::Copy
Delete objects	IWMDMStorageControl::Delete	IPortableDeviceContent::Delete
Retrieve object properties	IWMDMStorage4::GetSpecifiedMetadata	IPortableDeviceProperties::GetValues
Write object properties	IWMDMStorage3::SetMetadata	IPortableDeviceProperties::SetValues
Delete object properties	-	IPortableDeviceProperties::Delete

Device Events

There are only 4 events that WMDM applications can receive: media arrival/removal, and device arrival/removal. WPD supports device-level and the more granular object-level events, plus built-in extensibility for custom events.

Operation	Example WMDM API	Suggested WPD API
Monitor object-level property changes	-	IPortableDeviceEventCallback::OnEvent (WPD_EVENT_OBJECT_UPDATED)
Monitor object-level arrival and removal	-	IPortableDeviceEventCallback::OnEvent (WPD_EVENT_OBJECT_ADDED, WPD_EVENT_OBJECT_REMOVED)
Monitor media arrival and removal	IWMDMNotification::WMDMMessage (WMDM_MSG_MEDIA_ARRIVAL, WMDM_MSG_MEDIA_REMOVAL)	IPortableDeviceEventCallback::OnEvent (WPD_EVENT_OBJECT_ADDED, WPD_EVENT_OBJECT_REMOVED)
Monitor device removal	IWMDMNotification::WMDMMessage (WMDM_MSG_DEVICE_REMOVAL)	IPortableDeviceEventCallback::OnEvent (WPD_EVENT_DEVICE_REMOVED)
Monitor device arrival	IWMDMNotification::WMDMMessage (WMDM_MSG_DEVICE_ARRIVAL)	Subscribe to WPD interface arrival PnP event

Advanced Operations

Both WPD and WMDM provide some extensibility mechanism for sending device-specific commands. IWMDMDevice3::DeviceIoControl is used for packaging and sending commands only to Media Transfer Protocol (MTP) portable media players.

WPD API methods that map to Command GUIDs internally delegate to IPortableDevice::SendCommand. Applications can invoke these commands with additional options or parameters, such as the use of Read or Write IOCTLs for access control.

In addition, for better performance, WPD supports batching of property writes and retrievals across multiple objects, either per format or using a list of Object Identifiers.

Operation	Example WMDM API	Suggested WPD API
Retrieve properties of multiple objects	-	IPortableDevicePropertiesBulk:: QueueGetValuesByObjectList, OR QueueGetValuesByObjectFormat
Set properties of multiple objects	-	IPortableDevicePropertiesBulk:: QueueSetValuesByObjectList
Send device-specific commands	IWMDMDevice::SendOpaqueCommand OR IWMDMDevice3::DeviceIoControl	IPortableDevice::SendCommand
Cancel an operation	-	IPortableDevice*::Cancel, e.g. IPortableDeviceProperties::Cancel

Stability

WMDM loads registered service providers (SPs) within the same process as the application. Any crash or instability in the device driver or SP could cause undue crashes in the application process, or worse, trigger bluescreens if kernel mode drivers are involved.

WPD drivers are sandboxed in the User Mode Driver Framework (UMDF) host process, and gain the stability and security benefits of a UMDF driver. If a WPD driver crashes, only the sandbox process will be affected; the WPD application process is isolated from the driver instability. In a similar way, a WPD driver's process is not affected when a WPD client application crashes.

The Verdict

WPD and WMDM have a lot of overlap in terms of the device operations that each enables. WMDM is geared specifically towards portable media player applications and scenarios, with media-centric metadata schema, support for device playback control, and direct access to Windows Media Digital Rights Management (WMDRM) application interfaces. WPD supports much of what WMDM does (including WMDRM transfers), plus many key advantages over WMDM, including stability, UMDF integration, comprehensive property and content type schema (beyond portable media devices), extensibility for custom device solutions, broader device support, and not to mention, great development tools.

For applications that would like to connect to, control, and manage content across a wide range of devices (digital still cameras, portable media players, cellular phones, third-party device classes, and more), WPD is the clear choice.

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

Working with WMDRM Protected Content using WPD

wpdblog — Sat, 10 Feb 2007 02:55:00 GMT

Setting up your WPD application to handle protected WMDRM content

The WPD API supports the transfer and licensing operations for Windows Media Digital Rights Management (WMDRM) content.

This MSDN article describes two additional properties that are required to enable your WPD application to transfer protected content.

Property	Vartype	Description
WPD_CLIENT_WMDRM_APPLICATION_PRIVATE_KEY	VT_VECTOR \| VT_UI1	Specifies the application's private key.
WPD_CLIENT_WMDRM_APPLICATION_CERTIFICATE	VT_VECTOR \| VT_UI1	Specifies the application's certificate.

To initialize WPD for protected content, call IPortableDevice::Open() with the above parameters added to the pClientInfo IPortableDeviceValues. If this succeeds, you can use the derived IPortableDeviceContent interface (from IPortableDevice::Content()) to transfer protected (and clear) content using IPortableDeviceContent::CreateObjectWithPropertiesAndData().

To obtain a private application key and certificate, visit this link.

Transferring Content

To transfer WMDRM protected content, use IPortableDeviceContent::CreateObjectWithPropertiesAndData(). The same CreateObjectWithPropetiesAndData API call can be used for both protected and clear content without additional options. The WPD API will automatically select the protected or clear channel depending on whether the content is protected or clear. It interfaces with the WMDRM Secure Content Provider to process the WMDRM licenses.

Transferring Known Clear Content

If you've enabled WPD to handle protected content, but you know that a specific file is not protected, you can tell WPD to skip the DRM processing by setting WPD_API_OPTION_USE_CLEAR_DATA_STREAM option to TRUE in the input IPortableDeviceValues when calling IPortableDeviceContent::CreateObjectWithPropertiesAndData() for clear content.

Accessing Metering Operations using IWMDRMDeviceApp

WPD provides a mechanism to access the IWMDRMDeviceApp APIs for license updates and metering data retrieval. To access IWMDRMDeviceApp through WPD, call QueryInterface on IID_IWMDRMDeviceApp from the IStream returned from IPortableDeviceContent::CreateObjectWithPropertiesAndData(). This IWMDRMDeviceApp instance tied to the IPortableDevice connection to your WMDRM-compatible device, and not the specific content where the IStream was obtained. WPD internally wraps the metering APIs and makes it accessible to your application. Your application uses a constant for the IWMDMDevice* parameter: WMDRMDEVICEAPP_USE_WPD_DEVICE_PTR.

IStream* pDataStream = NULL;

IWMDRMDeviceApp* pWMDRMApp = NULL;

// ... Initialization

hr = pPortableDeviceContent->CreateObjectWithPropertiesAndData(pValues,

&pDataStream,

&dwOptimalWriteBufferSize,

NULL);

// ... Transfer the protected WMDRM content

pDataStream->Write(pData, cbData, &cbWritten);

pDataStream->Commit(0);

hr = pDataStream->QueryInterface(IID_IWMDRMDeviceApp,

(void**)&pWMDRMApp);

if (SUCCEEDED(hr))

{

DWORD dwStatus = 0;

// Call metering operations on the current device using the WPD device pointer

hr = pWMDRMApp->QueryDeviceStatus((IWMDMDevice *)WMDRMDEVICEAPP_USE_WPD_DEVICE_PTR,

&dwStatus);

}

The same pre-requisitie with the application private key and certificate applies here as well. If the key/certificate is invalid or if the WMDRM system fails to initialize, the QueryInferface call will fail.

Update [March 13, 2007]: The above method to acquire the IWMDRMDeviceApp interface from the IStream pointer is just a convenience if your application is already doing a prior protected content transfer, before proceeding on to do metering and license synchronization operations.

Our recommendation for most applications that need to access IWMDRMDeviceApp is to initialize IWMDRMDeviceApp directly as this does not require your application to transfer protected content or hold on to the transfer interfaces in order to do device metering and license sync. For details, refer to this MSDN article entitled "Handling Protected Content in the Application."

Update [May 5, 2007]: The whitepaper (and sample code) on initializing IWMDRMDeviceApp for WPD is now posted here.

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