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 XPath Reference.

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

Observação

Para obter uma lista completa de todos os tokens de namespace e os tokens de atributo dentro deles, consulte Tokens de relação de dispositivo em SDEL e Tokens de atributo em SDEL.

Noções básicas de sintaxe SDEL

O SDEL usa tokens de atributo para realizar 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, um dado anexado a um destino. Os valores reais no atributo são armazenados como uma VARIANT. Se você colocar um operador de comparação seguido por um valor de teste após o atributo, o SDEL executará uma correspondência de comparação. Você deve colocar 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 em ambas. Se o valor de teste consistir apenas em caracteres alfanuméricos e hífens (-), 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 por meio 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 (>=)

Bitwise E (&)

Esse operador força os tipos a VT_I8 antes de executar um bit a bit AND 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), a correspondência será satisfeita.

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 atributo

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 no SDEL.

Para usar qualquer atributo que esteja fora do namespace raiz, você deve 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::IsRemovível.

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 destino.

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

Para obter uma lista completa de tokens de atributo, consulte Tokens de atributo no SDEL.

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

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 para Eval um atributo, mas nenhum operador ou valor de comparação, Eval retornará VARIANT_TRUE se o atributo ou namespace contiver 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 que não possuem um operador de comparação, mas contêm um valor VT_BOOL , têm uma comparação implícita '=true' aplicada a eles. Essa comparação implícita significa que "IsDisable" é equivalente a "IsDisable='true'".

Relações de navegação

O teste geralmente envolve examinar o que acontece quando dispositivos relacionados mudam de estado. Por exemplo, quando um hub USB é desabilitado, os dispositivos conectados a ele manipulam a alteração de estado corretamente? Além disso, convém localizar um dispositivo com base em informações em dispositivos relacionados. Para oferecer 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 de um destino.

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 de 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 você pode recuperar da propriedade RootDevice ). (Para obter mais informações sobre dispositivos fantasmas, consulte Criando cenários WDTF.)

Coletando destinos usando GetRelations

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

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 destinos 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 atenda ao relacionamento específico. 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 desabilitados.

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

Coletando destinos usando 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 da interface de coleção IWDTFTargets2 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 a IWDTFDeviceDepot2::Query. IWDTFTargets2::Query retorna um subconjunto de destinos da coleção original que atende à instrução SDEL.

Lógica Booleana em SDEL

O método IWDTFTarget2::GetRelations pode aceitar somente o operador Boolean OR, mas suas chamadas para os métodos IWDTFTargets2::Query, IWDTFTarget2::Eval e IWDTFTarget2::GetValue podem usar operadores booleanos AND e OR. Para o método Query e o método Eval, os operadores agirão como operadores booleanos normais, retornando o resultado conforme o esperado. No entanto, para o método GetValue , AND irá compor os valores em ambos os lados de si mesmo, e OR retornará apenas o primeiro valor encontrado (começando com a 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 em uma relação ou namespace.

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

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 filho com mídia removível maior que 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.

Observação

Um atributo com erros ortográficos, namespace ou token de relação não causa um erro de sintaxe, porque o SDEL foi projetado para ser dinâmico com base no destino: as instruções SDEL devem ser capazes de consultar a existência de um atributo em um conjunto de campos dinâmicos.