MTP Responder Development Guide

MTP Responder Development Guide Windows Embedded CE 6.0 R3 Technical Article Writers: Mark McLemore, Harold Drews Technical Reviewer: Alex Bussmann, Kwan-Sub Shin, Vasu Pai Published: December 2009 Applies To: Windows Embedded CE 6.0 R3 Abstract Device Stage, introduced in Windows 7, helps users discover and use devices that are connected to their personal computers. MTP Responder for Windows Embedded CE 6.0 R3 adds functionality to Windows Embedded CE 6.0 R3 that helps OEMs create devices that are compatible with Device Stage. If you are creating a device that connects to a computer running Windows 7 through a USB or TCP/IP connection, MTP Responder for Windows Embedded CE 6.0 R3 gives you the necessary enhancements to build Windows 7-compatible Device Stage support into your device. As an OEM, you can build Windows Embedded CE 6.0 R3 devices that improve the experience Windows 7 users have with their devices. For example, you can make it easier for users to find the representation of their device on the computer, you can provide users with information that improves their experience with the device, and you can present the status information about the device and the tasks that users can perform with the device, all in a consolidated view. MTP Responder for Windows Embedded CE 6.0 R3 provides Media Transfer Protocol (MTP) functionality to support Device Stage. Although MTP Responder does not support media metadata transfer, it includes storage for MTP files and folders so that users can browse and manage files on their devices and transfer files to and from their computers. You can modify and extend MTP Responder to support additional MTP commands and properties. By using an MTP extension, you can define new MTP operations, properties, and object formats that are not part of the MTP specification. MTP Responder also prepares your device to meet the Windows Logo requirements for devices in the Other Portable Devices category. MTP Responder Development Guide 1 Microsoft ©2009 Introduction MTP Responder for Windows Embedded CE 6.0 R3 provides enhanced Media Transfer Protocol (MTP) functionality to support Windows 7 Device Stage. Device Stage offers a central location in Windows for your users to discover and use their devices. When you include Device Stage support in your device, users can get detailed information about the device, copy files to and from the device, run device-specific tasks, read a product manual, and buy accessories for the device, all in one handy location. Device Stage provides these capabilities without requiring the user to download or install software. For more information about Device Stage, see the Windows Device Experience site (http://go.microsoft.com/fwlink/?LinkId=132146). Device Stage communicates with your device over MTP; therefore, a device must implement MTP to support Device Stage. MTP enables an application on a computer, the MTP initiator, to control a portable device, the MTP responder, and transfer digital media content and metadata between the computer and the device. The MTP initiator and the MTP responder communicate over a communications link, or MTP transport, typically a USB or TCP/IP connection between the computer and the device. Devices participate in Device Stage by implementing an MTP responder that can handle Device Stage requests from an MTP initiator over one or more MTP transports. The MTP responder functionality provided in this release is specifically designed to support the MTP initiator that is included in Windows 7 for Device Stage. This guide describes the Device Stage support provided by the MTP Responder, the functionality of each MTP Responder catalog item, MTP Responder limitations, and prerequisites for including MTP Responder in your device. A detailed step-by-step Device Stage implementation section explains how to install MTP Responder, how to configure device registry settings, how to add OEM Adaptation Layer (OAL) support, how to create presentation elements, and how to test your device with Device Stage. A section on the MTP Responder design helps you learn more about the MTP Responder implementation, modify the provided source code to add customizations and extensions, and download additional software development kits and programming documentation for MTP and Device Stage development. Device Stage Support When you include MTP Responder for Windows Embedded CE 6.0 R3 in your device, you can choose from one of two supported levels of Device Stage presentation: baseline or custom. The baseline presentation is the simplest and most essential device presentation level, while the custom presentation offers a richer set of features for using your device. Baseline presentation displays a device icon, some textual information about your device, and basic status information. MTP Responder provisions your device to communicate this essential information about the device and its contents to Device Stage. Using this information, MTP Responder provides the following basic Device Stage capabilities: • View battery status Device Stage displays battery status information if your device reports this information. • View storage space Device Stage displays the amount of storage space available on your device if your device reports this information. MTP Responder Development Guide Microsoft ©2009 • Browse files File browsing capability lets a user manage files and folders on a device using an Explorer window on the computer and transfer files between the device and the computer. These basic capabilities meet the minimum functionality requirements for Windows Log certification for the Device Stage Other Portable Devices category. For more about Device Stage categories, see the section Windows Logo Certification below. Your device will automatically create a baseline presentation when you include MTP Responder catalog items in your OS design, configure registry settings with information about your device, and implement OAL support for battery and storage status. The custom presentation extends the baseline presentation by adding enhancements such as branding logos, additional presentation images, custom tasks for managing the device, and links to provide users with access to product registration, support, manuals, applications, and accessories. To create a custom presentation, you first configure your device to support the baseline presentation, and then you create a device metadata package for installation on the user’s computer to add additional end-user features. You can also implement extra functionality in your device to support custom Device Stage tasks as part of your custom presentation. Windows Logo Certification Windows classifies devices into categories, based on the functionality of the device. The MTP functionality in MTP Responder for Windows Embedded CE 6.0 R3 meets Windows Logo certification requirements for a new category of devices called Other Portable Devices. This category includes portable navigation devices, consumer internet devices, digital picture frames, e-book readers, portable gaming devices, and set-top boxes. The Other Portable Devices category is a member of the Portable Devices class. The Portable Devices class also contains categories for cellular phones, digital cameras, and portable media players. Each device category has unique requirements that a device must meet to be compatible with Device Stage and qualify for a Windows Logo. The MTP components included in MTP Responder for Windows Embedded CE 6.0 R3 fulfill requirements only for the Other Portable Devices category; however, you can extend the included MTP Responder source code to meet the requirements for other Windows device categories. For more information about Windows Logo certification and the requirements for device certification, see the Windows Logo Program (http://go.microsoft.com/fwlink/?LinkId=8772). MTP Responder Components MTP Responder is comprised of several major functional blocks; the MTP Responder Stack, MTP Storage, and MTP Transports. You select MTP Responder functionality from the Catalog Items View in Platform Builder, where several new catalog items are presented: MTP Responder (default), MTP Responder (minimal), MTP USB Transport, and MTP IP Transport. You cannot select MTP Storage as a separate catalog item; it is included only when you select the MTP Responder (default) catalog item. For more information about catalog items, see the section Step 2 Add Device Stage Catalog Items to Your OS Design. MTP Responder Development Guide Microsoft ©2009 MTP Responder Stack The MTP Responder Stack provides MTP router, dispatcher, and command handler functionality to support Device Stage communication with the MTP initiator included in Windows 7. The MTP Responder Stack communicates with the user’s computer through one or more MTP transports; you can configure the MTP Responder Stack to use a USB connection, a TCP/IP connection, or both. You add MTP Responder Stack functionality by adding one of the MTP Responder Stack catalog items in the Catalog Items View of Platform Builder. To support Device Stage, you must include the MTP Responder Stack in your OS design. MTP Storage MTP Storage adds file browsing capability over MTP by storing information about MTP objects on your device. MTP Storage is optional for Device Stage support; however, file browsing over MTP is a minimum requirement for Windows Logo certification. For more about Windows Logo certification, see Windows Logo Certification. MTP Transports The MTP USB Transport provides MTP connectivity between the device and the user’s computer through a USB connection. The MTP IP Transport provides MTP connectivity between the device and a user’s computer through a TCP/IP connection. You can use one or both of these transports in your device, but you must enable at least one transport to support Device Stage. MTP transports can be used interchangeably. Users can copy files between the device and a Windows 7 computer over a USB connection or a TCP/IP connection. Also, users have the ability to perform the same file browsing and device management operations over a TCP/IP connection to the device as with a USB connection. Limitations MTP Responder for Windows Embedded CE 6.0 R3 has several limitations with respect to file formats, properties, synchronization, and storage, which are described below. However, you can modify the provided MTP Responder source code to support additional file properties and formats, add synchronization support, or replace the included MTP Storage component with your own storage implementation. For more information about these modifications, see the MTP Storage section of MTP Responder Design. File Formats and Properties MTP Storage supports only two object formats: Undefined (files) and Association (folders). Your device may store many different file formats (.mp3, .jpg, and so on), but MTP Storage treats them all as Undefined format. As a result, MTP Responder ignores media properties found in video and audio files. • Properties that are specific to media files, such as Artist, Title, and Album Name cannot be stored on the device. • Windows Media Player cannot play files transferred over MTP from the device because these files no longer have the properties that characterize media files. MTP Responder Development Guide Microsoft ©2009 Windows Media Player only recognizes devices that support media file formats and properties. Although MTP Storage does not support media file properties, media files managed by MTP Storage contain a minimum set of properties, such as the file name and file type, that must be present for use over MTP connections. File Synchronization MTP Responder does not provide a mechanism for users to compare the contents of files on the device with files on a computer or update files in either location based on that comparison. Closed Storage Implementation Applications cannot access storage data that is created and managed by MTP Storage; only MTP Responder Stack can access files and object metadata managed by MTP Storage. Prerequisites To build support for Device Stage into your device by using MTP Responder for Windows Embedded CE 6.0 R3, you use the tools that you normally use for Windows Embedded CE Development. You use a few additional tools and software development kits to test your Device Stage presentation and create and test device metadata packages. Windows Embedded CE To support Device Stage, you must use Windows Embedded CE 6.0 R3. Earlier releases of Windows Embedded CE do not include support for Device Stage. MTP Responder for Windows Embedded CE 6.0 R3 includes an MTP responder and related functionality that is designed for servicing Windows 7 Device Stage requests. You use the Visual Studio integrated development environment (IDE) with the Windows Embedded CE Platform Builder toolset to design, create, build, test, and debug your Windows Embedded CE-based run-time image. For more information about Windows Embedded CE development and Platform Builder, see the Platform Builder User’s Guide (http://go.microsoft.com/fwlink/?LinkId=178104). Metadata Tools To support the Device Stage custom presentation, you must assemble the files that make up a Device Stage custom presentation into a device metadata package for installation on the user’s computer (the baseline presentation does not require a device metadata package). For more information about creating a device metadata package for a custom device presentation, download the Windows Device Experience Development Kit (http://go.microsoft.com/fwlink/?LinkId=178109). Windows 7 Windows 7 provides an MTP initiator for testing your device in addition to the environment for building and testing device metadata packages. MTP Responder Development Guide Microsoft ©2009 Development Steps To configure your Windows Embedded CE 6.0 R3 OS design to support Device Stage, follow these steps. 1. Download and install MTP Responder for Windows Embedded CE 6.0 R3, available from the Windows Embedded CE 6.0 Download Center (http://go.microsoft.com/fwlink/?LinkId=179042). 2. Create a baseline Device Stage presentation, which displays some identifying information about your device, your device icon, and a standard set of status elements and tasks. a. Choose and include MTP Responder catalog items in your OS design. b. Create a device icon image that represents your device. c. Populate device registry keys with information about your device. d. Develop your OEM Adaptation Layer (OAL) to support Device Stage status and task elements. 3. Optionally, create a custom Device Stage presentation, which includes a user interface for your device that installs on Windows 7. a. Create a device metadata package that installs on the user’s computer. b. Develop any custom tasks in your device to support your device metadata package. c. Submit your device for Windows Logo certification. d. Submit your device metadata package to Microsoft for signing. When you complete steps 1 through 2 above, Device Stage generates a baseline presentation for your device automatically. When you complete steps 1 through 3 above, Device Stage displays your device with a custom presentation. Windows Logo certification and metadata signing are required only for a custom presentation. If you create a custom presentation, you can add status displays and tasks that are specific to your device, promote your brand by adding custom graphic elements, and provide users with links to product enhancements, registration sites, support sites, and product manuals. If you don’t create a user interface, then Device Stage shows the baseline presentation for your device. The steps below and the links to related Web sites, software development kits, and additional documentation will help you prepare your device for Device Stage. Device Stage Implementation By using MTP Responder, you take advantage of the MTP class driver support provided in Windows, thereby reducing the need to design, develop, and support a proprietary device connectivity solution. You provide a user with a simpler connection experience because no additional software installation is necessary to communicate with Windows. To add Device Stage support to your device by using MTP Responder for Windows Embedded CE 6.0 R3, follow these steps: Step 1 Verify System Requirements MTP Responder for Windows Embedded CE 6.0 R3 requires the following minimum system configurations. MTP Responder Development Guide Microsoft ©2009 Windows Vista If your computer runs on 32-bit Windows Vista, the following hardware and software is required. Hardware Requirements • Personal computer with a 933 MHz or faster processor (2 GHz recommended) • 512 megabytes (MB) of RAM (1 GB recommended) • 18 gigabytes (GB) of available space on installation drive • 1 GB of available space on system drive • DVD-ROM drive • Monitor that supports 1024 x 768 screen resolution with 16-bit color Software Requirements • Microsoft Visual Studio 2005 • Visual Studio 2005 Service Pack 1 • Visual Studio 2005 Service Pack 1 Update for Windows Vista • Windows Embedded CE 6.0 R3 Windows Embedded CE 6.0 is available from the Windows Embedded CE 6.0 Download Center (http://go.microsoft.com/fwlink/?LinkId=179042). Windows XP If your computer runs on 32-bit Windows XP Service Pack 2, the following hardware and software is required. Hardware Requirements • Personal computer with a 933 MHz or faster processor (2 GHz recommended) • 512 megabytes (MB) of RAM (1 GB recommended) • 18 gigabytes (GB) of available space on installation drive • 1 GB of available space on system drive • DVD-ROM drive • Monitor that supports 1024 x 768 screen resolution with 16-bit color Software Requirements • Microsoft Visual Studio 2005 • Visual Studio 2005 Service Pack 1 • Windows Embedded CE 6.0 R3 Windows Embedded CE 6.0 is available from the Windows Embedded CE 6.0 Download Center (http://go.microsoft.com/fwlink/?LinkId=179042). MTP Responder Development Guide Microsoft ©2009 Step 2 Add Device Stage Catalog Items to Your OS Design To add Device Stage support to your OS design, add one or more of the following catalog items and SYSGEN variables to your OS design. Use the MTP Responder (default) catalog item unless you intend to modify or replace the provided transport components. If you do not use MTP Responder (default), you must include MTP Responder (minimal) and at least one transport or use equivalent components of your own design. Table 1 - SYSGENs Catalog item SYSGEN variable Description MTP Responder (default) SYSGEN_MTP_RESPONDER Adds all Device Stage components: MTP Responder Stack, MTP Storage, and all MTP transports. Includes the software components necessary to add Device Stage support on a CE 6.0 R3 device. MTP Responder (minimal) SYSGEN_MTP_RESPONDER_MIN Adds only the MTP Responder stack; does not add MTP Storage or MTP transports. MTP USB Transport SYSGEN_MTP_RESPONDER_USB Adds MTP over USB transport functionality. MTP IP Transport SYSGEN_MTP_RESPONDER_IP Adds MTP over IP transport functionality. For information about selecting catalog items, see Adding Catalog Items to an OS Design (http://go.microsoft.com/fwlink/?LinkId=179330). For information about setting SYSGEN variables, see Setting or Clearing a Sysgen Variable (http://go.microsoft.com/fwlink/?LinkId=179331). Step 3 Configure Registry Settings in Your OS Design To configure registry settings in