Simple Data Evaluation Language の概要

[アーティクル]
04/04/2024

WDTF には、属性または関係に基づいてターゲットを収集するタスクを簡略化する単純なクエリ言語が含まれています。単純なデータ評価言語 (SDEL) は XPath に似ています。 XPath の詳細については、「XPath リファレンス」をご参照ください。

このトピックの以降のセクションでは、SDEL の使用方法について説明します。

Note

すべての名前空間トークンとその中の属性トークンの完全な一覧については、「SDEL のデバイス関係トークン」および「SDEL の属性トークン」をご参照ください。

SDEL 構文の基本

SDEL は属性トークンを使用して一致を実行し、データを取得します。すべての SDEL トークンには、英数字とハイフン (-) のみを含めることができます。

属性は、ターゲットにアタッチされているデータを指します。属性の実際の値は VARIANT として格納されます。属性の後に比較演算子の後にテスト値を配置すると、SDEL は比較一致を実行します。テスト値は単一引用符または二重引用符で囲む必要があります。この表記を使用すると、テスト値に実際の単一引用符または二重引用符を使用できますが、両方を使用することはできません。テスト値が英数字とハイフン (-) のみで構成されている場合は、引用符を省略できます。

比較演算

SDEL を使用すると、さまざまな比較演算子が属性トークンに従います。比較時に、演算子の左側にある属性の実際の値は、VariantChangeType メソッド (Microsoft Windows SDK ドキュメントで説明) を使用して、演算子の右側にあるテスト値と同じ型になります。次の表は、SDELがサポートするさまざまな比較演算子を示しています。

等値を意味する比較演算子 (=)

型が変更されると、VarCmp メソッド (Windows SDK ドキュメントで説明) を使用して型が比較されます。

不等式 (!=)

より小さい (<)

次の値以下 (<=)

より大きい (>)

次の値以上 (>=)

ビット演算子 AND (&)

この演算子は、実際の値とテスト値のビットごとの AND を実行する前に、型を強制的にVT_I8します。

比較操作 (および値なし) が指定されていない

属性の実際の値がVT_BOOL型の場合、その値に基づいて一致が満たされます。つまり、"IsDisableable=True" を実行するために比較演算子は必要ありません。それ以外の場合(VT_EMPTY以外の値がある場合)、一致が満たされます。

属性に複数の実際の値 (または配列) がある場合は、逆の動作を持つ不等値演算子を除き、すべての比較演算子を少なくとも 1 つと一致するように解釈する必要があります。型をまったく比較できない場合 (つまり、VariantChangeType が失敗した場合)、一致はありません (逆の動作を持つ不等値演算子を除きます)。

属性名前空間についての理解

SDEL では、名前空間トークンを使用して属性をグループ化します。すべての名前空間トークンとその中の属性トークンの完全な一覧については、「SDEL の属性トークン」をご参照ください。

ルート名前空間の外部にある属性を使用するには、属性の前に名前空間名を付け、次に 2 つのコロン (::) を付ける必要があります。次の VBScript コード例では、Disk::IsRemovable 属性の値を表示します。

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

GetValue と Eval を使用してターゲットを調べる

IWDTFTarget2::GetValue メソッドを使用すると、その属性についてターゲットに問い合わせることができます。次の VBScript コード例では、ターゲットの FriendlyName 属性の値を出力します。

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

属性トークンの完全な一覧については、「SDEL の属性トークン」をご参照ください。

IWDTFTarget2::Eval メソッドを使用して、ターゲットに対して SDEL ステートメントを評価することもできます。 Eval は、VARIANT_TRUE または VARIANT_FALSE を返します。次の VBScript コード例では、Eval を使用して、デバイスを無効にできるかどうかを判断します。

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

Eval を使用して、属性の存在をテストすることもできます。属性に Eval を渡しても、比較演算子または値を渡さない場合、属性または名前空間に値 (VT_EMPTY 以外) が保持されている場合、Eval は VARIANT_TRUE を返します。次の VBScript コード例では、Eval を使用して、ターゲットに SymbolicLink キーワードがあるかどうかを判断します。

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

さらに、比較演算子がないが、VT_BOOL 値を含む属性には、暗黙的な '=true' 比較が適用されます。この暗黙的な比較は、"IsDisableable" が "IsDisableable='true' と等価であることを意味します。

リレーションシップのナビゲーション

多くの場合、テストには、関連するデバイスの状態が変化したときに何が起こるかを調べることが含まれます。たとえば、USB ハブが無効になっている場合、接続されているデバイスは状態の変化を適切に処理しますか? さらに、関連するデバイスの情報に基づいてデバイスを検索することもできます。この機能をサポートするために、SDEL には、属性または名前空間の前に 1 つ以上の論理リレーションシップを指定する方法が含まれています (どちらの後も指定できません)。リレーションシップトークンは、属性または名前空間からスラッシュ (/) で区切られます。次の VBScript コード例では、ターゲットの親デバイスの FriendlyName 属性の値を出力します。

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

関係修飾子を組み合わせることもできます。次の VBScript コード例では、ターゲットオブジェクトの祖父母デバイスの FriendlyName 属性の値を出力します。

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

デバイスに多対多のリレーションシップがある場合があります。たとえば、論理ストレージボリュームが多数の物理ディスクに存在し、それらの個々のディスクが多くのボリュームに領域を提供する場合があります。

WDTF 内では、非ファントムデバイス (つまり、物理的に存在するデバイス) はすべてルートデバイスの子孫です (RootDevice プロパティから取得できます)。 (ファントムデバイスの詳細については、「WDTF シナリオの作成」をご参照ください。)

GetRelations を使用したターゲットの収集

次の図は、IWDTFTarget2::GetRelations メソッドを示しています。

個々のターゲットと関連するターゲットを示す WDTF の Target::GetRelations メソッドを示す図。

IWDTFTarget2::GetRelations メソッドは、SDEL ステートメント構文の関係指定子部分のみを受け入れ、リレーションシップ条件を満たすすべてのターゲットを含む IWDTFTargets2 コレクションインターフェイスを返します。次の VBScript コード例は、元のターゲットとそのすべての兄弟を含むコレクションを返します。

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

GetRelations の 2 番目のパラメーターには、必要に応じて、特定のリレーションシップを満たす各ターゲットの Eval メソッドに渡されるステートメントを含めることができます。たとえば、2 番目のパラメーターとして IsDisableable=true を追加すると、前のコード例では、無効にできるデバイスとその兄弟のみが返されます。

一致するものがない場合は、項目が0のコレクションが返されます。

クエリを使用したターゲットの収集

IWDTFDeviceDepot2 インターフェイスには、Query メソッドが含まれています。このメソッドは、IWDTFTarget2::Eval メソッド用に設計された SDEL ステートメントを受け取り、クエリの条件を満たすターゲットのサブセットを含む IWDTFTargets2 コレクションインターフェイスの新しいインスタンスを返します。次の VBScript コード例では、非ファントムデバイスをすべて列挙し、各デバイスのフレンドリ名を示します。

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

返されるコレクションには、IWDTFTargets2::Query と同じ実装を持つ IWDTFDeviceDepot2::Query メソッドがあります。 IWDTFTargets2::Query は、SDEL ステートメントを満たす元のコレクションからターゲットのサブセットを返します。

SDEL のブール論理

IWDTFTarget2::GetRelations メソッドは、ブール OR 演算子のみを受け入れることができますが、IWDTFTargets2::Query メソッド、IWDTFTarget2::Eval メソッド、および IWDTFTarget2::GetValue メソッドの呼び出しでは、ブール AND 演算子と OR 演算子を使用できます。 Query メソッドと Eval メソッドの場合、演算子は通常のブール演算子と同様に動作し、期待どおりに結果を返します。ただし、GetValue メソッドの場合、AND はそれ自体の両側の値を構成し、OR は見つかった最初の値 (左から始まる) のみを返します。

SDEL の括弧

すべての SDEL ステートメントでは、括弧を使用してブールロジックの評価シーケンスを指定できます。括弧を使用して、ステートメント内のサブ要素をリレーションまたは名前空間の下にグループ化することもできます。

次の VBScript コード例では、祖父母デバイスのすべてのボリュームと子を取得します。

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

次の VBScript コード例では、1,000,000 バイトを超えるリムーバブルメディアを持つ子を持つすべてのデバイスを取得します。

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

SDEL 構文解析

構文が正しくない SDEL ステートメントを WDTF 内のいずれかのメソッドに渡すと、メソッドは失敗し、詳細なエラー情報が返され、問題が説明されます。