How to retrieve related PnP objects (HTML)

This topic describes how to find Plug and Play (PnP) objects that are related to each other. For example, you may want to retrieve the device container object that is related to a device information object. Device containers represent the physical device as seen by the user. The device container lets you access information that pertains to the whole device hardware product, rather than only one of its functional interfaces. Examples of device container properties are manufacturer or model name.

Understanding PnP object relationships

The tables in this topic show the relationship between the different PnpObjectType objects and the properties that must be used to navigate between them. Note that a DeviceInformation object is equivalent to a PnpObject with a PnpObjectType equal to deviceInterface.

Many-to-one relationships

The table in this section shows how to navigate from an object that has an N-to-1 relationship with other objects. For example, one or more device interfaces (represented by DeviceInformation objects) may belong to the same device container. The headings of the first two columns contain the type of Plug and Play (PnP) object that you start with. The entries in the third column contain the related PnP object you want to find. The cells in the table, if filled in, contain the property that can be used to query for the related PnP object.

To navigate from the object listed in the column headings to the object listed in the third column, do the following:

1. Find a property that is in the same column as the heading that correspondsto the object you started with, and is in the same row as the related object you want to find.
2. Retrieve the property by using the steps described in How to retrieve related PnP objects
3. Use the retrieved value as the id parameter in a PnpObject.createFromIdAsync call to create an object of the related type.

One-to-many relationships

The table in this section shows how to navigate from an object that has a 1 to N relationship with other objects. To navigate from the object you started with (in the top row), to the related object listed on the right, do the following:

1. Find a property in the same column as the heading for the object that you started with, and in the same row as the related object you want to find.

2. Use the id of the object you started with (from the heading row) and the property you identified in the table, to form an AQS string of the form "<property>:=<id>".

   As an example, if we wanted to find all interfaces in a container with identity "{1451362b-4b9c-4780-a4bf-6c001619646c}" then the AQS string would be "System.Devices.ContainerId:={1451362b-4b9c-4780-a4bf-6c001619646c}".

3. Use the AQS string as a parameter to a Windows.Devices.Enumeration.Pnp.PnpObject.findAllAsync call to find objects of the related type.

   Note  When working with properties that contain GUIDs, the GUID value must be placed in braces when forming the AQS string.

    

Examples

Getting a container from a DeviceInformation ID

You may need to get properties of the container that a device interface belongs to. For instance, if you have the device ID of a selected device but need to get the model name, you need to create a container object because System.Devices.ModelName is a container property, not a device interface property.

This code shows you how to get a container property starting with a device ID.

// GetModelNameFromDeviceID gets the ModelName property from the
// device interface's container.
// The parameter devID is assumed to be a valid device interface ID.
string GetModelNameFromDeviceID (devID)
{
// First create a DeviceInformation object from the ID.
// Create the argument that specifies that additional properties
// returned should include the System.Devices.ContainerId property.
   var propertiesToGet = new Array();
   propertiesToGet.push("System.Devices.ContainerId");


// Create a DeviceInformation object from the ID.
   var Enum = Windows.Devices.Enumeration;
   var DevInfo = Enum.DeviceInformation;
   var contID;   // The container ID
   DevInfo.createFromIdAsync(devID, propertiesToGet).then(
       function(devInf) {             
            var prop = devInf.properties;
            if (prop) {
                contID = prop.lookup("System.Devices.ContainerID");               
            }
       },
       function (e) {
           displayError("Failed to create DeviceInformation: " + e.message);
       });

// Use the container ID to create a PnPObject representing the container,
// and specify that the created object should have a 
// System.Devices.ModelId property.


// Create the argument that specifies that the additional properties to
// return should include the System.Devices.ContainerId property.
   var containerPropertiesToGet = new Array();
   containerPropertiesToGet.push("System.Devices.ModelId");

   var modelID;


var Pnp = Enum.Pnp;
var pnpObjType = Pnp.PnpObjectType;
var deviceType = pnpObjType.device;

// NOTE: We need to add extra braces "{}" back to the container ID before
// passing it to createIdAsync (a pair of braces is lost in the implicit
// conversion from GUID to string).
   contID = "{" + contID + "}";

// Create the container from its ID.
   Pnp.createFromIdAsync(deviceType, contID, containerPropertiesToGet).then(
       function(contInf) {
           var prop = contInf.properties;
           if (prop) {
               modelID = prop.lookup("System.Devices.ModelID");
           });
   return modelID;
}

Note  

If you pass the GUID result of a property lookup to a function that takes the GUID as a string argument, as in the previous example, you need to add extra braces "{}" around the GUID argument before passing it to the function. This is because the result of a property lookup is a variant type, rather than a string, so when the argument is passed to a function that takes a string, a pair of braces is lost in the implicit conversion.

Getting all the DeviceInformation objects in a specific device container

This example demonstrates how to find all the DeviceInformation objects in a specified device container, by forming an AQS query and passing the query to findAllAsync.

function findInterfacesInContainer(containerId) {

    var Enum = Windows.Devices.Enumeration;
    var aqsString = "System.Devices.ContainerId:=\"" + containerId + "\"";

    Enum.DeviceInformation.findAllAsync(aqsString, null).then(
            successCallback, 
            errorCallback);
}

// Handles successful completion of the findAllAsync method.
function successCallback(deviceInformationCollection) {
    // Add your code here for processing the enumerated device collection.
}

// Handles an error completion of the findAllAsync method.
function errorCallback(e) {
    // Add your error-handling code here.
}

Related topics

How to retrieve additional properties for a device or PnP object

AQS query