Readme for Windows Portable Devices

  • Article

October 2006

This documentation provides late-breaking or other information that supplements the documentation for Microsoft Windows Portable Devices.

Contents

Build information

Minimum system requirements

Known issues

  • Support in Windows Vista
  • Support in Windows XP
  • The WpdInfo Tool
  • Requirements for Windows Media DRM-enabled applications
  • Access Control
  • WPD_DEVICE_SUPPORTED_DRM_SCHEMES
  • IPortableDeviceManager::GetDeviceProperty

Legal notice

Build information

To create a Windows Portable Devices application, you must have the Windows Software Development Kit (SDK) installed on your computer. The required headers and libraries appear in the following list.

  • PortableDeviceGuids.lib
  • PortableDevice.h
  • PortableDeviceTypes.h
  • PortableDeviceApi.h
  • Any other libraries and headers required by your application to consume or render media files.

Minimum system requirements

Windows Portable Devices are supported in both the Windows Vista and Windows XP operating systems. Your application will compile and link on either operating system using the supplied headers and libraries.

Known issues

Support in Windows Vista

For all but the N SKUs of Windows Vista, the WPD runtime is bundled as part of the Windows Vista operating system.

For your application to run on the N SKUs of Windows Vista, the user will need to install the Media Restore Pack from the Microsoft Download Center. (The restore pack will install Windows Media Player and its components. These components include the WPD runtime.)

Support in Windows XP

For your application to run in Windows XP, the user will need a copy of the Windows Media Format 11 runtime on their machine. You can redistribute this runtime with your WPD application. (The runtime is found in a folder of redistributables in the Windows Media Format SDK.)

The WpdInfo Tool

The WpdInfo.exe tool is a Windows-based application that WPD driver developers use to test the functionality in their driver. Application developers may use this tool as well to familiarize themselves with common device operations. This tool, as well as several others, ships as part of the Windows Drivers Kit. For information about downloading this kit, refer to MSDN.

Requirements for Windows Media DRM-Enabled Applications

To create a Windows Media Digital Rights Management (DRM)-enabled application, you must have the headers and libraries described in the Build information section of this document. In addition, the application will need to supply additional properties in the client information when opening the device.

The two additional properties that are required to enable Windows Media DRM-protected content transfers are described in the following table.

Property Description
WPD_CLIENT_WMDRM_APPLICATION_PRIVATE_KEY Specifies the application's private key.
WPD_CLIENT_WMDRM_APPLICATION_CERTIFICATE Specifies the application's certificate.

These properties must be supplied in the application's client information when the device is opened with the IPortableDevice::Open method. When these properties are supplied, the Windows Portable Devices API allows protected content transfers. If the application has provided a certificate and private key, the API will CoCreate the IPortableDeviceWMDRM component and initialize it with an instance of itself (IPortableDevice) and the client information from the application (IPortableDeviceValues).

The WMDRMDEVICEAPP_USE_WPD_DEVICE_PTR constant which appears in the file PortableDevice.h is defined for internal use only. It is required by the IPortableDeviceWMDRM component.

You can obtain a private key and certificate from the Windows Media licensing website.

Access Control

The WPD driver stack is slightly different from many other driver stacks in that it is the payload of the WPD message that contains the WPD command, not the IOCTL (in most driver stacks, the IOCTL is the command). This is not unique, but it means that WPD has the following two IOCTLs:

IOCTL Description
IOCTL_WPD_MESSAGE_READ_ACCESS A read-only IOCTL for all WPD commands that require read-only access.
IOCTL_WPD_MESSAGE_READWRITE_ACCESS A read-write IOCTL for all WPD commands that require read-write access.

These IOCTLs, and the supporting WPD_CONTROL_FUNCTION_GENERIC_MESSAGE constant, are defined in the file PortableDevice.h.

WPD_DEVICE_SUPPORTED_DRM_SCHEMES

The file PortableDevice.h contains two constants that can be returned by the WPD_DEVICE_SUPPORTED_DRM_SCHEMES property to identify supported formats. These constants, and their significance, are described in the following table.

Constant Description
PORTABLE_DEVICE_DRM_SCHEME_WMDRM10 Returned when the device supports Windows Media Digital Rights Management 10 for Portable Devices.
PORTABLE_DEVICE_DRM_SCHEME_PDDRM Returned when the device supports Portable Device Digital Rights Management.

IPortableDeviceManager::GetDeviceProperty

The file PortableDevice.h contains five constants that can be returned by the IPortableDeviceManager::GetDeviceProperty method. These constants identify types of data returned by the method in the caller-allocated buffer. The following table lists each constant and describes its significance.

Constant Description
PORTABLE_DEVICE_ICON A predefined name for a REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ value that indicates the location of the device icon file or device icon resource.

This value is either in the form "file.dll, resourceID" or a full file path to an icon file. For example: "x:\file.ico".
PORTABLE_DEVICE_NAMESPACE_TIMEOUT A predefined name of a REG_DWORD value that indicates the amount of time in milliseconds that the WPD Namespace Extension will keep its reference to the device open under idle conditions.
PORTABLE_DEVICE_NAMESPACE_EXCLUDE_FROM_SHELL A predefined name of a REG_DWORD value that indicates whether the device should be shown in the Explorer view. A value of 0 indicates that the device should be shown; a non-zero value indicates that it should not.

The default is zero for WPD devices identified by GUID_DEVINTERFACE_WPD; it is non-zero for WPD devices identified by GUID_DEVINTERFACE_WPD_PRIVATE. (All private devices are excluded from the WPD Namespace by default.)
PORTABLE_DEVICE_NAMESPACE_THUMBNAIL_CONTENT_TYPES A predefined name of a REG_SZ or REG_MULTI_SZ value containing content type GUIDs. These GUIDs indicate which content types the portable device namespace should attempt to generate thumbnails for automatically when placing new content on the device.

Each GUID should be a string representation of a GUID that corresponds to the thumbnail's content type. This GUID has the form '{00000000-0000-0000-0000-000000000000}'.

By default, the portable device namespace generates thumbnails for the WPD_CONTENT_TYPE_IMAGE only. An application can prevent the default behavior for a particular device by setting this registry value to an empty string.
PORTABLE_DEVICE_IS_MASS_STORAGE A predefined name of a REG_DWORD value that indicates whether a Portable Device is a Mass Storage Class (MSC) device. This is used to avoid duplication of the device in certain views and scenarios that include both file systems and Portable Devices.

If this value is 0, the device is not an MSC device; if this value is 1, the device is an MSC device. (The default value is 0.)

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, places or events is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Windows Server, Windows Vista, Active Directory, ActiveSync, ActiveX, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, Expression, FrontPage, Internet Explorer, HighMAT, JScript, Microsoft Press, MSN, Outlook, PlaysForSure logo, PowerPoint, SideShow, Visual Basic, Visual C++, Visual InterDev, Visual J++, Visual Studio, WebTV, Windows Media, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

All other trademarks are property of their respective owners.