イベント フィルター

イベント フィルター は、単純なイベント フィルター処理を提供します。これは、ターゲットでイベントが発生した後のデバッガー エンジンの進行方法に影響します。 イベントが発生すると、エンジンはそのイベントがイベント フィルターと一致するかどうかを判断します。 その場合、イベント フィルターの中断状態は、デバッガーがターゲットで中断されるかどうかに影響します。 イベントが例外イベントの場合、処理状態が、例外がターゲットで処理済みとみなすか、処理済みでないとみなすかを判断します。

注意: より高度なイベント フィルターが必要な場合は、イベント コールバックを使用できます。

イベント フィルターは、3 つのカテゴリに分かれています。

1. 特定のイベント フィルター。 これらは、すべての非例外イベントのフィルターです。 これらのイベントの一覧については、「DEBUG_FILTER_XXX」を参照してください。

2. 特定の例外フィルター。 最初の特定の例外フィルターは、既定の例外フィルターです。 残りは、エンジンに組み込みフィルターがある例外のフィルターです。 特定の例外フィルターの一覧については、「特定の例外」を参照してください。

3. 任意例外フィルター。 これらは、手動で追加された例外イベントのフィルターです。

カテゴリ 1 とカテゴリ 2 のフィルターは、特定のフィルターと総称され、カテゴリ 2 とカテゴリ 3 のフィルターは、例外フィルターと総称されます。 各カテゴリのフィルター数は、GetNumberEventFilters によって返されます。

イベントの種類がフィルターの型と同じ場合、イベントは特定のイベント フィルターと一致します。 一部のイベント フィルターには、一致するイベントをさらに制限する追加のパラメーターがあります。

例外イベントの例外コードが例外フィルターの例外コードと同じ場合、例外イベントは例外フィルターと一致します。 例外イベントと同じ例外コードを持つ例外フィルターがない場合、例外イベントは既定の例外フィルターによって処理されます。

コマンドおよびパラメーター

イベント フィルターには、debugger コマンドを関連付けることができます。 このコマンドは、フィルターに一致するイベントが発生したときにエンジンによって実行されます。 GetEventFilterCommand と SetEventFilterCommand を使用して、このコマンドを取得および設定できます。 例外フィルターの場合、このコマンドは例外が最初に発生した場合に実行されます。 second-chance 例外イベントに対しては、別の second-chance コマンドを実行できます。 second-chance コマンドの取得と設定には、GetExceptionFilterSecondCommand および SetExceptionSecondChanceCommand を使用します。

特定のイベント フィルターと例外フィルターのパラメーターは、GetSpecificFilterParameters と GetExceptionFilterParameters によって返されます。 イベント フィルターの中断状態と処理状態は、SetSpecificFilterParameters および SetExceptionFilterParameters を使用して設定できます。

SetExceptionFilterParameters を使用すると、任意の例外フィルターを追加および削除することもできます。

特定のフィルターの簡単な説明は、GetEventFilterText によって返されます。

一部の特定のフィルターは、フィルターが一致するイベントを制限する引数を受け取ります。 GetSpecificFilterArgument および SetSpecificFilterArgument は、引数をサポートする特定のフィルターの引数を取得および設定します。 特定のフィルターに引数がない場合、一致するイベントに制限はありません。 次の表に、引数を受け取るイベント フィルターと、それらに一致するイベントを制限する方法を示します。

イベント	一致条件
プロセスの作成	作成されたプロセスの名前が argument.1 と一致している必要があります
プロセスの終了	終了したプロセスの名前が argument.1 と一致している必要があります
モジュールの読み込み	読み込まれたモジュールの名前が argument.1 と一致している必要があります
モジュールのアンロード	アンロードされたモジュールのベース アドレスは、argument.2 と同じである必要があります。
ターゲット出力	ターゲットからのデバッグ出力が argument.3 と一致している必要があります。

注  

1. 引数は、イベント発生時、string wildcard syntax を使用して、イメージ名 (無視されたパス) と比較します。 モジュールまたはプロセスの名前が使用できない場合は、一致と見なされます。

2. 引数は、引数が設定されたときにエンジンによって評価される式です。

3. 引数は、string wildcard syntax を使用し、ターゲットからのデバッグ出力と比較されます。 出力が不明な場合は、一致と見なされます。

インデックスと例外コード

各イベント フィルターにはインデックスがあります。 インデックスは、フィルターの総数より 0 および 1 (両方の数字を含む) より小さい間の数です。 フィルターの各カテゴリのインデックス範囲は、次の表で示すように、GetNumberEventFilters が返す SpecificEvents、SpecificExceptions および ArbitraryExceptions 値から確認できます。

イベント フィルター	最初のフィルターのインデックス	フィルター数
特定のイベント フィルター	0	SpecificEvents
特定の例外フィルター。	SpecificEvents	SpecificExceptions
任意例外フィルター	SpecificEvents + SpecificExceptions	ArbitraryExceptions

特定のイベント フィルターのインデックスは、トピック DEBUG_FILTER_XXX にある最初のテーブルにあります。 既定の例外フィルター (最初の特定の例外フィルター) のインデックスは SpecificEvents です。 任意の例外フィルターが削除されると、他の任意の例外フィルターのインデックスが変更される可能性があります。

例外フィルターは通常、例外コードによって指定されます。 ただし、一部のメソッドでは例外のインデックスが必要です。 特定の例外の例外フィルターのインデックスを検索するには、GetExceptionFilterParameters を使用して、例外と同じ例外コードを持つフィルターが見つかるまで、すべての例外フィルターを反復処理します。 特定の例外フィルターの例外コードについては、トピック「特定の例外」を参照してください。

System Errors (システム エラー)

システム エラーが発生すると、指定したレベル以下でエラーが発生した場合、エンジンはデバッガーで中断するか、エラーを出力ストリームに出力します。 これらのレベルは GetSystemErrorControl で返され、SetSystemErrorControl を使用して、変更できます。