Windows Portable Devices Team Blog : SDK

Windows 7 Application Samples

wpdblog — Sat, 26 Sep 2009 01:52:00 GMT

The Windows Portable Devices (WPD) SDK includes two sample command-line applications written in C++. The first application, WpdApiSample, lets the user accomplish tasks like: enumerating connected devices, exploring objects on these devices, and enumerating object properties. The second application, WpdServiceApiSample, is designed to explore a Contacts Device Service. The user can enumerate connected device services, retrieve properties and formats for a given service, and invoke methods on that service. 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 following sections describe each sample application, the modules found in that application, and the operating systems that it will run on.

WpdApiSample

Of the two sample applications, the WpdApiSample, is the most generalized. It demonstrates how a developer would use the WPD API to accomplish tasks common to most applications. For example, this application demonstrates how a developer would:

· Enumerate the devices connected to a computer.

· Establish a connection to a connected device.

· Enumerate device content.

· Retrieve the properties for a given object on a device.

· Set the properties for a given object on a device.

· Retrieve general device information (for example, a description of the operations that a device can perform).

· Operate on device content (for example, move a file from one folder on the device to another).

The WpdApiSample application includes the following files:

File	Description
ContentEnumeration.cpp	Contains functions that enumerate all the objects on a device.
ContentProperties.cpp	Contains functions that read and write object properties and make bulk property set/get requests.
ContentTransfer.cpp	Contains functions that transfer content to or from the device, read object type requirements, and create a folder on the device.
DeviceCapabilities.cpp	Contains functions to list the functional object types on the device, list the content types supported by each functional object type, and display rendering object profiles.
DeviceEnumeration.cpp	Lists the friendly names, manufacturers, and descriptions of all connected devices.
DeviceEvents.cpp	Contains functions that log device events and their parameters whenever events are fired.
Stdafx.cpp	Includes the standard files.
WpdApiSample.cpp	Displays a list of available devices and tasks available to the user.

This application is supported on Windows XP, Windows Vista, and Windows 7.

Even if you have no WPD devices connected to your computer, you can familiarize yourself with the WPD API and this application by installing the WpdHelloWorldDriver sample from the Windows Driver Kit (WDK), which emulates a simple WPD device. For information about downloading the WDK, see http://www.microsoft.com/whdc/resources/downloads.mspx

WpdServiceApiSample

The WpdServiceApiSample sample demonstrates how a developer would use the WPD API to explore a Contacts Device Service on a device that’s attached to a computer. For example, this application demonstrates how a developer would:

· Enumerate the services on a devce.

· Open a service.

· Enumerate service content.

· Retrieve the events and methods supported by a service.

· Access the service object properties.

· Invoke service methods (both synchronously and asynchronously).

The WpdServiceApiSample application includes the following files:

File	Description
ContentEnumeration.cpp	Contains methods that enumerate the content on a given Contacts service.
ContentProperties.cpp	Contains methods that read and write properties on a given Contacts service.
ServiceCapabilities.cpp	Contains the methods that retrieve the supported formats, events, and abstract services that are supported by a given Contacts service.
ServiceEnumeration.cpp	Contains the helper functions that retrieve device information such as the device-friendly name or the supported Contacts services.
ServiceMethods.cpp	Contains the methods that retrieve and invoke methods supported by a given Contacts service.
Stdafx.cpp	Includes the standard files.
WpdServiceApiSample.cpp	Displays a list of available device services and tasks available to the user

Because Device Services is new for Windows 7, this application is only supported in the Windows 7 operating system.

Even if you have no WPD devices connected to your computer, you can familiarize yourself with the WPD API and this application by installing the WpdServiceSampleDriver that’s included as a sample in the Windows Driver Kit (WDK). This sample driver emulates a simple WPD device service.

Other Samples

In addition to the two samples that ship in the SDK, the WPD team created three other samples that demonstrate using WPD to display the current office temperature in the Windows Sidebar. One of these samples is written using unmanaged-code and C++; another is written using the COM interop and Visual Basic .Net; and, the third is written using the COM interop and Visual C# .Net.

All three of these samples rely on a simple temperature sensor device, device-firmware, and a sample WPD driver. You can download the circuit description, device-firmware, and sample driver from here: http://www.microsoft.com/whdc/device/media/WPD_drv.mspx

Once you build the device, download the firmware, and install the driver, you can begin exploring the WPD API samples. You’ll find a description of the unmanaged application at: http://blogs.msdn.com/wpdblog/archive/2007/12/19/creating-a-temperature-sensor-gadget-for-windows-sidebar-with-c.aspx.

You’ll find a description of the COM interop and Visual Basic .Net application at: http://wpdtempsensor.codeplex.com/.

And, you’ll find a description of the COM interop and the C# application at: http://blogs.msdn.com/wpdblog/archive/2007/11/26/creating-a-temperature-sensor-gadget-for-windows-sidebar.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.

Visual Basic .Net Sample for WPD

wpdblog — Wed, 16 Jan 2008 20:49:00 GMT

We've created a Visual Basic .Net sample for WPD and posted it to CodePlex: Microsoft's open source project-hosting web site. Take a look at http://www.codeplex.com/wpdtempsensor

In addition to the Visual Basic project and source files, we've posted a document that describes the sample. This document also describes how you can address and resolve the COM Interop issues associated with .Net and WPD.

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

Creating a Temperature Sensor Gadget for Windows Sidebar with C++

wpdblog — Thu, 20 Dec 2007 01:13:00 GMT

The following post describes a gadget for Windows Sidebar that displays the temperature reading from a temperature sensor device. Similar applications could be written to display: battery-level or available memory for a portable media device, contact lists from a mobile phone or PDA, route lists from a GPS device, and so on.

Introduction

Microcontrollers are used in a variety of applications from industrial to automotive to the home. One use that stretches across these boundaries is the microcontroller-based sensor which monitors parameters such as temperature, humidity, acceleration, distance, and light.

While the microcontroller device-universe has grown exponentially, there hasn’t been a common interface for integrating these devices with the PC. As a result, device and application developers were forced to write custom software to handle operations like data retrieval and display.

Microsoft recently introduced Microsoft® Windows® Portable Devices (WPD), a technology that addresses the challenges of integrating microcontroller-based devices with your PC. A microcontroller-based device can be as simple as a remote sensor or as complex as a mobile phone, a portable media player, or a digital camera. WPD consists of a driver model that runs in the user-mode driver framework (UMDF) and an API that simplifies the creation of applications for these devices.

This paper describes the use of the WPD API to create a Windows Console application that retrieves temperature data from a temperature sensor device. In addition, it describes a corresponding gadget for Windows Sidebar that consumes the data collected by the application.

The temperature sensor used by this application is based on the BASIC Stamp Activity Kit for Windows Portable Devices. This kit is offered by the Parallax Corporation in Rocklin, California. You can order the kit from the company’s Web site.

The console application obtains real-time temperature data from a Parallax temperature sensor device. It writes this data to a file on disk. A script in the gadget’s HTML file retrieves the data and renders it in Windows Sidebar.

The console application was written in Microsoft Visual Studio® 8 using the C++ programming language. The WPD gadget was written in HTML and Jscript®.

Downloading the Sample Application and Sidebar Gadget

To download the sample application, see this page on the Microsoft Downloads site.

To download the gadget, see this page on the Microsoft Downloads site.

Running the Sample Application

The sample application requires that the WPD temperature sensor driver (WpdTempSensorDriver.dll) is installed and that a temperature sensor device is connected over a standard RS232 port.

The WPD temperature sensor driver exposes a Temperature Sensor object. This object, in turn, exposes three programmatic elements: two properties and an event. These elements are described in the following table.

Programmatic Element	Description
Interval property	This read/write property specifies the frequency at which the device should return the current temperature. (This property is specified in milliseconds.)
Temperature property	This read-only property specifies the current temperature in degrees Kelvin.
Temperature-reading event	This event is fired each time the device retrieves the current temperature. (The Interval property specifies the frequency at which the device will fire this event.)

The sample console application, described in this white paper, registers to receive the Temperature-reading event notification each time it’s fired. Upon receiving the notification, the application writes the temperature data as HTML and saves it in an ASCII text file. The gadget, in turn, reads the HTML from this file and renders it in Sidebar.

Building and Installing the Temperature Sensor Device

The temperature sensor device referenced in this paper is based on a Parallax BS2 microcontroller and an AD592 Temperature Sensor transducer.

Parallax supplies a complete hardware kit that includes all of the required components. To order the kit, see this page on the Parallax site.

You can download the Basic Stamp source code for the temperature sensor device from the WHDC site.

Building and Installing the WPD Temperature Sensor Driver

In order to install the driver, download the source code and build it. For information about downloading the driver, see the following topic on the WHDC Web site.

Installing the Gadget

The download package referenced above in this article contains a file named WpdTemperatureSensor.gadget. Copy this file to your local machine, open Windows Explorer, and double-click this file. You will be asked whether you want to install the gadget. Click Install.

The gadget will be installed in the Desktop\\AppData\Local\Microsoft\Windows Sidebar\Gadgets folder.

Now you’re ready to build and run the sample application.

Building and Running the Sample Application

The download package included with this white paper contains the project, source, and header files for the sample console application that retrieves temperature data from the sensor.

After you’ve installed the temperature sensor device, driver, and gadget files, you’ll need to extract the contents of the download package to your development machine. This includes the following files.

· stdafx.h

· stdafx.cpp

· deviceevents.cpp

· sidebar_console.cpp

· sidebar_console.vcproj

For a description of these files, see the Temperature Sensor Console Application section that follows.

If you haven’t installed the Windows SDK for Windows Vista, you’ll need to do so before building the project. For information about installing the Windows SDK, visit the Windows SDK web page.

Once the Windows SDK is installed, open the project file (sidebar_console.vcproj) in Visual Studio 8. Select the Build_Sidebar console option from the Build menu. Visual Studio 8 will build an executable file and place it in the \Debug subdirectory. You can test the gadget and verify that it works by selecting Start Debugging from the Debug menu.

WPD Application and Gadget Overview

The WPD application and gadget consists of two separate processes: a server and a client. The server is a console application which monitors the temperature sensor device for event notifications. Each time this application receives a notification, it writes corresponding temperature data formatted as HTML to a file on disk. The client is a script running in the gadget’s HTML file. This script retrieves the data from the file created by the console application and renders it in Sidebar.

The WPD Console Application registers to receive temperature events from the device. These events are fired at an interval specified by the device’s Interval property. (The default value for this property is 2,000 milliseconds.)

The event handler in the console application writes the temperature as a string of HTML to an ASCII text file on the local disk. This string has the following appearance.

<P>Office Temperature<P>304° Kelvin

The gadget’s script executes every 3,000 milliseconds. The script reads the string of HTML created by the console application and inserts that string into the body of the gadget’s HTML.

The Temperature Sensor Console Application

The temperature sensor console application is a simple application that accomplishes the following tasks.

· Searches for the temperature sensor device and opens a connection if the device is found.

· Registers to receive event notifications from the device.

· Enters a loop and responds to any one of three inputs from the user.

· While listening for user input, and for as long as the event registration is intact, writes temperature data to the local disk.

The temperature sensor application project consists of the following files:

File	Description
stdafx.h	Contains #defines for the target platform as well as #includes for the standard system include file.
deviceevents.cpp	Implements IPortableDeviceEventCallback which is required by any WPD application that registers to receive device events.
sidebar_console.cpp	Implements the entry point for the console application and the helper functions which perform tasks like searching for the device and establishing a connection.
stdafx.cpp	Contains #include for stdafx.h
sidebar_console.vcproj	The Visual Studio 8 project file.

Most of work accomplished by the application is found in the module named sidebar_console.cpp; the exception is the event handling code which is found in the module deviceevents.cpp.

Opening a Connection to the Temperature Sensor Device

The WPD API provides a set of interfaces that a Windows programmer can use to accomplish tasks like enumerating connected devices, opening a device, closing a device, enumerating objects on a device, reading and writing properties on a device, sending a command to a device, and registering to receive events from a device.

One of the primary interfaces is the IPortableDevice interface which supports the methods a programmer calls to open a device, receive events, send a command, and so on.

The first task the sample application accomplishes is to open (establish a connection to) the temperature sensor device. It does this by calling the IPortableDevice::Open method. This method takes two parameters: a pointer to a string that specifies a special identifier for the device and a pointer to an array of key/value pairs that specify information about the calling application.

hr = CoCreateInstance(CLSID_PortableDevice,

NULL,

CLSCTX_INPROC_SERVER,

IID_IPortableDevice,

(VOID**) &pIPortableDevice);

if (SUCCEEDED(hr))

{

if (pIPortableDevice != NULL)

{

hr = (pIPortableDevice)->Open(DeviceID, pClientInformation);

if (FAILED(hr))

{

// Release the IPortableDevice interface

// because we cannot proceed with an

// unopen device.

pIPortableDevice = NULL;

}

else

{

printf("Device successfully opened.\n\r\n\r");

}

In order to retrieve the device identifier DeviceID, which is passed as the first parameter to IPortableDevice::Open, the application first needs to determine whether the temperature sensor device is connected to the PC and, if it is, retrieve the identifier.

The FindDevice helper function in the Sidebar_Console.cpp module accomplishes this work. The FindDevice function has two arguments: the first is a “friendly” name for the target device; the second is the special Plug and Play identifier that the WPD API returns as a match for this friendly name.

The FindDevice helper function accomplishes the following tasks.

1. Retrieves a count of devices connected to the PC.

2. Retrieves an array of friendly names for each device.

3. Compares the friendly name passed in its first argument to the friendly names for each of the connected devices.If a match is found, it retrieves the Plug and Play identifier for the target device.

Retrieving a Count of Connected Devices

The first task of the FindDevice function is the retrieval of a count of connected devices. This is done in two stages: first, by creating an IPortableDeviceManager object, and second, by calling the IPortableDeviceManager::GetDevices method. (In order to retrieve a count of connected devices, the first argument to GetDevices is set to NULL.)

// CoCreate the IPortableDeviceManager interface to enumerate

// portable devices and to get information about them.

hr = CoCreateInstance(CLSID_PortableDeviceManager,

NULL,

CLSCTX_INPROC_SERVER,

IID_IPortableDeviceManager,

(VOID**) &pPortableDeviceManager);

if (FAILED(hr))

{

printf("! Failed to CoCreateInstance CLSID_PortableDeviceManager\n\r\n\r");

return hr;

}

// First, pass NULL as the LPWSTR array pointer to get the total

// number of devices found on the system.

if (SUCCEEDED(hr))

{

hr = pPortableDeviceManager->GetDevices(NULL, &cPnPDeviceIDs);

if (FAILED(hr))

{

printf("! Failed to get number of devices on the system\n\r\n\r");

return hr;

}

Retrieving a Plug and Play name for the Temperature Sensor

WPD supports two types of device names: friendly names and Plug and Play names. The friendly names are the names applications display to the user. The friendly name for the temperature sensor device is: "Parallax BS2 Temperature Sensor". The Plug and Play names are used internally by WPD to identify devices. The Plug and Play name for the temperature sensor device is:

\\?\root#wpd#0000#{6ac27878-a6fa-4155-ba85-f98f491d4f33}

This string uniquely identifies the device instance and the device interface, and it is defined as part of the Windows Driver Model (WDM). For more information, refer to this MSDN topic.

After retrieving a count of connected devices and storing it in the cPnPDeviceIDs variable, FindDevice iterates through the available devices until it finds a device whose friendly name matches the string “Parallax BS2 Temperature Sensor”. If this match is made, FindDevice returns the corresponding Plug and Play name in the DeviceID argument.

if (cPnPDeviceIDs > 0)

{

pPnpDeviceIDs = new LPWSTR[cPnPDeviceIDs];

if (pPnpDeviceIDs != NULL)

{

DWORD dwIndex = 0;

hr = pPortableDeviceManager->GetDevices(pPnpDeviceIDs, &cPnPDeviceIDs);

if (SUCCEEDED(hr))

{

// For each device found, retrieve the friendly

// name and compare it to the submitted name.

for (dwIndex = 0; dwIndex < cPnPDeviceIDs; dwIndex++)

{

CAtlStringW FriendlyName;

hr = RetrieveFriendlyName(pPortableDeviceManager, pPnpDeviceIDs[dwIndex], FriendlyName);

if ((hr == S_OK) && (DeviceName.CompareNoCase(FriendlyName) == 0))

{

DeviceID = pPnpDeviceIDs[dwIndex];

bFoundDevice = TRUE;

break;

}

else

{

printf("! Failed to get the device list from the system\n\r\n\r");

}

if (SUCCEEDED(hr) && (!bFoundDevice))

{

printf("! Failed to find a matching device\n\r\n\r");

hr = E_FAIL;

}

// Free all returned PnPDeviceID strings by using

// CoTaskMemFree.

// NOTE: CoTaskMemFree can handle NULL pointers, so

// no NULL check is needed.

for (dwIndex = 0; dwIndex < cPnPDeviceIDs; dwIndex++)

{

CoTaskMemFree(pPnpDeviceIDs[dwIndex]);

pPnpDeviceIDs[dwIndex] = NULL;

}

// Delete the array of LPWSTR pointers.

delete [] pPnpDeviceIDs;

pPnpDeviceIDs = NULL;

}

else

{

printf("! Failed to allocate memory for LPWSTR array\n\r\n\r");

hr = E_OUTOFMEMORY;

}

return hr;

}

The application passes the returned Plug and Play name as the first argument to IPortableDevice::Open when it opens the device.

Note that the FindDevice function calls the RetrieveFriendlyName helper function to retrieve a friendly name for each Plug and Play name returned by IPortableDeviceManager::GetDevices. The RetrieveFriendlyName function calls the IPortableDeviceManager::GetFriendlyName method twice to retrieve the friendly name string. The first time, it calls this method to retrieve a count of characters in the friendly name string; the second time, it calls this method to retrieve the actual string.

// First, pass NULL as the LPWSTR return string parameter to get

// the total number of characters to allocate for the string

// value.

hr = pPortableDeviceManager->GetDeviceFriendlyName(pPnPDeviceID, NULL, &cchFriendlyName);

if (FAILED(hr))

{

printf("! Failed to get number of characters for device friendly name.\n\r\n\r");

return hr;

}

// Second, allocate the number of characters needed and retrieve

// the string value.

if ((hr == S_OK) && (cchFriendlyName > 0))

{

wszFriendlyName = new WCHAR[cchFriendlyName];

if (wszFriendlyName != NULL)

{

hr = pPortableDeviceManager->GetDeviceFriendlyName(pPnPDeviceID, wszFriendlyName, &cchFriendlyName);

if (SUCCEEDED(hr))

{

FriendlyName = wszFriendlyName;

}

else

{

printf("! Failed to get device friendly name\n\r\n\r");

}

// Delete the allocated friendly name string.

delete [] wszFriendlyName;

wszFriendlyName = NULL;

}

Receiving Device Events

The WPD API and driver model were designed so devices can issue events and applications can register to receive notifications when these events occur. Applications that receive events must implement the IPortableDeviceEventCallback interface. This interface supports a single OnEvent method. The driver calls this method each time an event is fired. However, in order for a driver to call this method, an application first needs to register with the driver. An application registers with the driver by calling the IPortableDevice::Advise method. The third argument for this method, pCallback, is a pointer to the IPortableDeviceEventCallback interface that the application implemented.

The temperature sensor device issues a single temperature-reading event that the sample application registers to receive. Each time the driver calls the OnEvent method, the sample application writes the received temperature to a local file on disk. The gadget’s script then reads from this file to update the gadget with the most recent office temperature.

Implementing IPortableDeviceEventCallback

The sample application implements the IPortableDeviceEventCallback interface in the DeviceEvents.cpp module. Most of the code in this module was taken from the WpdApiSample application that ships with the Windows SDK. The following changes were made to the original file.

· The TEMPERATURE_SENSOR_READING property key was defined and declared.

· The OnEvent method was modified to process the TEMPERATURE_SENSOR_READING property and write the new temperature value to disk.

The IPortableDeviceEventCallback interface is implemented in the CPortableDeviceEventsCallback class in DeviceEvents.cpp. This class supports the following methods.

Method	Description
CPortableDeviceEventsCallback	Object constructor
~CPortableDeviceEventsCallback	Object destructor
QueryInterface	Returns a pointer to the IPortableDeviceEventCallback interface.
AddRef	Increments the object’s reference count.
Release	Decrements the object’s reference count.
OnEvent	Event handler. WPD will call this method if the application is registered to receive event notifications.

In addition to implementing IPortableDeviceEventCallback, the DeviceEvents.cpp module also contains two functions that the application calls in order to register and unregister for event notifications. These functions are described in the following table.

Function	Description
RegisterForEventNotifications	Registers the application to receive event notifications. (This method is called when the application first starts.It’s also called if the user requests registration by entering the number 2 at the command prompt.)
UnregisterForEventNotifications	Unregisters the application from receiving event notifications. (This method is called if the user requests cancellation of registration by entering the number 1 at the command prompt.)

Implementing the IPortableDeviceEventCallback::OnEvent Method

Once an application registers to receive event notifications, the WPD device driver will call the IPortableDeviceEventCallback::OnEvent method whenever the device fires an event. Each time the driver calls this method, it passes data associated with the given event in an IPortableDeviceValues interface. The pEventParameters argument is a pointer to this interface.

The temperature sensor device fires one event per temperature reading update, and the accompanying data is a single, signed integer value which specifies the current temperature in degrees Kelvin. The sample application retrieves this value by calling the IPortableDeviceValues::GetSignedIntegerValue method and passing the property key for the TEMPERATURE_SENSOR_READING property as the first argument. (This property key was declared and defined at the top of DeviceEvents.cpp.)

HRESULT __stdcall OnEvent(

IPortableDeviceValues* pEventParameters)

{

HRESULT hr = S_OK;

LONG i=0;

HANDLE hFile;

DWORD dwBytesWritten;

char strHtmlPrefix[]="<P>Office Temperature<P>";

char strHtmlSuffix[]="° Kelvin";

char strHtml[40];

if (pEventParameters != NULL)

{

pEventParameters->GetSignedIntegerValue(TEMPERATURE_SENSOR_READING, &i);

sprintf_s(strHtml, "%s%d%s\0", strHtmlPrefix, i, strHtmlSuffix);

hFile = CreateFileW(_T("c:\\temp\\tempdata.txt"),

GENERIC_WRITE,

NULL,

CREATE_ALWAYS,

FILE_ATTRIBUTE_NORMAL,

NULL);

if (WriteFile(hFile, strHtml, sizeof(strHtml), &dwBytesWritten, NULL))

{

printf("Current temperature: %d Kelvin\n\r", i);

printf("Temperature written to target file.\n\r\n\r");

}

else

{

printf("Temperature not written to target file.\n\r");

printf("WriteFile failed with error %d.\n\r\n\r", GetLastError());

}

CloseHandle(hFile); // We need to close the handle.

}

return hr;

}

Upon retrieving the current temperature, the OnEvent method writes a string of HTML to a temporary file on disk (c:\temp\tempdata.txt). The gadget reads this string of HTML from the temporary file and incorporates it into the gadget’s own HTML. In addition, the OnEvent method writes the current temperature to the console window.

Implementing the RegisterForEventNotifications Function

The sample application supports a single function, RegisterForEventNotfications, which it calls at startup and if the user explicitly requests registration. This function performs the following tasks.

4. Examines the event registration cookie (g_strEventRegistrationCookie) to determine whether the application is already registered.

5. If not, creates an instance of the CPortableDeviceEventsCallback object.

6. Calls the IPortableDevice::Advise method to complete the registration.

7. If registration is successful, assigns the event cookie returned by the Advise method to the g_strEventRegistrationCookie variable.

void RegisterForEventNotifications(IPortableDevice* pDevice)

{

HRESULT hr = S_OK;

LPWSTR wszEventCookie = NULL;

CPortableDeviceEventsCallback* pCallback = NULL;

if (pDevice == NULL)

{

return;

}

// Check to see if we already have an event registration cookie.

// If so, then avoid registering again.

// NOTE: An application can register for events as many times as.

// wanted. This sample only keeps a single registration

// cookie around for simplicity.

if (g_strEventRegistrationCookie.GetLength() > 0)

{

printf("This application has already registered to receive device events.\n\r\n\r");

return;

}

// Create an instance of the callback object. This will be

// called when events are received.

if (hr == S_OK)

{

pCallback = new CPortableDeviceEventsCallback();

if (pCallback == NULL)

{

hr = E_OUTOFMEMORY;

printf("Failed to allocate memory for IPortableDeviceEventsCallback object, hr = 0x%lx\n\r\n\r",hr);

}

// Call Advise to register the callback and receive events.

if (hr == S_OK)

{

hr = pDevice->Advise(0, pCallback, NULL, &wszEventCookie);

if (FAILED(hr))

{

printf("! Failed to register for device events, hr = 0x%lx\n\r\n\r",hr);

}

// Save the event registration cookie if event registration was

// successful.

if (hr == S_OK)

{

g_strEventRegistrationCookie = wszEventCookie;

}

// Free the event registration cookie if one was returned.

if (wszEventCookie != NULL)

{

CoTaskMemFree(wszEventCookie);

wszEventCookie = NULL;

}

if (hr == S_OK)

{

printf("This application has registered for device event notifications.\r\n\r\n");

}

// If a failure occurs, remember to delete the allocated callback

// object if one exists.

if (pCallback != NULL)

{

pCallback->Release();

}

Implementing the UnregisterForEventNotifications Function

The sample application supports a single function, UnregisterForEventNotfications, which it calls if the user explicitly cancels registration. This function performs the following tasks.

8. Calls the IPortableDevice::Unadvise method and passes the registration cookie (which is also the event cookie returned by the IPortableDevice::Advise method).

9. Sets the internal event registration-cookie variable g_strEventRegistrationCookie to an empty string.

void UnregisterForEventNotifications(IPortableDevice* pDevice)

{

HRESULT hr = S_OK;

if (pDevice == NULL)

{

return;

}

hr = pDevice->Unadvise(g_strEventRegistrationCookie);

if (FAILED(hr))

{

printf("! Failed to unregister for device events using registration cookie '%ws', hr = 0x%lx\n\r\n\r",g_strEventRegistrationCookie.GetString(), hr);

}

if (hr == S_OK)

{

printf("This application used the registration cookie '%ws' to unregister from receiving device event notifications\n\r\n\r", g_strEventRegistrationCookie.GetString());

}

g_strEventRegistrationCookie = L"";

}

Handling User Input

The sample application displays a simple menu in the console window when it begins execution. This menu has three options corresponding to three integer values.

Option/Value	Description
1	Unregister for device notifications. (The application calls the UnregisterForEventNotifications function.)
2	Register for device notifications. (The application calls the RegisterForEventNotifications function.)
99	Exit. (The application exits.)

The code that supports the menu and its options is found in the ProcessInput function in the Sidebar_Console.cpp module.

void ProcessInput(CComPtr<IPortableDevice> pIPortableDevice)

{

HRESULT hr = S_OK;

UINT uiSelection = 0;

CHAR szSelection[81] = {0};

printf("\n\n");

printf("===============================================\r\n");

printf("1. Unregister for device notifications.\r\n");

printf("2. Register for device notifications.\r\n");

printf("99. Exit.\r\n");

printf("===============================================\r\n");

printf("\n\n");

while (uiSelection != 99)

{

ZeroMemory(szSelection, sizeof(szSelection));

hr = StringCbGetsA(szSelection,sizeof(szSelection));

if (SUCCEEDED(hr))

{

uiSelection = (UINT) atoi(szSelection);

switch (uiSelection)

{

case 1:

// Unregister to receive device events

UnregisterForEventNotifications(pIPortableDevice);

break;

case 2:

// Register to receive device events

RegisterForEventNotifications(pIPortableDevice);

default:

break;

}

else

{

printf("! Failed to read menu selection string input, hr = 0x%lx\n\r\n\r",hr);

}

The Temperature Sensor Gadget

The temperature sensor gadget displays the current office temperature in degrees Kelvin in Windows Sidebar.

If you’ve never created a gadget for Windows Sidebar before, refer to the Gadget Development Overview.

The Temperature Sensor Gadget Files

The temperature sensor gadget consists of three files: an HTML file, an XML file, and a JPEG file. These files are described in the following table.

File Name	Description
UpdateTemperatureReading.htm	An HTML file that contains the script which retrieves the updated temperature data from the local disk every 3,000 milliseconds.
gadget.xml	The gadget manifest. This file specifies properties such as the name of the gadget, the name of its HTML file, a string of descriptive text, and so on.
background.jpg	A 163 x 58 pixel image that produces the gadget’s two-tone blue background color.

Retrieving the Current Temperature

The gadget’s HTML file, UpdateTemperatureReading.htm, contains a script which opens the file created by the console application (c:\temp\tempdata.txt) and copies the contents of this file into a span element identified as “temperature_data” within the body of the gadget’s HTML.

This script creates a FileSystemObject which it uses to open and read the text file. It uses the OpenTextFile method to open the file and the ReadAll method to retrieve its contents.

The script uses the setTimeout method on the window object to recursively execute the update function every 3,000 milliseconds. (This function contains the code that retrieves the contents of c:\temp\tempdata.txt.)

<html>

<head>

var fileSystemObject = null;

function loaded()

{

fileSystemObject = new ActiveXObject("Scripting.FileSystemObject");

update();

}

function update()

{

var textStream = fileSystemObject.OpenTextFile("c:\\temp\\tempdata.txt");

try

{

temperature_data.innerHTML = textStream.ReadAll();

}

finally

{

textStream.Close();

window.setTimeout(update, 3000);

}

</script>

<style>

body

{

margin: 0;

width: 125px;

height: 62px;

font: 'normal 8pt Arial';

line-height: 12pt;

text-align:center;

}

</style>

</head>

<g:background src="background.png">

</g:background>

</body>

</html>

The HTML file also contains a description of the gadget’s window between the <style> and </style> tags that follow the script. Note that the width and height attributes match the width and height of the background image (background.png). In addition to specifying the size of the gadget’s window, the attributes found here specify the font used to render text, the line height (which creates padding between the two lines of text), and the text alignment.

The g:background element specifies the source file (background.png) for the gadget’s background image.

The span element “temperature_data” identifies the location of the HTML which is copied from c:\temp\tempdata.txt by the Update function.

More Information

· For general information about developing gadgets for Windows Sidebar, see the Gadget Development Overview.

· To learn more about the BASIC Stamp Activity Kit for Windows Portable Devices, refer to the Parallax site.

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.

How to Receive WPD Arrival Event Notifications

wpdblog — Sat, 17 Mar 2007 04:25:00 GMT

If you followed the standard WPD events link in our previous post on WPD driver events, you may have seen the following event definition:

WPD_EVENT_DEVICE_REMOVED

This event is sent when a driver for a device is being unloaded. This is typically a result of the device being unplugged.

Clients should release the IPortableDevice interface they have open on the device specified in WPD_EVENT_PARAMETER_PNP_DEVICE_ID.

In a nutshell, when a WPD device disconnects, IPortableDeviceEventCallback::OnEvent is called with this specific event GUID and the PnP Device ID in the event parameters, allowing applications to clean up the associated WPD interfaces for that device instance, display UI, etc.

Having an event to tell an application when a device is disconnected can help applications build richer or smarter device scenarios. Why isn't there a device arrival event, ala WPD_EVENT_DEVICE_ARRIVED, to cover the converse Disconnected -> Connected case?

The reason this hypothetical event doesn't exist is that WPD events utilize the IWDFDevice::PostEvent mechanism, which requires the WPD driver to up and running (with the device connected). Consequently, to receive such events, a WPD application has to invoke IPortableDevice::Advise and maintain an open IPortableDevice connection.

Device Interface Arrival Events to the Rescue

Fortunately, Plug-and-Play provides your application with the ability to receive broadcast device notifications on device interfaces, including WPD's. This standard mechanism has existed long before WPD, and is documented here in MSDN. The following code snippets show how to register for WPD device interface notifications, and how to handle the corresponding arrival event.

//
// Step 1: Registering for WPD device interface PnP notification events
//

// The WPD device interface GUID
#define WPD_DEVINTERFACE L"{6ac27878-a6fa-4155-ba85-f98f491d4f33}"

GUID guidDevInterface            = GUID_NULL;
DEV_BROADCAST_DEVICEINTERFACE db = {0};
db.dbcc_size = sizeof(db);
db.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
CLSIDFromString(WPD_DEVINTERFACE, &guidDevInterface);
db.dbcc_classguid  = guidDevInterface;

hDevNotify = RegisterDeviceNotificationW(hWnd, &db, DEVICE_NOTIFY_WINDOW_HANDLE);

do error checking ...


//
// Step 2: Processing the DBT_DEVICEARRIVAL event when a WPD device is connected
//

LRESULT WndProc(HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{  
   switch (uMsg)
   {
       ....

       case WM_DEVICECHANGE:
       {
          switch(wParam) 
          {	    
             case DBT_DEVICEARRIVAL:
             {
                 PDEV_BROADCAST_HDR pdbh = (PDEV_BROADCAST_HDR)lParam;
                 if (pdbh != NULL && pdbh->dbch_devicetype == DBT_DEVTYP_DEVICEINTERFACE)
                 {
                     PDEV_BROADCAST_DEVICEINTERFACE pdbi = (PDEV_BROADCAST_DEVICEINTERFACE)lParam;
            
                     if (IsEqualGUID(pdbi->dbcc_classguid, guidDevInterface)) 
                     {
                         // Initialization is skipped here for brevity
                         // Use the symbolic name to open a PortableDevice connection
                         // pClientInfo is an IPortableDeviceValues containing the client information
                         // NOTE: Use a separate thread if your code could block
                         hr = pIPortableDevice->Open(pdbi->dbcc_name, pClientInfo);

                         do more error checking ...
                     }
		 }
                 break;         
             }
             
             ...
 
          } // switch (wParam)
       }
       break;
       ....
   } // switch (uMsg)
}

To summarize, the application will receive a WM_DEVICECHANGE message for the DBT_DEVICEARRIVAL event when the device is connected. DEV_BROADCAST_DEVICEINTERFACE.dbcc_name is equivalent to the WPD PnP Device ID, which the application can use when calling IPortableDevice::Open.

The guidelines for processing Plug-and-Play messages apply: the event handler should process the event as quickly as possible, using a separate thread if there's a possibility of blocking execution, to avoid undue system hangs.

Choices of Device Removal Events

The application will also receive a DBT_DEVICEREMOVECOMPLETE event, which can be useful for e.g. placing arrival and removal handlers in the same code module. The difference between this event and WPD_EVENT_DEVICE_REMOVED is subtle. The latter is a custom PnP event that is sent via WUDF during unloading of the WPD driver (usually caused by a device unplug); whereas DBT_DEVICEREMOVECOMPLETE is triggered by the removal of a device interface (also caused by a device unplug). Usually, WPD applications that just want a notification when WPD devices are disconnected can subscribe to either event and get the same effect.

Further Reading (and more code samples)

To learn more on how to use PnP device notifications, refer to this detailed article from The Code Project.

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

Getting ERROR_BUSY (0x800700AA) after reading data from an MTP device?

wpdblog — Fri, 09 Mar 2007 22:40:00 GMT

One common cause of the ERROR_BUSY (0x800700AA) in MTP devices is when the application reads resource data from a content object on the portable device using IStream::Read(), and does not complete the read with an IStream::Close(). Subsequent operations that eventually translate into MTP commands into the device could fail with ERROR_BUSY because the resource read operation is not yet complete. Sometimes the failure could appear delayed - after the resource read, there could be several successful WPD API calls before ERROR_BUSY appears, because the interim calls that succeeded were handled by the MTP driver (i.e. do not require the driver to talk to the device).

From the device's perspective, reading resource data translates to a sequence of operations involving the MTP command "GetObject". This has to be completed or cancelled before further MTP commands to the device could proceed.

For example, if your application does the following:


IStream* pObjectDataStream = NULL;

// 1. Open the default resource of an object with read access
HRESULT hr = pIPortableDeviceResources->GetStream(wszObjectID, 
                                                     WPD_RESOURCE_DEFAULT, 
                                                     STGM_READ, 
                                                     &cbOptimalTransferSize,
                                                     &pObjectDataStream);

// 2. Read some data from the resource stream created by GetStream
if (hr == S_OK)
{
  hr = pObjectDataStream->Read(pObjectData, cbOptimalTransferSize, &cbBytesRead);
}

// 3. Do other operations that translate into MTP commands to the device
// and they could result in 0x800700AA as the resource read operation is not complete

To fix this, ensure that IStream::Release() is called to complete or cancel the current read operation before proceeding


IStream* pObjectDataStream = NULL;

// 1. Open the default resource of an object with read access
HRESULT hr = pIPortableDeviceResources->GetStream(wszObjectID, 
                                                     WPD_RESOURCE_DEFAULT, 
                                                     STGM_READ, 
                                                     &cbOptimalTransferSize,
                                                     &pObjectDataStream);

// 2. Read some data from the resource stream created by GetStream
if (hr == S_OK)
{
  hr = pObjectDataStream->Read(pObjectData, cbOptimalTransferSize, &cbBytesRead);
}

// 3. IMPORTANT: Release the IStream if no longer using it to ensure that the read operation
// completes.   
if(pObjectDataStream)
{
    pObjectDataStream->Release();  // If using a CComPtr, set it to NULL
}

// 4. Proceed on to the other operations

If your application is reading resource data from an MTP device, and you are seeing ERROR_BUSY, check that you are always calling Release() on the IStream objects that you have opened. This also applies if you are using smart pointers (e.g. CComPtr<IStream>), in which case you can explicitly set the pointer to NULL to tell the smart pointer to Release() itself before you proceed on to other device operations. This will release the pointer after you have completed your resource read/write operation(s), instead of relying on the IStream smart pointer to get out of scope.

Similarly, if your application is writing resource data to an MTP device, ensure that you're calling IStream::Commit() or IStream::Revert() to complete the write operation.

[June 11, 2007] Thanks to drlily for pointing out that IStream::Close does not actually exist. It should have been IStream::Release for a read IStream, and IStream::Commit, IStream::Revert, or IStream::Release for a write IStream.

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

Object Creation: Required Properties and Debugging Failures

wpdblog — Fri, 02 Mar 2007 21:35:00 GMT

Basic Set of Properties for Folder Creation

When creating a folder object, the following properties are required when calling IPortableDeviceContent::CreateObjectWithPropertiesOnly:

WPD_OBJECT_PARENT_ID: VT_LPWSTR, Parent Object ID
WPD_OBJECT_NAME: VT_LPWSTR, Name of the new object
WPD_OBJECT_CONTENT_TYPE = WPD_CONTENT_TYPE_FOLDER
WPD_OBJECT_FORMAT = WPD_OBJECT_FORMAT_PROPERTIES_ONLY

Some devices (such as the Toshiba MES30VW Gigabeat) require the following additional property when creating a folder object, or the object creation would fail with 0x80040000.

WPD_OBJECT_ORIGINAL_FILE_NAME: VT_LPWSTR, Original file name of the new object

Typically, the original file name property can be set to the same value for WPD_OBJECT_NAME.

Basic Set of Properties for Creating Other Objects

For creating other objects, the set of required properties will vary depending on the Content Type of the object. For creating objects with data (such as a Music or an Image file), use IPortableDeviceContent::CreateObjectsWithPropertiesAndData.

Debugging Object Creation Failures (and Others)

You can run WpdMon to view the traffic between the application and the responses from the device. This helps to zero in on the errors and responses from the driver before the error codes are bubbled up to the application level.

The following capture shows an attempted folder creation on an MTP device (the Creative Zen Vision M) using the WPD Shell Namespace Extension (i.e. Explorer). IPortableDeviceContent::CreateObjectWithPropertiesOnly corresponds to the WPD driver command WPD_COMMAND_OBJECT_MANAGEMENT_CREATE_OBJECT_WITH_PROPERTIES_ONLY.

Date Created and Date Modified are both additional optional properties that the WPD Shell Namespace chooses to specify when creating folder objects.

The client information context is a string identifier that is added automatically by the WPD API in the command parameters. This is generated internally by the WPD API during IPortableDevice::Open, and uniquely identifies the IPortableDevice instance.

Timestamp: 03/02/2007 10:48:25.0806
Operation: (Request) WPD_COMMAND_OBJECT_MANAGEMENT_CREATE_OBJECT_WITH_PROPERTIES_ONLY from Application (4 elements)
WPD_PROPERTY_COMMON_COMMAND_CATEGORY                         = [VT_CLSID   ] WPD_CATEGORY_OBJECT_MANAGEMENT
WPD_PROPERTY_COMMON_COMMAND_ID                               = [VT_UI4     ] 0x2 (Decimal: 2) WPD_PROPERTY_OBJECT_MANAGEMENT_CREATION_PROPERTIES = [VT_UNKNOWN ] IPortableDeviceValues (7 elements)
WPD_OBJECT_PARENT_ID                                         = [VT_LPWSTR ] s10001
WPD_OBJECT_ORIGINAL_FILE_NAME                                = [VT_LPWSTR ] New Folder
WPD_OBJECT_NAME                                              = [VT_LPWSTR ] New Folder
WPD_OBJECT_DATE_CREATED                                      = [VT_DATE    ] 2007/3/2 10:48:25.0
WPD_OBJECT_DATE_MODIFIED                                     = [VT_DATE    ] 2007/3/2 10:48:25.0
WPD_OBJECT_CONTENT_TYPE                                      = [VT_CLSID   ] WPD_CONTENT_TYPE_FOLDER
WPD_OBJECT_FORMAT                                            = [VT_CLSID   ] WPD_OBJECT_FORMAT_PROPERTIES_ONLY
WPD_PROPERTY_COMMON_CLIENT_INFORMATION_CONTEXT               = [VT_LPWSTR ] {F86BC3B3-D205-463F-80CF-DB43C51D4FE2}

Timestamp: 03/02/2007 10:48:25.0806
Operation: (Response) IPortableDeviceValues from Driver (1 elements)
WPD_PROPERTY_COMMON_HRESULT                                  = [VT_ERROR   ] 0x800700AA

Even though the application has provided all the required property values (and then some), the WPD driver still failed the command with 0x800700AA (ERROR_BUSY). This means that the driver is busy servicing other requests, and the application should try the request again later. By using WpdMon, we are able to determine that the failure in CreateObjectWithPropertiesOnly had originated from the driver or the device.

This post provides more details on ERROR_BUSY.

The same technique of viewing WpdMon traffic can be applied to diagnosing error responses returned from other methods in the WPD API to determine which level the error appeared (the application, the WPD API, or the driver/device). The trick is to map the WPD API call to the driver command. It is a straightforward mapping, for example:

IPortableDeviceProperties::GetValues => WPD_COMMAND_OBJECT_PROPERTIES_GET

More tips and tricks for using WpdMon.

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

Enabling Your WPD application for AutoPlay on Windows Vista

wpdblog — Fri, 23 Feb 2007 05:40:00 GMT

The power of WPD derives from built-in extensibility mechanisms and scenarios around content type and device function. A good example is AutoPlay, which has been updated in Windows Vista to support WPD scenarios. Instead of providing the ability to only register for devices as a whole, AutoPlay now allows a generic scheme where each WPD device provides a list of content and functional categories that it supports. Application handlers can register for each type of content and function category that they are interested in.

Overview of the WPD AutoPlay Registration Scheme

The WPD AutoPlay scheme is defined as follows:

Source

The list of content types in this group indicates what the device can provide.
This allows for applications that are interested in browsing or acquiring device contents to be registered for devices that can provide that content.

Sink

The list of content types in this group indicates what the device can accept.
This allows for applications that are interested in putting content on the device to be registered for devices that can receive that content.

Function

The list of categories in this group indicates what functions the device supports.
This allows for applications that are interested in device functionality (e.g. ability to send/receive SMS messages) to be registered for devices that can provide that function.

Note that this scheme is not limited to the content the device currently has on its storage, but rather, what the device is capable of storing/doing.

When a device arrival event occurs, AutoPlay will walk the list of capabilities reported by the WPD driver (e.g. "Source for Audio"), and for each type found on the list, AutoPlay will walk the list of registered handlers to find a match. The lists of handlers for the supported types are merged into a single list of handlers and presented to the user in the AutoPlay Dialog.

Registering Your WPD Application for AutoPlay

To register for WPD AutoPlay events, applications need to add themselves to the appropriate WPD entry under the AutoPlayHandlers\EventHandlers key. To illustrate a simple application registration, suppose your WPD application can transfer Music to a WPD device, and can receive Music and Photos from a WPD device. You could register your application handler like this:

[HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\AutoPlayHandlers\EventHandlers\Wpd]:

Sink
{4AD2C85E-5E2D-45E5-8864-4F229E3C6CF0} -> WPD_CONTENT_TYPE_AUDIO
MyWpdSendMusicHandler, REG_SZ, (Empty)

Source
{4AD2C85E-5E2D-45E5-8864-4F229E3C6CF0} -> WPD_CONTENT_TYPE_AUDIO
MyWpdAcquirePhotoMusicHandler, REG_SZ, (Empty)

{EF2107D5-A52A-4243-A26B-62D4176D7603} -> WPD_CONTENT_TYPE_IMAGE
MyWpdAcquirePhotoMusicHandler, REG_SZ, (Empty)

Both [MyWpdAcquirePhotoMusicHandler] and [MyWpdSendMusicHandler] are normal Autoplay registrations in HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\AutoplayHandlers\Handlers. For more details, refer to this MSDN article (suggested section: Autoplay V2 Registration Mechanism).

The "EventHandlers\Wpd\..." entries are defined using the content type and functional category GUIDs (e.g. {EF2107D5-A52A-4243-A26B-62D4176D7603}), not the symbolic names (i.e. WPD_CONTENT_TYPE_IMAGE). This is designed to support extensibility for custom content types and functional categories that devices and applications can register. Published WPD GUID values and their associated symbolic names are defined in PortableDevice.h, available in the Windows SDK.

"Source" and "Sink" are content transfers relative to the device, not the application. In the example above, your application is registering for AutoPlay events for a WPD device that can do one or more of the following:

Receive music content from your application
Provide image or audio content to your application

If your application is a general purpose WPD application that wants to register for any device, you can add a handler entry under the WPD_CONTENT_TYPE_ALL, e.g. in ...\Wpd\Source\{80E170D2-1055-4A3E-B952-82CC4F8A8689}. Note that this will also register your application to handle devices that support custom content types.

AutoPlay for Functional Category

Function registration provides a great way for your WPD application to register to handle devices that support specific commands or scenarios that are organized by functional category.

For example, if your application interfaces with cameras that support image capture, register your handler for WPD_FUNCTIONAL_CATEGORY_STILL_IMAGE_CAPTURE, so that when a device that supports this functional category is connected, your app can be present in the AutoPlay dialog:

[HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\AutoPlayHandlers\EventHandlers\Wpd]:

Function
{613CA327-AB93-4900-B4FA-895BB5874B79} -> WPD_FUNCTIONAL_CATEGORY_STILL_IMAGE_CAPTURE
MyWpdImageCaptureHandler, REG_SZ, (Empty)

Can I register AutoPlay for other device events?

AutoPlay only supports registration for device arrival events. Your application can still receive WPD events and custom events using IPortableDevice::Advise.

What about Windows XP?

The granular WPD Source/Sink/Function AutoPlay registration functionality is only available on Windows Vista. On Windows XP, the AutoPlay registration mechanisms are documented in this MSDN article and in the MSDN library.

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.

Which Portable Devices?

wpdblog — Sat, 27 Jan 2007 11:46:00 GMT

What devices does WPD support?

A WPD application (e.g. the WPD API Sample) on Windows XP (with the pre-requisites installed) can connect to these devices:

Devices (e.g. portable media players, cameras, some phones) that support Media Transfer Protocol (MTP).
Devices that connect using third party or vendor provided WPD drivers.

A WPD application on Windows Vista can connect to even more devices:

Devices (e.g. portable media players, cameras, some phones) that support MTP.
Devices that connect using third party or vendor provided WPD drivers.
Devices (e.g. cameras, camcorders) that support Picture Transfer Protocol.
USB Mass Storage Devices.
Windows CE devices via IPortableDeviceManager::GetPrivateDevices()

In both cases, the WPD Shell Namespace Extension is also a WPD application, so you can check whether your device is visible to WPD by browsing to it using Explorer ("My Computer").

What about a Smartphone or PocketPC device?

On Windows Vista, Windows CE devices register the private WPD interface GUID, and can be enumerated in WPD by calling IPortableDeviceManager::GetPrivateDevices(). These devices connect to Explorer using the WPD RAPI driver, which provides device browsing functionality. Content sync is implemented through a different channel. The WPD RAPI driver is not available on Windows XP.

On Windows Vista and Windows XP, to enumerate content on a Windows CE device for Windows Media Player applications, you can use the Windows Media Device Manager (WMDM) APIs.

How do I install WPD?

On Windows XP, WPD is available when any one of these pre-requistes are installed:

Windows Media Player 11
The redistributable package bundled with Windows Media Format 11 SDK (see release notes)

On Windows Vista, WPD is supported natively for SKUs that include Windows Media Player (e.g. Home Basic, Home Premium, Ultimate Edition ...)

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.