Como recuperar objetos PnP relacionados (HTML)

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico descreve como encontrar objetos PnP (Plug and Play) que estão relacionados entre si. Por exemplo, você pode querer recuperar o objeto do contêiner do dispositivo que está relacionado a um objeto de informações do dispositivo. Os contêineres de dispositivos representam um dispositivo físico, como visto pelo usuário. O contêiner do dispositivo permite o acesso a informações que pertencem a todo o produto do hardware do dispositivo, em vez de apenas uma das suas interfaces funcionais. Exemplos de propriedades de contêineres do dispositivo são o nome do fabricante ou do modelo.

Compreendendo relações de objetos PnP

As tabelas deste tópico mostram a relação entre objetos PnpObjectType e as propriedades que devem ser usadas para navegar por eles. Observe que um objeto DeviceInformation é equivalente a um PnpObject com um PnpObjectType igual a deviceInterface.

Relações muitos-para-um

A tabela desta seção mostra como navegar de um objeto que possui uma relação de N para1 com outros objetos. Por exemplo, uma ou mais interfaces de dispositivos (representadas pelos objetos DeviceInformation) podem pertencer ao mesmo contêiner de dispositivo. Os cabeçalhos da duas primeiras colunas contêm o tipo de objeto PnP com o qual você começará. As entradas na terceira coluna contêm o objeto PnP relacionado que você quer localizar. As células da tabela, se preenchidas, contêm a propriedade que pode ser usada para consultar o objeto PnP relacionado.

Para navegar do objeto listado nos cabeçalhos das colunas até o objeto listado na terceira coluna, faça o seguinte:

1. Encontre uma propriedade que está na mesma coluna do cabeçalho correspondente ao objeto com o qual você começou e que está na mesma linha que o objeto relacionado que você quer localizar.
2. Recupere a propriedade usando as etapas descritas em Como recuperar objetos PnP
3. Use o valor recuperado como o parâmetro de id em uma chamada PnpObject.createFromIdAsync para criar um objeto do tipo relacionado.

Relações um-para-muitos

A tabela desta seção mostra como navegar de um objeto que possui uma relação de 1 para N com outros objetos. Para navegar do objeto com o qual você começou (na linha superior) até o objeto relacionado listado à direita, faça o seguinte:

1. Encontre uma propriedade na mesma coluna do cabeçalho do objeto com o qual você começou e na mesma linha do objeto relacionado que você quer localizar.

2. Use o ID do objeto com que você começou (a partir da linha de título) e da propriedade que você identificou na tabela, para formar uma cadeia de caracteres AQS do formulário "<property>:=<id>".

   Como um exemplo, se quiser encontrar todas as interfaces em um contêiner com identidade "{1451362b-4b9c-4780-a4bf-6c001619646c}", a cadeia de caracteres AQS seria "System.Devices.ContainerId:={1451362b-4b9c-4780-a4bf-6c001619646c}".

3. Use a cadeia de caracteres AQS como um parâmetro para uma chamada Windows.Devices.Enumeration.Pnp.PnpObject.findAllAsync para encontrar objetos do tipo relacionado.

   Observação  Ao trabalhar com propriedades que contêm GUIDs, o valor GUID deve ser colocado entre colchetes ao formar a cadeia de caracteres AQS.

    

Exemplos

Obtendo um contêiner de uma ID de DeviceInformation

Talvez você precise obter propriedades do contêiner ao qual uma interface de dispositivo pertence. Por exemplo, se você tem a ID de dispositivo de um dispositivo selecionado, mas precisa obter o nome do modelo, terá que criar um objeto contêiner porque System.Devices.ModelName é uma propriedade de contêiner, não uma propriedade de interface de dispositivo.

Este código mostra como obter uma propriedade de contêiner começando com a ID de um dispositivo.

// 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;
}

Observação  

Quando você passa o resultado GUID de uma pesquisa de propriedade para uma função que recebe o GUID como um argumento de cadeia de caracteres, é necessário adicionar chaves "{}" em torno do argumento GUID antes de passá-lo para a função. Isso ocorre porque o resultado de uma pesquisa de propriedade é um tipo variante, em vez de uma cadeia de caracteres, de maneira que quando o argumento é passado para uma função que aceita uma cadeia de caracteres, um par de chaves é perdido na conversão implícita.

Obtendo todos os objetos DeviceInformation em um contêiner de dispositivo específico

Este exemplo demonstra como localizar todos os objetos DeviceInformation em um contêiner de dispositivo especificado formando uma pesquisa AQS e passando a pesquisa para 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.
}

Tópicos relacionados

Como recuperar propriedades adicionais para um dispositivo ou objeto PnP

Pesquisa AQS