Visão geral da linguagem de avaliação de dados simples

O WDTF inclui uma linguagem de consulta simples para simplificar a tarefa de coletar destinos com base em atributos ou relacionamentos. A Simple Data Evaluation Language (SDEL) é semelhante ao XPath. Para obter mais informações sobre XPath, consulte a Referência XPath .

As seções a seguir neste tópico descrevem como você pode usar o SDEL.

Noções básicas de sintaxe SDEL

O SDEL usa tokens de atributo para efetuar correspondências e recuperar dados. Todos os tokens SDEL podem conter apenas caracteres alfanuméricos e hífen (-).

Um atributo refere-se a uma parte de um dado que está anexado a um destino. Os valores reais no atributo são armazenados como um VARIANT. Se colocares um operador de comparação seguido por um teste valor após o atributo, o SDEL realizará uma comparação. Você deve colocar os valores de teste entre aspas simples ou duplas - essa notação permite que você use aspas simples ou duplas reais em seu valor de teste, mas não ambos. Se o valor de teste consistir apenas em caracteres alfanuméricos e hífenes (-), você poderá omitir as aspas.

Operações de comparação

O SDEL permite que vários operadores de comparação sigam um token de atributo. No momento de uma comparação, o valor real no atributo à esquerda do operador é feito para ser o mesmo tipo do valor de teste à direita do operador através do método VariantChangeType (que é descrito na documentação do SDK do Microsoft Windows). A tabela a seguir mostra os diferentes operadores de comparação suportados pelo SDEL.

Operador de comparação Significado Igualdade (=)

Depois que os tipos são alterados, eles são comparados usando o método VarCmp (que é descrito na documentação do SDK do Windows).

Desigualdade (!=)

Menor que (<)

Menor ou igual (<=)

Maior que (>)

Maior ou igual (>=)

Operação Bitwise AND (&)

Este operador força os tipos de dados a VT_I8 antes de executar uma operação AND bit a bit dos valores reais e de teste.

Nenhuma operação de comparação (e nenhum valor) especificado

Se o valor real no atributo for do tipo VT_BOOL, a correspondência será satisfeita com base nesse valor, ou seja, você não precisará de um operador de comparação para fazer "IsDisable=True". Caso contrário, se houver algum valor (além de VT_EMPTY), o critério é cumprido.

Quando há mais de um valor real (ou uma matriz) no atributo, todos os operadores de comparação devem ser interpretados para corresponder a pelo menos um, exceto o operador de desigualdade, que tem o comportamento oposto. Se os tipos não puderem ser comparados (ou seja, VariantChangeType falhar), não haverá correspondência (exceto com o operador de desigualdade, que tem o comportamento oposto).

Noções básicas sobre namespaces de atributos

O SDEL usa tokens de namespace para agrupar atributos. Para obter uma lista completa de todos os tokens de namespace e os tokens de atributo dentro deles, consulte Tokens de atributo em SDEL.

Para usar qualquer atributo que esteja fora do namespace raiz, deve-se prefixar o atributo com o nome do namespace e, em seguida, dois pontos (::). O exemplo de código VBScript a seguir exibe o valor do atributo Disk::IsRemovable .

WScript.Echo "Is Removable?: " & DeviceObj.GetValue("Disk::IsRemovable")

Examinando um destino usando GetValue e Eval

O método IWDTFTarget2::GetValue permite perguntar a um destino sobre seus atributos. O exemplo de código VBScript a seguir imprime o valor do atributo FriendlyName para um alvo.

WScript.Echo "FriendlyName: " & Device.GetValue("FriendlyName")

Para uma lista completa de identificadores de atributo, consulte Identificadores de atributo em SDEL.

Você também pode usar o método IWDTFTarget2::Eval para avaliar uma instrução SDEL em relação a um alvo. Eval retorna VARIANT_TRUE ou VARIANT_FALSE. O exemplo de código VBScript a seguir usa Eval para determinar se um dispositivo pode ser desativado.

If Device.Eval("IsDisableable=true") Then
    WScript.Echo "Target is disableable!"
End If

Você também pode usar Eval para testar a presença de um atributo. Quando você passa Eval um atributo, mas nenhum operador ou valor de comparação, Eval retornará VARIANT_TRUE se o atributo ou namespace tiver qualquer valor (diferente de VT_EMPTY). O exemplo de código VBScript a seguir usa Eval para determinar se o destino tem uma palavra-chave SymbolicLink.

If Device.Eval("SymbolicLink") Then
    WScript.Echo "Target has a SymbolicLink!"
End If

Além disso, os atributos a que falta um operador de comparação, mas que contêm um valor VT_BOOL, têm uma comparação implícita '=true' aplicada. Esta comparação implícita significa que "IsDisableable" é equivalente a "IsDisableable='true'".

Navegando em relacionamentos

Os testes geralmente envolvem examinar o que acontece quando dispositivos relacionados mudam de estado. Por exemplo, quando um hub USB está desativado, os dispositivos conectados a ele lidam corretamente com a mudança de estado? Além disso, talvez você queira localizar um dispositivo com base em informações em dispositivos relacionados. Para dar suporte a essa funcionalidade, o SDEL inclui uma maneira de especificar um ou mais relacionamentos lógicos antes de qualquer atributo ou namespace (mas não depois de qualquer um deles). Os tokens de relação são separados do atributo ou namespace por uma barra (/). O exemplo de código VBScript a seguir imprime o valor do atributo FriendlyName para o dispositivo pai do alvo.

WScript.Echo "FriendlyName: " & Device.GetValue("parent/FriendlyName")

Você também pode combinar modificadores de relação. O exemplo de código VBScript a seguir imprime o valor do atributo FriendlyName do dispositivo avô do objeto de destino.

WScript.Echo "FriendlyName: " & Device.GetValue("parent/parent/FriendlyName")

Às vezes, os dispositivos têm relações muitos-para-muitos. Por exemplo, um volume de armazenamento lógico pode residir em muitos discos físicos e esses discos individuais podem contribuir com espaço para muitos volumes.

No WDTF, todos os dispositivos não-fantasmas (ou seja, dispositivos fisicamente presentes) são descendentes do dispositivo raiz (que pode ser obtido a partir da propriedade RootDevice). (Para obter mais informações sobre dispositivos fantasmas, consulte Criando cenários WDTF.)

Recolha de alvos usando GetRelations

A ilustração a seguir mostra o IWDTFTarget2::GetRelations método.

O método IWDTFTarget2::GetRelations aceita apenas a parte do especificador de relação da sintaxe da instrução SDEL e retorna uma interface de coleção IWDTFTargets2 que contém todos os alvos que atendem aos critérios de relacionamento. O exemplo de código VBScript a seguir retorna uma coleção que contém o destino original e todos os seus irmãos.

Set TestDevices = Device.GetRelations("parent/child/", "")

O segundo parâmetro para GetRelations pode, opcionalmente, incluir uma instrução a ser passada para o método Eval de cada destino que estabeleça a relação específica. Por exemplo, se você adicionar IsDisable=true como o segundo parâmetro, o exemplo de código anterior retornará apenas o dispositivo e seus irmãos que podem ser desativados.

Se não houver resultados, uma coleção com zero itens será retornada.

Recolher Destinos Usando uma Consulta

A interface IWDTFDeviceDepot2 contém um método Query. Esse método usa uma instrução SDEL projetada para o método IWDTFTarget2::Eval e retorna uma nova instância do IWDTFTargets2 interface de coleta que contém um subconjunto dos destinos que atendem aos critérios da consulta. O exemplo de código VBScript a seguir enumera todos os dispositivos não fantasmas e mostra o nome amigável para cada dispositivo.

For Each Device In WDTF.DeviceDepot.Query("IsPhantom=false")
    WScript.Echo Device.GetValue("FriendlyName")
Next

A coleção retornada tem o método IWDTFTargets2::Query, que tem uma implementação idêntica à IWDTFDeviceDepot2::Query. IWDTFTargets2::Query retorna um subconjunto de alvos da coleção original que satisfaz a instrução SDEL.

Lógica Booleana em SDEL

O métodoIWDTFTarget2::GetRelations pode aceitar apenas o operador booleano OU OR, mas as suas chamadas para os métodos IWDTFTargets2::Query, IWDTFTarget2::Eval, e IWDTFTarget2::GetValue podem usar os operadores booleanos E AND e OU OR. Para o método Query e método Eval, os operadores agirão como operadores booleanos normais, retornando o resultado conforme o esperado. No entanto, para o método GetValue, E comporá os valores em ambos os lados dele, e OU retornará apenas o primeiro valor encontrado (começando pela esquerda).

Parênteses em SDEL

Todas as instruções SDEL podem usar parênteses para especificar a sequência de avaliação para a lógica booleana. Você também pode usar parênteses para agrupar subelementos em uma instrução sob uma relação ou namespace.

O exemplo de código VBScript a seguir recupera todos os volumes e filhos de um dispositivo avô.

Set Devices = Device.GetRelations("parent/parent/(child/ OR volume/)", "")

O exemplo de código VBScript a seguir recupera todos os dispositivos que têm um dispositivo filho com mídia amovível que ultrapassa 1.000.000 bytes.

Set Devices = WDTF.DeviceDepot.Query("child/disk::(IsRemovable=true AND Size>1000000)")

Análise de sintaxe SDEL

Se você passar uma instrução SDEL com sintaxe incorreta para qualquer um dos métodos no WDTF, o método falhará e informações detalhadas de erro serão retornadas e explicarão o problema.