Rally Vertical Pairing PnP-X support
All Rally devices must support PnP-X. In Windows, PnP-X provides the mechanism to discover the presence of a paired Rally device.
This information applies for the following operating systems:
- Windows Server 2008 R2
- Windows 7
When Windows discovers a Rally device, it engages the Plug and Play subsystem to load or unload the appropriate device drivers when the device comes onto the network or leaves the network.
Network printers that implement WS-Print and WS-Scan interfaces are examples of such devices. However some devices, such as Digital Living Network Alliance (DLNA) renderers, do not require device drivers. In this situation, Windows includes a PnP-X pass through driver that can be used. This driver does not provide any functionality. However, it enables the Plug and Play subsystem to correctly detect the device’s presence, load the driver, and then announce the device to Windows. Such notifications are important for software such as Devices and Printers, AutoPlay handlers, and Sidebar gadgets.
Implement PnP-X support
A device implements PnP-X support by adding metadata to the device’s description document (UPnP) or the device’s metadata (DPWS). These metadata tags communicate information that Windows requires to map the device to the appropriate device drivers and to provide a Plug and Play presence.
The PnP-X metadata maps the device to a device driver by using a driver information (INF) file. The INF file tells the Plug and Play subsystem to which devices the driver package applies, where the files are located in the driver package, and where to copy the files on the system during device installation. The most critical point here is the matching of the PnP-X device to a driver package. Windows does this by comparing the hardware IDs and compatible IDs that were retrieved from the device with the IDs that are specified in the INF files in the driver store, on Windows Update, and other sources. All INF files that match the device are then ranked according to several criteria, and the driver package with the best match is selected for installation. Some INF files are included with Windows and others are accessed as part of a driver package on Windows Update, on a CD-ROM, or that is downloaded from the device manufacturer's web site.
For more information about driver packages, see Rally Vertical Pairing device drivers. For more information about PnP-X, see Discovery Technologies: PnP-X.
Device metadata
There are five PnP-X XML elements that you can add to a Rally device's metadata, which are described in the following table.
PnP-X Metadata XML Elements
| Name | Requirement | Description |
|---|---|---|
| Device Category | Optional (Windows Vista)
Required (Windows 7) |
Describes the device category for the device. |
| Hardware ID | Required | A unique identifier for the device. Windows uses this identifier to determine the appropriate drivers and metadata packages to use for the device. |
| Compatible ID | Required (if applicable) | An identifier for the device that indicates that the device is compatible with another device or class of devices. Windows uses this identifier to determine the appropriate drivers and metadata packages to use for the device. If a compatible ID exists for a device, it must be included in the device's metadata. |
| Container ID | Optional | A unique identifier that specifies the physical device. This identifier is shared across all transports and services that the device provides. Windows uses this identifier to group all the functionality of the device into a single physical device. This element is new for Windows 7. |
| Model ID | Optional | A unique identifier that specifies the particular model of the physical device. Windows uses this identifier to determine the appropriate metadata packages to use for the device. This element is useful to identify variations of a given device, such as different colors of the same device. This element is new for Windows 7. |
All Rally devices that support PnP-X must implement the elements in the preceding table that are noted as being required.
XML element details
The following sections provide more details about each XML element in the preceding table.
Device Category
The Device Category element informs Windows about the functionality that the device provides. In Windows Vista and Windows 7, each device is associated with a device category such as Printer, Scanner, or Modem. A single physical device can represent several different device categories. For example, a multifunction printer device might fit into the categories of Printer, Scanner, Fax, and Storage.
The value for the Device Category element in your device metadata is specified as a list of device categories that are each separated by a space character. The first entry in the list is considered the primary device category. Network Explorer and Devices and Printers display the device by using an icon that represents the primary device category. If Windows does not recognize the primary device category for a device, the device is displayed as a generic device icon with a device category of Other or Unknown.
There are two different XML namespaces where the Device Category element can be specified, one for backward support (for Windows Vista) and one for forward support (for Windows 7 and later). If you want your device to appear the best in both Windows Vista and Windows 7, you must specify the Device Category element for your PnP-X device in both namespaces.
Windows Vista Device Category Support
Windows Vista includes support for various device categories. The device category value can be any text string. However, Windows Vista recognizes only a limited list of device category values. For more information about the device categories that Windows Vista supports, see PnP-X: Plug and Play Extensions for Windows Specification.
Windows 7 Device Category Support
Windows 7 changed some device categories to include a broader range of devices. The Windows 7 device category list provides a hierarchical taxonomy that can be used to provide generic to specific device categories. For example, for a printer you might supply the general PrintFax device category or you might choose to identify the printer by using the more specific device category of PrintFax.Printer.Laser.
For more information about the device categories that Windows 7 supports, see How to Create a Device Metadata Package for Devices and Printers.
Note Multiple device categories must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple device categories.
Hardware ID
The hardware ID uniquely identifies the device model on a particular transport. Windows uses this identifier to determine the correct device drivers and metadata packages to use for the device.
For example, Devices and Printers uses the hardware ID (and the model ID) to identify the correct metadata package for the device. This enables Windows to display the device by using photorealistic icons and rich device descriptions.
You should use the same hardware ID value for all devices of the same model.
Beginning with Windows 7, PnP-X devices must use the following format for their hardware ID values:
VEN*_VID***&DEV***_DID***&SUBSYS***_SID***&REV***_RID*
VID
The device vendor’s vendor ID. Device vendors should contact sysdev@microsoft.com to obtain a vendor ID or to look up their vendor ID.
DID
The device ID for the device. This value is defined by the device vendor and must be unique for each device model.
SID
An optional subsystem ID for the device. This value is defined by the device vendor.
Some devices of the same model may differ by subsystem components. For example, one variant of a device model might implement support for a Wi-Fi network whereas another variant of the same device model might implement support for a wired network.
A device vendor might design a device on behalf of another company. In this situation, the device vendor might use the subsystem ID to identify itself and the vendor ID to identify the company for which it designed the device.
A device vendor might want to use both UPnP and the DPWS network protocols. In this situation, the hardware ID values for the two different protocols can be unique if the vendor specifies different values for the subsystem ID.
RID
An optional revision ID for the device. This value is defined by the device vendor. This value represents a revision of the device. It might represent the revision of the device's hardware or firmware.
For example:
VEN_999&DEV_22&REV_2533
or
VEN_999&DEV_22&SUBSYS_01&REV_2533
You can specify multiple hardware IDs for a device. In this situation, the hardware IDs typically range from specific to more general. For example, a device might define a hardware ID that represents the model number and another hardware ID that represents the model number plus the firmware revision or device options.
For example, you could specify the following three hardware IDs for a device:
VEN_999&DEV_22&SUBSYS_01&REV_2533
VEN_999&DEV_22&SUBSYS_01
VEN_999&DEV_22
Specifying multiple hardware IDs for your device can be very useful because it enables Windows to match your device to the appropriate device drivers at various levels. For example, Windows might determine the appropriate device driver and metadata package for a device that are based on the device’s basic hardware ID, such as VEN_999&DEV_22. However, if you must release an updated device driver only for those devices that have a specific firmware version, you can release an updated driver package that specifies a more specific hardware ID, such as VEN_999&DEV_22&SUBSYS_01&REV_2533.
Some device manufacturers use the basic hardware ID to identify an appropriate driver package and use more specific hardware IDs to identify an appropriate metadata package. This enables differentiation between functionally identical devices that have different device characteristics such as color or shape or that have been rebranded.
When specifying multiple hardware ID values in your device metadata, you must make sure that each is separated by a space character and that they are ordered most specific to least specific. The order is critical because it affects how Windows determines the appropriate device drivers and metadata packages for the device.
Note Hardware ID values must not include forward slash ('/') or backslash ('\') characters. These characters are reserved for delimiting a bus from a hardware ID in a device driver INF file.
Note Hardware ID values should be unique across transport protocols (for example, UPnP and DPWS). If a device implements more than one transport protocol, the device should have a unique hardware ID value for each transport protocol. This enables different drivers to load for the device for each transport protocol. However, some device vendors have implemented a single driver for their device that supports multiple transport protocols. In this situation, the hardware IDs for the device are not required to be unique across transport protocols.
Note When hardware ID and compatible ID values are specified in XML documents (such as DPWS metadata exchanges and UPnP description documents), they must be appropriately coded as entity references.
Note Multiple hardware IDs must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple hardware IDs.
Compatible ID
Much like the hardware ID, the compatible ID is a value that is used to determine the appropriate device drivers and metadata packages for a device. However, the compatible ID does not specify a specific device. Instead, it declares that the device is compatible with particular types of functionality.
For example, for a particular UPnP webcam, Windows might not find a driver or metadata package that is installed on the system that matches any of the device's hardware ID values. However, the device might be compatible with a more generic webcam device driver and metadata package that is installed on the system. If the device specifies compatible IDs, Windows can use the generic device drivers and metadata package for the device.
Basically, a compatible ID is used to indicate that a device is compatible with another device. Typically, a compatible ID is the same as the other device’s hardware ID. Often a device specifies a compatible ID that matches a class driver that is included with Windows for a particular type of device.
The following table provides some examples of the compatible ID values for some well-known device types.
Examples of Well-Known Compatible ID Values
| Device type | Compatible ID |
|---|---|
| DLNA media renderer | MS_DigitalMediaDeviceClass_DMR_V001 |
| DLNA media server | MS_DigitalMediaDeviceClass_DMS_V001 |
| DLNA media player | MS_DigitalMediaDeviceClass_DMP_V001 |
| DLNA media controller | MS_DigitalMediaDeviceClass_DMC_V001 |
| Media Center Extender | MICROSOFT_MCX_0001 |
| DPWS printer | https://schemas.microsoft.com/windows/2006/08/wdp/print /PrinterServiceType |
| Basic PnP-X support | GenericUmPass |
Just as you can with the hardware ID, you can specify a list of multiple compatible ID values for a device. The compatible IDs in your device metadata must each be separated by a space character, must not contain backslash ('\') or forward slash ('/') characters, and must be ordered from most relevant to least relevant (if applicable).
You can specify a compatible ID value of GenericUmPass for a device if the device does not implement any device-class-specific functionality. If you specify a list of compatible ID values for the device, GenericUmPass should be the last value in the list. In this situation, Windows loads the generic default driver, Umpass.sys, if no other hardware ID or compatible ID matches a device driver that is installed in the system. For more information, see Default pass-through driver.
Note Multiple compatible IDs must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple compatible IDs.
Container ID
The container ID is a unique identifier that specifies the physical device. This value is new for Windows 7. Windows uses this identifier to group devices that function over multiple transports into a single physical device that is displayed in Devices and Printers. If a device does not support multiple transports, this value should be omitted.
For example, if a printer can be accessed over UPnP, DPWS, and USB, the same container ID value should be specified for all three transports. When Windows enumerates all devices across all transports, it finds multiple devices with the same container ID and groups them as a single physical device.
The container ID value is specified as a GUID, for example, {01392d0-5e91-10ad-ad8b-0a00200c9e12}.
For more information about the container ID element, see Container IDs.
Model ID
The model ID is a unique identifier that specifies the particular model of the physical device. Windows uses this identifier to determine the appropriate metadata packages to use for the device.
The model ID is typically used to differentiate among different versions of a device. For example, a particular MP3 playback device model may be available in different colors. If the same hardware ID is specified for all colors, Windows uses the same device driver regardless of the color of the device. However, if a different model ID is specified for each color of the device, Windows can use different metadata packages for each different color of the device. This lets each color of the device use a different photorealistic icon of the device in Devices and Printers to represent the correct color of the device.
Like the container ID, the model ID value is specified as a GUID, for example, {01392d0-5e91-10ad-ad8b-0a00200c9e12}.
DPWS devices
All DPWS devices must expose all required PnP-X metadata elements that were listed at the beginning of this section (Device metadata). The following table associates each PnP-X metadata element with its respective DPWS XML element container and namespace.
DPWS XML Element Containers and Namespaces for PnP-X Elements
| PnP-X element | Element container | Namespace |
|---|---|---|
| DeviceCategory | ThisModel | For Windows Vista: https://schemas.microsoft.com/windows/pnpx/2005/10 For Windows 7: https://schemas.microsoft.com/windows/2008/09/devicefoundation |
| HardwareId | Hosted | https://schemas.microsoft.com/windows/pnpx/2005/10 |
| CompatibleId | Hosted | https://schemas.microsoft.com/windows/pnpx/2005/10 |
| ContainerId | ThisDevice | https://schemas.microsoft.com/windows/2008/09/devicefoundation |
| ModelId | ThisModel | https://schemas.microsoft.com/windows/2008/09/devicefoundation |
The following example shows a DPWS Simple Object Access Protocol (SOAP) message that specifies metadata for a printer/scanner device that supports two hosted services.
DPWS Metadata Message with PnP-X Support
<soap:Envelope
xmlns:soap="https://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsdisco="https://schemas.xmlsoap.org/ws/2005/04/discovery"
xmlns:wsx="https://schemas.xmlsoap.org/ws/2004/09/mex"
xmlns:wsd="https://schemas.xmlsoap.org/ws/2006/02/devprof"
xmlns:pnpx="https://schemas.microsoft.com/windows/pnpx/2005/10"
xmlns:df="https://schemas.microsoft.com/windows/2008/09/devicefoundation" >
<soap:Header>
<!-- Place SOAP header information here.-->
</soap:Header>
<soap:Body>
<wsx:Metadata>
<wsx:MetadataSection Dialect="https://schemas.xmlsoap.org/ws/2006/02/devprof/ThisDevice">
<wsd:ThisDevice>
<!-- Place ThisDevice metadata here.-->
<df:ContainerId>
<-- only define if using multiple protocols -->
{101392d0-5e91-11dd-ad8b-0800200c9a66}
</df:ContainerId>
</wsd:ThisDevice>
</wsx:MetadataSection>
<wsx:MetadataSection Dialect="https://schemas.xmlsoap.org/ws/2006/02/devprof/ThisModel">
<wsd:ThisModel>
<!-- Place ThisModel metadata here.-->
<pnpx:DeviceCategory>
<!-- List Windows Vista only categories -->
MFP Printers Scanners
</pnpx:DeviceCategory>
<df:DeviceCategory>
<!-- List Windows 7 categories -->
PrintFax.MFP PrintFax.Printer.Laser Imaging.Scanner
</df:DeviceCategory>
<df:ModelId>
<!-- Model ID is optional -->
{01392d0-5e91-10ad-ad8b-0a00200c9e12}
</df:ModelId>
</wsd:ThisModel>
</wsx:MetadataSection>
<wsx:MetadataSection Dialect="https://schemas.xmlsoap.org/ws/2006/02/devprof/Relationship">
<wsd:Relationship Type="https://schemas.xmlsoap.org/ws/2006/02/devprof/host">
<wsd:Hosted>
<!-- Place Hosted metadata for first service -->
<pnpx:HardwareId>
<!-- Place 1st service Hardware IDs here.-->
<!-- This example: SUBSYS_01 = DPWS printer -->
VEN_999&DEV_22&SUBSYS_01&REV_2533 VEN_999&DEV_22&SUBSYS_01 VEN_999&DEV_22
</pnpx:HardwareId>
<pnpx:CompatibleId>
<!-- Place 1st service Compatible IDs here.-->
https://schemas.microsoft.com/windows/2006/08/wdp/print/PrinterServiceType GenericUmPass
</pnpx:CompatibleId>
</wsd:Hosted>
<wsd:Hosted>
<!-- Hosted metadata for second service -->
<pnpx:HardwareId>
<!-- Place 2nd service Hardware IDs here -->
<!-- This example: SUBSYS_11 = DPWS scanner -->
VEN_999&DEV_22&SUBSYS_11&REV_2533 VEN_999&DEV_22&SUBSYS_11 VEN_999&DEV_22
</pnpx:HardwareId>
<pnpx:CompatibleId>
<!-- Place 2nd service Compatible IDs here.-->
https://schemas.microsoft.com/windows/2006/08/wdp/scan/ScannerServiceType GenericUmPass
</pnpx:CompatibleId>
</wsd:Hosted>
<wsd:Hosted>
<!-- Hosted metadata for the third service -->
<!-- This service will not be installed by
PnP X because it does not contain a
Hardware ID or Compatible ID -->
</wsd:Hosted>
</wsd:Relationship>
</wsx:MetadataSection>
</wsx:Metadata>
</soap:Body>
</soap:Envelope>
Note This example specifies GenericUmPass as the compatible ID value for each DPWS service. Devices should leave this as the last compatible ID value, as discussed earlier in this article.
UPnP devices
All UPnP devices must be PnP-X-enabled. The following sections discuss how to include PnP-X support in a UPnP device.
SSDP discovery
For PnP-X support, no changes are required to the UPnP SSDP discovery packets. However, for Rally Vertical Pairing support, the device identity string must be specified with lowercase characters.
UPnP description document
Similar to DPWS devices, all UPnP devices must expose all required PnP-X metadata elements that were listed at the beginning of this section (Device metadata). The following table associates each PnP-X metadata element with its respective parent UPnP element block.
UPnP XML Element Containers and Namespaces for PnP-X Elements
| PnP-X element | Element container | Namespace |
|---|---|---|
| X_deviceCategory | <device> | For Windows Vista: https://schemas.microsoft.com/windows/pnpx/2005/11
For Windows 7: https://schemas.microsoft.com/windows/2008/09/devicefoundation |
| X_hardwareId | <device> | https://schemas.microsoft.com/windows/pnpx/2005/11 |
| X_compatibleId | <device> | https://schemas.microsoft.com/windows/pnpx/2005/11 |
| X_containerId | <device> | https://schemas.microsoft.com/windows/2008/09/devicefoundation |
| X_modelId | <device> | https://schemas.microsoft.com/windows/2008/09/devicefoundation |
The following example shows a UPnP description document that specifies metadata for a printer/scanner device that supports two hosted services.
UPnP Description Document with PnP-X Support
<?xml version="1.0" ?>
<root xmlns="urn:schemas-upnp-org:device-1-0"
xmlns:pnpx="https://schemas.microsoft.com/windows/pnpx/2005/11"
xmlns:df="https://schemas.microsoft.com/windows/2008/09/devicefoundation" >
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<device>
<pnpx:X_hardwareId>
<!-- This example: SUBSYS_00 = UPnP printer -->
VEN_999&DEV_22&SUBSYS_00&REV_2533 VEN_999&DEV_22&SUBSYS_00 VEN_999&DEV_22
</pnpx:X_hardwareId>
<pnpx:X_compatibleId>
<!-- Add any applicable compatID values -->
GenericUmPass
</pnpx:X_compatibleId>
<pnpx:X_deviceCategory>
<!-- List Vista only categories -->
MFP Printers Scanners
</pnpx:X_deviceCategory>
<df:X_deviceCategory>
<!-- List Win7+ categories -->
PrintFax.MFP PrintFax.Printer.Laser Imaging.Scanner
</df:X_deviceCategory>
<df:X_containerId>
<!-- Only define this if using multiple protocols -->
{101392d0-5e91-11dd-ad8b-0800200c9a66}
</df:X_containerId>
<df:X_modelId>
<!-- Model ID is optional -->
{701392d0-5e91-10ad-ad8b-0a00200c9e12}
</df:X_modelId >
<deviceType>UPnP_DEVICE_TYPE_VALUE</deviceType>
<friendlyName>friendly name</friendlyName>
<manufacturer>manufacturer</manufacturer>
<manufacturerURL>manufacturer URL</manufacturerURL>
<modelDescription>model description</modelDescription>
<modelName>model name</modelName>
<modelNumber>model number</modelNumber>
<modelURL>URL to model site</modelURL>
<serialNumber>manufacturer's serial number</serialNumber>
<UDN>device UDN</UDN>
<UPC>universal product code</UPC>
<serviceList>
<service>
<serviceType />
<serviceId />
<SCPDURL />
<controlURL />
<eventSubURL />
</service>
</serviceList>
<deviceList>
<!-- Child device descriptions -->
</deviceList>
<presentationURL>presentation URL</presentationURL>
</device>
</root>
Note This example specifies GenericUmPass as the compatible ID value. Devices should leave this as the last compatible ID value, as discussed earlier in this article.
Related topics
Using Windows Rally Vertical Pairing to automatically install Wi Fi devices