Device Metadata Package Pipeline

Device Metadata Package Pipeline

September 28, 2012

Abstract

This paper describes how to install and use a device metadata package for the Windows 7 and Windows 8 device experience features. This document is intended to be used both as a tutorial and as a reference guide. It provides information on how to install a metadata package, how to debug device metadata package errors, how the Device Metadata Retrieval Client (DMRC) selects a metadata package, and how the DMRC uses the metadata cache.

This information applies to the following operating systems:

Windows 8 Windows 7

References and resources discussed here are listed at the end of this paper.

The current version of this paper is maintained on the Web at: Device Metadata Package Pipeline

Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2012 Microsoft. All rights reserved.

http://msdn.microsoft.com/en-us/library/windows/hardware/gg463157

Device Metadata Package Pipeline - 2

Document HistoryDate ChangeSeptember 28, 2012 Updated to reflect rebranding

June 27, 2012 Updated information about ETW Events

April 9, 2012 Updated Windows 8 terminologyFebruary 28, 2012 Updated for Windows 8 Consumer PreviewJanuary 22, 2010 Noted that a guest account cannot access metadata packages on the

WMIS server.Added guidance on using a separate INF DDInstall section if your device also installs on Windows versions earlier than Windows 7.Added information about the DMRC device metadata cache.Adjusted the debugging information to reflect just one Event Viewer channel (DeviceMetadata/Debug).

July 1, 2009 Corrected XML element namesJune 1, 2009 Fixed an error of the INF example with COPYFLG_NODECOMP flag

Added the section “How the DMRC Selects A Device Metadata Package”

November 5, 2008 First publication

ContentsDevice Metadata Package Installation...........................................................................4

Add Metadata Packages to Offline Windows Image..................................................4Install Metadata Packages on a Running Instance of Windows.................................4

Install Metadata Package from the WMIS Server.................................................4Install Metadata Packages by Using an Application..............................................5Install Metadata Packages by Using an INF File in a Driver Package.....................5

Apply the device metadata package to your system for testing....................................6Signature of the device metadata package and test mode............................................7How the DMRC Selects a Device Metadata Package.....................................................7How the DMRC Determines Whether to Search the WMIS Server..............................10

Best Practices for Testing Download of Device Metadata Packages...................12Device Metadata Package Installation Debug..............................................................12

Check whether the device metadata package is installed or not............................12Debug the device container properties by Using Ddodiag.exe................................13

Run Ddodiag.exe.................................................................................................13Debug by Using Event Tracing for Windows (ETW) in Windows 7...........................14

View Device Metadata/Debug ETW Events in Event Viewer...............................14Device Metadata/Debug ETW Events.................................................................15

Debug by Using Event Tracing for Windows (ETW) in Windows 8...........................16View Device Metadata/Debug ETW Events in Event Viewer...............................16Device Metadata/Debug ETW Events.................................................................17

Debug by Using Problem Reports (Action Center)...................................................20View a Problem Report in Action Center.............................................................20Interpret a Problem Report.................................................................................21

Determine the Device Metadata-Related Error Code..............................................21Appendix......................................................................................................................23

Debug device setup by Using Event Tracing for Windows (ETW) in Windows 8......23

September 28, 2012© 2012 Microsoft Corporation. All rights reserved.


View Device Setup ETW Events in Event Viewer.................................................23Device setup ETW Events....................................................................................23

Glossary.......................................................................................................................30Resources....................................................................................................................31



Device Metadata Package InstallationYou can add device metadata packages to an offline Windows image, or you can install additional device metadata packages while Windows is running.

Add Metadata Packages to Offline Windows ImageTo add device metadata packages to an offline Windows image, copy the packages (for example, GUID.devicemetadata-ms) to the local metadata store (%PROGRAMDATA%\Microsoft\Windows\DeviceMetadataStore\<locale>).

Remarks:

You must create the <locale> folder based on the metadata package’s locale in the local metadata store, for example, %PROGRAMDATA%\Microsoft\Windows\DeviceMetadataStore\EN-US. Copy the appropriate locale metadata package to the subfolder. For example, copy an EN-US metadata package to the EN-US subfolder, and copy an EN metadata package to the EN subfolder.

Multiple-locale device metadata packages should also be copied to the locale folder. The locale is defined in packageinfo.xml, which is used only when the device metadata package is loaded to a Windows 7 computer. For example, the package should be copied to the EN-US folder if the locale in packageinfo.xml is EN-US.

Install Metadata Packages on a Running Instance of WindowsYou can install device metadata packages on a running instance of Windows in three different ways:

Install metadata packages from the Windows Metadata and Internet Services (WMIS) server.

Install metadata packages by using an application.

Install metadata packages by using an INF file in a driver package (which we do not recommend).

All three ways use the same background processes and copy the metadata packages to the local metadata store.

Install Metadata Package from the WMIS Server

When Windows detects a new device, it queries the WMIS online server for a metadata package for the device. If a device metadata package is available, the Device Metadata Retrieval Client (DMRC) that runs on the local computer downloads the package from the WMIS server and installs the package on the local computer.

You can submit your metadata in the Dashboard of the Hardware Development and Desktop App Development areas of the Windows Dev Center. See http://msdn.microsoft.com/library/c71750f4-885f-425a-a3ad-29740a1cb0bb to understand the Logo requirements and whether they apply to your submission. After the Dashboard validates your metadata package, it will be available to WMIS for download requests that DMRC makes on any computer that runs Windows 7.


http://msdn.microsoft.com/library/c71750f4-885f-425a-a3ad-29740a1cb0bb


To support the device metadata package installation scenario with the hardware-first driver installation scenario, we recommend that you use this method to provide metadata packages.

Note: If a user accesses a computer by using a guest account, the DMRC cannot retrieve device metadata packages from the WMIS server for that user.

Install Metadata Packages by Using an Application

To install metadata packages, your application or installation application should follow these steps:

1. Get the local metadata store path by calling SHGetKnownFolderPath. The knownfolderID for the local metadata store is {5CE4A5E9-E4EB-479D-B89F-130C02886155}.

2. Copy the metadata package to the local metadata store by calling CopyFile.

Remarks: You must have administrator privileges when you copy metadata packages.

You must copy metadata packages to the correct locale subfolder. For example, copy a metadata package for ”EN-US” to %PROGRAMDATA%\Microsoft\Windows\DeviceMetadataStore\EN-US.

If the local metadata store does not have a subdirectory for the locale, the application must create it. If you use the CopyFile function, it creates the folder if there is no subdirectory for the locale.

Install Metadata Packages by Using an INF File in a Driver Package

Note: Because we do not provide support for the INF file method for installing metadata packages, we strongly recommend that you install from the WMIS server. However, if you choose to use an INF file, read this section thoroughly and make sure that you understand the risk.

To install metadata packages from a driver package, your INF file copies the metadata packages. For more information about INF files, see “INF Files” in the Windows Driver Kit (WDK).

Note: If your driver package is used to install devices on Windows versions earlier than Windows 7, you must use a separate INF DDInstall section that contains your metadata-related INF directives. You must specify this section name in the INF Models section by using a TargetOSversion decoration that specifies an OSMajorVersion and OSMinorVersion value for Windows 7. If you do not use a separate DDInstall section for Windows 7, your driver package installation shows a signature alert because the COPYFLG_NODECOMP does not work on Windows versions earlier than Windows 7. For more information about creating decorated INF sections, see “Creating INF Files for Multiple Platforms and Operating Systems” in the WDK.



The following example shows how the DestinationDirs and DDInstall sections specify the paths for the metadata package operations:

[SourceDisksNames]1 = %Media_Description%,,,\MetadataPackage ;

[SourceDisksFiles.NTx86]GUID1.devicemetadata-ms= 1,, ;A metadata package file for EN-USGUID2.devicemetadata-ms= 1,, ;A metadata package file for AR-SAGUID3.devicemetadata-ms= 1,, ;A metadata package file for JA-JP

[DestinationDirs]COPYMETADATA_EN-US = 24, \ProgramData\Microsoft\Windows\DeviceMetadataStore\EN-US ;COPYMETADATA_AR-SA = 24, \ProgramData\Microsoft\Windows\DeviceMetadataStore\AR-SA ;COPYMETADATA_JA-JP = 24, \ProgramData\Microsoft\Windows\DeviceMetadataStore\JA-JP ;. . .

[DeviceInstall.NTx86]CopyFiles=COPYMETADATA_EN-USCopyFiles=COPYMETADATA_AR-SACopyFiles=COPYMETADATA_JA-JP

[COPYMETADATA_EN-US]GUID1.devicemetadata-ms,,,0x00000800 ;COPYFLG_NODECOMP[COPYMETADATA_AR-SA]GUID2.devicemetadata-ms,,,0x00000800 ;COPYFLG_NODECOMP[COPYMETADATA_JA-JP]GUID3.devicemetadata-ms,,,0x00000800 ;COPYFLG_NODECOMP

Remarks:

You must copy all metadata packages in the driver package to the correct folder in the Local Device Metadata Store to support dynamic locale change.

The metadata packages must not be copied by a co-installer or a class installer.

You must specify the COPYFLG_NODECOMP flag in the CopyFIles directive. This flag ensures that the binary integrity of the device metadata package is retained, and it avoids a decompression of the device metadata package when the driver package is installed.

You must sign the metadata package if it is included in a driver package that will be signed.

Any failure of the metadata package installation causes the driver installation to fail.

Apply the device metadata package to your system for testingThe device metadata package is installed automatically when you install a device in the user’s system. However, you need to press the F5 key in Devices and Printers when you copy the device metadata package after you install the device metadata package to the local metadata store for testing purposes. In that case, follow these steps:



1. Go to the Start menu.

2. Type Devices and Printers.

3. Click Settings in the Search pane.

4. Click Devices and Printers.

5. Press the F5 key.

Note: If you use the device metadata authoring tool or the WDK driver deployment tool, you don’t have to press the F5 key, as those tools refresh the device metadata database automatically.

Signature of the device metadata package and test modeTo apply for the Windows Store device app, specialized device app, Device Stage, and Autoplay for devices, your device metadata package requires a signature (users will get the device metadata package from WMIS), or your system needs to be in test mode (for your testing). When you are going to test your device metadata package before submitting it to Microsoft, you need to put your system into test mode. To put your PC into test mode, follow these steps:

1. Open a command prompt with elevated access.

2. Run bcdedit -set testsigning on.

3. Reboot the system.

You will see Test Mode in desktop when your PC is in test mode.

How the DMRC Selects a Device Metadata PackageWhen a user opens the Devices and Printers or the Device Stage™ user interface, the operating system launches the DMRC to search its cache for the most appropriate and current metadata package for a device. The DMRC also searches for a newer metadata package for the device on the WMIS server. If the DMRC finds a package, it downloads the package and installs it on the computer.

If the DMRC recently queried the WMIS server for a metadata package for a device, it uses a cached metadata package for the device instead of searching for a newer package. For more information, refer to “How the DMRC Determines Whether to Search the WMIS Server” later in this paper.

The DMRC uses the following metadata XML elements that are specified in the metadata packages to select the appropriate package for a device. The order of these XML elements reflects the priority that the DMRC uses to select a metadata package:

1. ModelID and ModelIDList

2. HardwareID and HardwareIDList

3. Locale

4. LastModifiedDate



When the DMRC selects a metadata package for a device, it follows these steps:

1. If the device has a model ID, the DMRC searches device metadata packages for a match between one ModelID entry in the package’s ModelIDList XML element and the device’s model ID value.

2. If the device does not have a model ID, the DMRC searches device metadata packages for a match between the HardwareID entries in the package’s HardwareIDList XML element and the device’s hardware IDs.

3. The DMRC creates a list of device metadata packages that meet the search criteria that are described in steps 1 and 2. From this list, the DMRC then searches the list entries for a match between the package’s Locale XML element and the list of preferred user locales on the computer.

If no entries in the list match this search criterion, the DMRC searches the list entries for a device metadata package that contains a Locale XML element that has the default attribute set to true. If the DMRC finds a match, it selects that metadata package.

In Windows 8, if the multiple locale flag is set to true, then that device metadata package is treated as the highest ranking for matching to locale.

4. If the DMRC finds more than one device metadata package during step 3, it selects the package that has a LastModifiedDate XML element with the most recent timestamp.

For more information about the device metadata XML schema and elements, refer to “How to Create a Device Metadata Package for Devices and Printers” on the Windows Dev Center-Hardware site.


http://msdn.microsoft.com/en-us/library/windows/hardware/gg463145


Figure 1 shows how the DMRC selects device metadata packages.

start

The device reportsa model ID?

YesNo

Any metadata package contains the

Model ID

Any metadata package contains the

device’ s hardwareIDs?

No

Returns ‘No Metadata Package Found’

Finish

More than 1 metadata package?

Yes

No

Yes

Returns the Metadata Package

No

The packages contains user locale?

Yes

NoA package sets locale default?

Yes

No

More than 1 metadata package?

Yes

No

Choose a package with latest ‘ LastModifiedDate’

Figure 1. How DMRC selects a metadata package

Remarks:

If the DMRC selects a metadata package that is based on hardware IDs, it uses the same ranking of hardware IDs that the operating system uses during driver installation. The DMRC ranks a more-specific hardware ID higher than a less-specific hardware ID. For example, the following hardware IDs are listed in ranking order:

<HardwareID>DOID:USB\VID_XXXX&PID_YYYY&REV_0000</HardwareID><HardwareID>DOID:USB\VID_XXXX&PID_YYYY</HardwareID>



For information about the hardware IDs in a device container, refer to “How to Create a Device Metadata Package for Devices and Printers” on the Windows Dev Center-Hardware site.

Only one metadata package for a device should set the default attribute of the Locale XML element to true. You should set this attribute to true in the package that contains a hardware ID with the highest ranking value.

The LastModifiedDate XML element is used for versioning and selecting a newer version of a device metadata package for a device.

If two or more device metadata packages in the local metadata store contain the same values for the ModelIDList, HardwareIDList, Locale, or LastModifiedDate XML elements, the DMRC selects only one of them for the device. Note that the DMRC selects one of these packages in a nondeterministic manner.

How the DMRC Determines Whether to Search the WMIS ServerTo reduce network traffic on a user’s local network, the DMRC maintains a cache of device metadata packages. When a user opens Devices and Printers, when Autoplay launches Device Stage, or when a periodic maintenance task is initiated in Windows 8, the DMRC follows these steps to determine if it is time to search the WMIS server for a newer metadata package:

1. If the target device’s device ID is not listed in the DMRC index table, the DMRC is searching for a metadata package for the device for the first time. Therefore, the DMRC queries the WMIS server.

2. If the target device’s device ID is listed in the DMRC index table, the DMRC calculates whether it is time to requery the WMIS server:

If the DMRC has previously retrieved a device metadata package for the device, the DMRC compares the value of the CheckBackMDRetrieved registry key to the value of today minus LastCheckedDate. If the CheckBackMDRetrieved value is smaller, the DMRC queries the WMIS server.

If the DMRC has not previously retrieved a device metadata package for the device, the DMRC compares the value of the CheckBackMDNotRetrieved registry key to the value of today minus LastCheckedDate. If the CheckBackMDNotRetrieved value is smaller, the DMRC queries the WMIS server.



Figure 2 summarizes the algorithms that the DMRC uses to determine when to query the WMIS server for updated metadata packages.

start

Previouslyqueried for a metadata

package for the device? (Is device hardware ID listed in the

DMRC index?)

No

Query WMIS server

Yes

Finish

The device has a metadata package?

Today – LastCheckedDate > CheckBackMDRetrieved?

Yes

Today – LastCheckedDate > CheckBackMDNotRetrieved?

No

Yes

No

Yes

No

Figure 2. How the DMRC determines whether to query the WMIS server for a device metadata package

The following list describes the values that are used in the algorithms in Figure 2:

LastCheckedDate

This value indicates the most recent date when the DMRC queried the WMIS server for metadata for a device. This date does not reflect whether the DMRC successfully retrieved a metadata package; it only indicates the last time that the DMRC queried the WMIS server on behalf of the device.

CheckBackMDNotRetrieved

This registry value indicates the number of days that the DMRC waits before it rechecks the WMIS server for metadata for a device. This value applies to devices for which the DMRC has not yet retrieved metadata from WMIS.

Path HKCU\Software\Microsoft\Windows\CurrentVersion\DeviceMetadataKey CheckBackMDNotRetrievedValue 0 to 256: REG_DWORDDefault Value 5



CheckBackMDRetrieved

This registry value indicates the number of days that the DMRC waits before it checks for updated metadata for a device. This value applies to devices for which the DMRC previously received metadata.

Path HKCU\Software\Microsoft\Windows\CurrentVersion\DeviceMetadataKey CheckBackMDRetrievedValue 0 to 256: REG_DWORDDefault Value 8

Note: The WMIS controls the CheckBackMDRetrieved and CheckBackMDNotRetrieved values. The WMIS team selects the values based on network conditions and load balancing. Every response from the WMIS server contains the client configuration data and controls the DMRC behavior.

Best Practices for Testing Download of Device Metadata Packages

Because of DMRC metadata caching, a delay can occur between the time when a device metadata package is available on the WMIS server and the time when that package is downloaded to a client system. To test the download of a device metadata package, you can force a download in two ways:

Delete the device metadata cache folder (%LOCALAPPDATA%\Local\Microsoft\Device Metadata\). Deleting this folder resets the value of LastCheckedDate and causes the DMRC to query the WMIS server for all devices as a first-time query.

In Windows 8, the device metadata cache is located on %PROGRAMDATA%\Microsoft\Windows\DeviceMetadataCache

Set the CheckBackMDRetrieved and CheckBackMDNotRetrieved registry keys to 0. When these values are zero, the DMRC immediately queries the WMIS server for a target device. Note that the WMIS overwrites these values each time that the DMRC receives a response from WMIS. Therefore, these parameters can change if the DMRC receives a response for any other device before it queries the WMIS server for your target device.

Note: You must make the preceding changes only when you test metadata packages. You must not provide to end users any tools that make these changes, and you should not communicate these forcing mechanisms to end users.

Device Metadata Package Installation DebugThe following sections provide information about debugging device metadata package installation.

Check whether the device metadata package is installed or not.Check the icon of your target device in Devices and Printers. If the device has the device icon that you specified listed in Devices and Printers, the device metadata package was installed correctly at least for the DeviceInfo.xml part.



Debug the device container properties by Using Ddodiag.exeIf you debug a device metadata package issue or any device properties issues, we recommend that you use Ddodiag.exe.

Beginning with Windows 7, the Ddodiag.exe supports listing all values of the device properties in device containers.

Run Ddodiag.exe

Follow these steps to run Ddodiag.exe:

1. Launch a command prompt.

2. Type start /wait ddodiag.exe -o <Filename.xml> and press the Enter key.

3. Type notepad.exe <Filename.xml>.

Note: The xml contains all properties of device containers in the system. If you are investigating a specific device problem, find the HardwareID or ModelID in the XML and see the properties of the device container. If you are investigating whether a given property value is set or not, try to find the value in the XML file.

Example 1: When you know the target device hardware IDs

1. Open the filename.xml by using Notepad or any editor.

2. Try to find the hardware ID (for example, USB\VID_045E&PID_0047).

3. Find the kind of property below in the XML file:

<Property key="PKEY_Device_HardwareIds" type="VT_VECTOR | VT_LPWSTR" vectorCount="7">

<Value>USB\VID_045E&PID_0047&REV_0300</Value>

<Value>HID\VID_045E&PID_0047&REV_0300</Value>

<Value>USB\VID_045E&PID_0047</Value>

<Value>HID\VID_045E&PID_0047</Value>

<Value>HID_DEVICE_SYSTEM_MOUSE</Value>

<Value>HID_DEVICE_UP:0001_U:0002</Value>

<Value>HID_DEVICE</Value>

</Property>

4. The property element should be a child element of a DDO element. (e.g. <DDO instanceId="DDO:{FF5614B9-6CB3-11E1-AAB0-806E6F6E6963}">).

5. In the DDO element, see the information that you set in the device metadata package. If the values are set, the device metadata package installation was completed correctly.



Below is an example of the property values (Icon name):

<Property key="PKEY_DeviceDisplay_Icon" type="VT_LPWSTR"> <Value>%programdata%\microsoft\windows\devicemetadatacache\dmrccache\en-us\2ec2ef3b-83d2-4f5d-afa3-31aec5a379dd\DeviceInformation\IntelliMouseExplorer3.0.ico</Value>

</Property>

Example 2: When you know the values that should be set into a container

1. Open the filename.xml by using notepad or any editor.

2. Try to find the value (e.g. Microsoft.Samples.PrinterExtensionCS).

3. If you don’t find any, the value is not set, so check the device metadata package information such as hardware ID, signature of the package, etc.

Below is an example of the property values (package name of an app):

<Property key="51236583-0c4a-4fe8-b81f-166aec13f510, 101" type="VT_VECTOR | VT_LPWSTR" vectorCount="1">

<Value>Microsoft.Samples.PrinterExtensionCS</Value>

</Property>

Debug by Using Event Tracing for Windows (ETW) in Windows 7If you debug a device metadata package problem, we recommend that you use Event Viewer.

Beginning with Windows 7, the Event Tracing for Windows (ETW) service supports the DeviceMetadata/Debug channel for events that are related to processing device metadata packages.

View Device Metadata/Debug ETW Events in Event Viewer

Follow these steps to view device metadata events in the Event Viewer:

1. On the Start menu, right-click Computer, and then select Manage.

2. Expand the System Tools node.

3. Expand and select the Event Viewer node.

4. On the View menu, click Show Analytic and Debug Logs.

5. Expand the Applications and Services Logs node, expand the Microsoft node, expand the Windows node, and then expand the UserPnP node.

6. Select the DeviceMetadata/Debug node.

Note: To receive and view events, you must enable logging on the DeviceMetadata/Debug ETW channel. Right-click the DeviceMetadata/Debug node, select Properties, and check the box that is named EnableLogging.



Device Metadata/Debug ETW Events

The operating system logs the following error, warning, and informational events during the download or processing of a device metadata package.

Event ID: 7900 Error: Device metadata package error.An error was detected with one of the components of a device metadata package. This event log message contains the following information:

A description of the error.

The source of the device metadata package, which is either DeviceMetadataStore or DeviceMetadataCache. For more information, see ”Glossary” later in this paper.

The name of the device metadata package.

An application-specific error code. For more information about these error codes, see “Determine the Device Metadata-Related Error Code” later in this paper.

A Win32 error code.

Event ID: 7901 Information: Device metadata package downloaded from WMIS.A device metadata package was downloaded from WMIS by the DMRC, which extracts the components from the package and saves them within the device metadata cache. This event log message contains the following information:

A description of the event.

The location of the unpacked device metadata package in the device metadata cache.


Event ID: 7902 Error: Device metadata package not signed.An installed device metadata package was not signed by the Dashboard.

Note: The signature of the device metadata package is verified only when it is downloaded from WMIS.

This event log message contains the following information:



An application-specific error code. For more information about these error codes, refer to “Determine the Device Metadata-Related Error Code” later in this paper.

A Win32 error code.



Event ID: 7950 Information: New device metadata package discovered in the local metadata store.The DMRC has detected a new device metadata package that is installed on the local computer. This event log message contains the following information:


The source of the device metadata package, which is either the Device Metadata Store or the Device Metadata Cache. For more information, refer to ”Glossary” later in this paper.


Event ID: 7951 Information: Query for metadata packages in progress.The DMRC queries installed device metadata packages for a particular device. This event log message contains the following information:


A device lookup key, such as the device’s hardware ID or model ID.

Note: Only the most specific hardware ID is logged when a list of hardware IDs are passed as a parameter.

Event ID: 7952 Warning: Network-related errors.The DMRC encountered a network error during the download of a device metadata package from the WMIS.

Note: This warning is not generated if the network is unavailable.


A detailed description of the error.

An application-specific error code.

The HTTP status code at the time of the network error.

Debug by Using Event Tracing for Windows (ETW) in Windows 8If you debug a device metadata package problem, we recommend that you use Event Viewer.

Beginning with Windows 7, the Event Tracing for Windows (ETW) service supports the DeviceMetadata/Debug channel for events that are related to processing device metadata packages.

View Device Metadata/Debug ETW Events in Event Viewer


1. On the Start menu, type Event Viewer and select settings in the Search pane.

2. Click View Event Logs.




4. Expand the Applications and Services Logs node, expand the Microsoft node, expand the Windows node, and then expand the UserPnP node.

5. Select the DeviceMetadata/Debug node.

Note: To receive and view events, you must enable logging on the DeviceMetadata/Debug ETW channel. Right-click the DeviceMetadata/Debug node, select Properties, and check the box that is named EnableLogging.

Device Metadata/Debug ETW Events

The operating system logs the following errors, warnings, and informational events during the download or processing of a device metadata package.

Event ID: 7804 Information: DMRC Start Search Local Index.DMRC starts searching a device metadata package in Local cache.

Message: START: Searching local index for metadata package

Event ID: 7805 Information: DMRC Stop Search Local Index.DMRC stops searching a device metadata package in Local cache.

Message: STOP: Searching local index for metadata package

Event ID: 7806 Information: DMRC Start Unpack package.DMRC starts unpacking a device metadata package.

Message: START: Unpacking metadata package into cache

Event ID: 7807 Information: DMRC Stop Unpack package.DMRC stops unpacking a device metadata package.

Message: STOP: Unpacking metadata package into cache

Event ID: 7808 Information: DMRC Start Parse_PackageInfo.DMRC start parsing packageinfo.xml.

Message: START: Parsing packageinfo.xml for metadata properties

Event ID: 7809 Information: DMRC Stop Parse_PackageInfo.DMRC stop parsing packageinfo.xml.

Message: STOP: Parsing packageinfo.xml for metadata properties

Event ID: 7810 Information: DMRC Start Scan_LocalStore.DMRC start scanning metadata packages in the local metadata store.

Message: START: Scanning local store for new metadata packages



Event ID: 7811 Information: DMRC Stop Scan_LocalStore.DMRC stop scanning metadata packages in the local metadata store.

Message: STOP: Scanning local store for new metadata packages

Event ID: 7812 Information: DMRC Start Initialize.DMRC start initializing the process.

Message: START: Initializing DMRC

Event ID: 7813 Information: DMRC Stop Initialize.DMRC stop initializing.

Message: STOP: Initializing DMRC

Event ID: 7814 Information: DMRC Start Uninitialize.DMRC start uninitializing.

Message: START: Uninitialize DMRC

Event ID: 7815 Information: DMRC Stop Uninitialize.DMRC stop uninitializing.

Message: STOP: Uninitializing DMRC

Event ID: 7900 Error: Device metadata package error.An error was detected with one of the components of a device metadata package. This event log message contains the following information:


The source of the device metadata package, which is either DeviceMetadataStore or DeviceMetadataCache. For more information, see ”Glossary” later in this paper.


An application-specific error code. For more information about these error codes, see “Determine the Device Metadata-Related Error Code” later in this paper.

A Win32® error code.

0x50000011

Failed to unpack metadata package

Package name failed filename validation

0x50000021

Couldn’t open PackageInfo

Couldn’t open DeviceInfo



Couldn’t open WindowsInfo

Couldn’t open ServiceInfo

Couldn’t open SoftwareInfo

0x50000022

Couldn’t parse PackageInfo

Couldn’t parse DeviceInfo

Couldn’t parse WindowsInfo

Couldn’t parse ServiceInfo

Couldn’t parse SoftwareInfo

Event ID: 7901 Information: Device metadata package downloaded from WMIS.A device metadata package was downloaded from WMIS by the DMRC, which extracts the components from the package and saves them within the device metadata cache. This event log message contains the following information:

Message: A new device metadata package was downloaded from WMIS.



Event ID: 7902 Error: Device metadata package not signed.An installed device metadata package was not signed by the Dashboard.

Note: The signature of the device metadata package is verified only when it is downloaded from WMIS.




An application-specific error code. For more information about these error codes, refer to “Determine the Device Metadata-Related Error Code” later in this paper.

A Win32 error code.

Event ID: 7903 Information: DMRC Parse Device metadata.DMRC finish parsing device metadata package. This event log message contains the following information:

Message: Successfully parsed device metadata file.





Language

Event ID: 7950 Information: New device metadata package discovered in the local metadata store.The DMRC has detected a new device metadata package that is installed on the local computer. This event log message contains the following information:


The source of the device metadata package, which is either the Device Metadata Store or the Device Metadata Cache. For more information, refer to ”Glossary” later in this paper.


Event ID: 7951 Information: Query for metadata packages in progress.The DMRC queries installed device metadata packages for a particular device. This event log message contains the following information:


A device lookup key, such as the device’s hardware ID or model ID.

Note: Only the most specific hardware ID is logged when a list of hardware IDs are passed as a parameter.

Event ID: 7952 Warning: Network-related errors.The DMRC encountered a network error during the download of a device metadata package from the WMIS.

Note: This warning is not generated if the network is unavailable.


A detailed description of the error.

An application-specific error code.

The HTTP status code at the time of the network error.

Debug by Using Problem Reports (Action Center)Windows 7 sends reports of device metadata package errors (error code 0x50000xx) to the Windows Error Report (WER) server. The Action Center lists the errors that will be sent or have already been sent. These reports provide debug information for your device metadata package.

View a Problem Report in Action Center

Follow these steps to view a problem report in Action Center:

1. On the Start menu, type “View all problem reports” and press ENTER.

2. Select a problem report that you want to review. The report contains detailed information for the error.



You can find the same information in Event Viewer:

1. Start the Event Viewer.

2. Expand the Windows Logs node.

3. Right-click Application, and then select Filter Current Log.

4. Type ”1001” in the Event ID text box, and then click OK.

The Event ID text box is the unlabeled text box in the middle of the dialog box with the default contents of “<All Event Ids>”.

Interpret a Problem Report

Every Device Metadata Retrieval Client problem report contains the following information:

1. An application-specific error code. For more information on these error codes, see “Determine the Device Metadata-Related Error Code” later in this paper.

2. A Win32 error code.

3. The source of the device metadata package, which is either the Device Metadata Store or the Device Metadata Cache. For more information, refer to “Glossary” later in this paper.

4. The name of the device metadata package.

Determine the Device Metadata-Related Error CodeBeginning with Windows 7, the operating system logs the following error codes within events that are related to downloading and processing device metadata packages. These events are managed by the ETW service and can be viewed by using Event Viewer.

WMIS server error (200000xx):

21: Request does not contain a device metadata request.

22: Request batch size exceeds maximum allowed value.

23: Invalid locale value.

24: Request does not contain valid header information.

25: Invalid request format.

31: Error occurred at service side when processing the request.

DMRC local error (0x400000xx):

The local metadata cache is corrupted:

11: There is no local metadata cache.12: The structure (folders) in the local metadata cache is not correct.

The local metadata store is corrupted:

21: There is no local metadata store.22: The structure (folders) in the local metadata store is corrupted.

The index is corrupted:



31: The index is missing.32: The index is corrupted.

Device metadata package errors (0x500000xx):

Cab file error:

11: The cab file is corrupted.12: The cab file does not have the correct structure.

PackageInfo.xml Error:

21: PackageInfo.xml is missing.22: PackageInfo.xml is not well-formed (cannot be parsed).

Note: Error code 22 indicates either that the PackageInfo.xml document is missing required elements or that one or more of its elements are not valid based on the syntax of the PackageInfo XML schema.

DeviceInfo.xml Error:

31: DeviceInfo.xml is missing.32: DeviceInfo.xml is not well-formed (cannot be parsed).33: DeviceInfo.xml is missing required elements.34: Elements in the DeviceInfo.xml are not valid based on the XML schema definition.

WindowsInfo.xml Error:

41: WindowsInfo.xml is missing.42: WindowsInfo.xml is not well-formed (cannot be parsed).43: WindowsInfo.xml is missing required elements.44: Elements in WindowsInfo.xml are not valid based on the XML schema definition.

Network error:

WMIS query (0x70000xxx):

503: WMIS server is busy and cannot service the request.For more information about HTTP errors, see “Resources” at the end of this paper.

408: WMIS server is not down but the request timed out.500: WMIS server returned internal error but the fault XML does not have a detailed error code.

BITS errors:

For more information about BITS errors, see “BITS Return Values” on MSDN®.

Appendix

Debug device setup by Using Event Tracing for Windows (ETW) in Windows 8

If you debug a device setup problem including device metadata package installation, we recommend that you use Event Viewer.



Beginning with Windows 8, the Event Tracing for Windows (ETW) service supports the channel for events that are related to device setup.

View Device Setup ETW Events in Event Viewer


1. On the Start menu, type Event Viewer and select settings in the Search pane.

2. Click View Event Logs.


4. Expand the Applications and Services Logs node, expand the Microsoft node, expand the Windows node, and then expand the DeviceSetupManager node.

5. Select the Admin node or Debug node to see the logs.

6. Note: To receive and view events of the Debug node, you must enable logging on the Debug channel. Right-click the Debug node, select Properties, and check the box that is named EnableLogging.

Device setup ETW Events

The operating system logs the following errors, warnings, and informational events during the download or processing of a device metadata package.

Admin Node

Below are the events that will be logged in the Admin Node.

Event ID: 100 Information: DSMServiceStartup.Device software manager service starts. This event log message contains the following information:

Message: DSM service start

Mode information

o Normal

o Paused

o Setup

o OOBE

The time last DSM session was performed.

Event ID: 101 Information: DSMServiceShutdown.Device software manager service ends. This event log message contains the following information:

Message: DSM Service shutting down.

The service uptime (how long the DSM service was up).



The active worktime (how long the DSM works actively).

Event ID: 104 Error: DsmServiceStartupFailed.DSM failed to start up. This event log message contains the following information:

Message: DSM Service failed to start.

Win32 error code

Event ID: 105 Information: RetrySequenceStart.DSM faces an error and starts retry sequence. This event log message contains the following information:

Message: DSM Service is entering a retry sequence because soft (retryable) errors were encountered.

Event ID: 106 Information: RetrySequenceStop.DSM leaves the retry sequence. This event log message contains the following information:

Message: DSM Service is leaving the retry state

The retry cycle time in this session. (How many times the DSM tried to retry in the session)

Event ID: 109 Information: DsmCoreServiceMode.DSM enters service mode. This event log message contains the following information:

Message: The DSM service has entered service mode

Mode Information

o Normal

o Paused

o Setup

o OOBE

Event ID: 112 Information: DeviceJobQueueComplete. DSM complete a device job queue. This event log message contains the

following information:

Device Name

Container ID

The number of tasks processed in the sessions

The number of properties that are updated

The active work time (how long the DSM works actively).



Event ID: 120 Information: DriverPackageDownloaded.DSM downloaded a driver from Windows update. This event log message

contains the following information:

Message: Driver update has been downloaded from Windows Update

Driver package ID

Download time (how long it took to download the drivers).

Event ID: 121 Error: DriverInstallFailed.Driver install failed. This event log message contains the following information:

Message: Driver install failed

Devnode ID

Win32 error code

Event ID: 122 Warning: DriverInstallBlockedByWUPolicy.Driver install failed because of WU opt-in policy. Users or group policy opt-out

the WU driver download.

Message: Access to drivers on Windows Update was blocked by policy

Event ID: 123 Warning: DriverInstallDelayed.The DSM service was delayed. This event log message contains the following

information:

Message: The DSM service was delayed

The delay time (how long the delay happened. )

Device ID

Event ID: 124 Information: DriverInstalled.A driver is installed successfully. This event log message contains the following

information:

Driver package ID

Device instance ID

The install time (how long it took to install the driver)

Event ID: 125 Warning: DriverInstallBlockedByPnpPolicy.A driver installation failed because of a PnP policy. This event log message


Message: Installation of a driver on device was blocked by PnP restriction policy

Devnode ID



Event ID: 130 Warning: MetadataStagingSucceeded.A device metadata package is staged for a device container. This event log

message contains the following information:

Message: Metadata package has been staged for container

Device metadata package name

Device container ID

Staging time (how long it took to stage the device metadata package)

Event ID: 131 Error: MetadataStagingFailed.Metadata staging failed. This event log message contains the following

information:

Message: Metadata staging failed

Device container ID

Win32 error code

Event ID: 150 Information: DeviceRemovalSucceeded.A device is removed successfully. This event log message contains the following

information:

Message: A device has been removed.

Device name

Container ID

Event ID: 151 Error: DeviceRemovalTimeout.A device fails to be removed. This event log message contains the following

information:

Message: A device failed to respond to a device remove request.

Device name

Container ID

Event ID: 152 Error: DevnodeRemovalFailure.A devnode fails to be removed. This event log message contains the following

information:

Message: Removal of device node failed.

Devnode name

Error code

Event ID: 200 Warning: NoConnectionToWu.The system doesn’t have a connection to Windows update.



Message: A connection to the Windows Update service could not be established.

Event ID: 201 Warning: NoConnectionToWmis.The system doesn’t have a connection to Windows Metadata and Internet

Services.

Message: A connection to the Windows Metadata and Internet Services (WMIS) could not be established.

Event ID: 202 Warning: NoConnectionToInternet.The system doesn’t have a connection to internet.

Message: The Network List Manager reports no connectivity to the internet.

Event ID: 203 Information: NetworkAvailable.The system doesn’t have a connection to internet.

Message: The Network List Manager reports no connectivity to the internet.

Debug Node

Event ID: 102 Information: DSMServiceDllLoad.DSM service dll is loaded.

Message: DSM Service dll has loaded.

Event ID: 103 Information: DSMServiceDllUnload.DSM Service dll is unloading..

Message: DSM Service dll is unloading.

Event ID: 108 Information: DsmCoreServiceState.DSM enters service state. This event log message contains the following information:

Message: The DSM service has entered service state

State Information

o Init

o Idle

o Working

o Retry pending

o Shutdown



Event ID: 110 Information: DsmJobStarted.DSM job started for a device container. This event log message contains the following information:

Message: Job has started for device container

Container ID

Job ID

Job Mode

o StartDeviceInstall

o InstallDrivers

o RunHeuristics

o InstallMetadata

o Remove

o Refresh

o RefreshProperty

Event ID: 111 Information: DsmJobComplete.DSM completes a job for a device container. This event log message contains the following information:

Message: Job has completed for device container

Container ID

Job ID

Task Status

o Complete

o Restart Required

o Soft Error

o Hard Error

o Internal Error

o Blocked by user policy

o Blocked by system policy

o Cancelled

Event ID: 220 Information: DsmRegisteredBackgroundTask.DSM registered a background task for a device container. This event log message


Message: Registered the handler for the app to handle notifications from the device container.

Device container ID

App package full name



Notification handler name

Event ID: 221 Information: DsmBackgroundTaskAlreadyRegistered.The background task is already registered. This event log message contains the

following information:

Message: A handler for the app was already registered for the device container.

Device container ID


Event ID: 222 Information: DsmRegisterErrorBackgroundTask.The background task failed to get registered. The event log message contains the following information:

Message: The device container and the app specify background task information, but we failed to register with error.Device container IDApp package full nameWin32 error code

Event ID: 223 Information: DsmUnregisterPrintBackgroundTask.A print background task is unregistered after the app is uninstalled. This event log

message contains the following information:

Message: Unregistered for the Print background task after uninstalling the app.


Event ID: 224 Information: DsmUnregisterMobileOperatorBackgroundTask.A mobile broadband background task is unregistered after the app is uninstalled.


Message: Unregistered for the Mobile Operator background task after uninstalling the app.


GlossaryDMRC

Device Metadata Retrieval Client that manages the device metadata operation in Windows 7.



WMISWindows Metadata and Internet Services, which serves device metadata packages that partners submit to the Dashboard over the Internet.

Windows Dev Center-Hardware Dashboard

This is a Web site that enables you to qualify hardware devices and software applications for the Microsoft Logo Program. You can then provide information about your products on the Windows Product Listing sites as well as update your driver distribution settings on Windows Update, retrieve end-user crash data, and submit device metadata packages.

For more information, see Resources at the end of this paper.

Device Metadata Store%programdata%\Microsoft\Windows\DeviceMetadataStore\

The folder into which users or applications copy device metadata packages when they install the packages on the local system.

Device Metadata Cache%localappdata%\Local\Microsoft\Device Metadata\

%PROGRAMDATA%\Microsoft\Windows\DeviceMetadataStore (In Windows 8)The folder in which the DMRC caches the unpacked device metadata package. All unpacked device metadata packages such as the device metadata packages that are downloaded from WMIS or the device metadata packages that are installed into the Local Device Metadata Store are saved in this folder.



Resources

MSDN

BITS Return Valueshttp://msdn.microsoft.com/en-us/library/aa362823(VS.85).aspx

CopyFile Functionhttp://msdn2.microsoft.com/en-us/library/aa363851.aspx

Windows Dev Center-Hardware site

How to Create a Device Metadata Package for Devices and Printers http://msdn.microsoft.com/en-us/library/windows/hardware/gg463145.aspx

Windows Driver Kit

Device and Driver Installation http://msdn2.microsoft.com/en-us/library/aa972910.aspx

Creating INF Files for Multiple Platforms and Operating Systemshttp://msdn.microsoft.com/en-us/library/ff540206.aspx

INF Fileshttp://msdn.microsoft.com/en-us/library/ff547402.aspx

10 Status Code Definitionshttp://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10


http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10

http://msdn.microsoft.com/en-us/library/ff547402.aspx

http://msdn.microsoft.com/en-us/library/ff540206.aspx

http://msdn2.microsoft.com/en-us/library/aa972910.aspx

http://msdn.microsoft.com/en-us/library/windows/hardware/gg463145.aspx

http://msdn2.microsoft.com/en-us/library/aa363851.aspx

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

Device Metadata Package Pipeline

Documents

Transcript of Device Metadata Package Pipeline