Фильтры событий

Фильтры событий обеспечивают простую фильтрацию событий; они влияют на работу подсистемы отладчика после возникновения события в целевом объекте. При возникновении события подсистема определяет, соответствует ли это событие фильтру событий. Если это так, состояние останова для фильтра событий влияет на то, будет ли отладчик врезаться в целевой объект. Если событие является событием исключения, состояние обработки определяет, следует ли считать исключение обработанным или не обработанным в целевом объекте.

Примечание Если требуется более сложная фильтрация событий, можно использовать обратные вызовы событий.

Фильтры событий делятся на три категории.

1. Фильтры конкретных событий. Это фильтры для всех событий, не являющихся исключениями. Список этих событий см. в разделе DEBUG_FILTER_XXX .

2. Фильтры конкретных исключений. Первый конкретный фильтр исключений — это фильтр исключений по умолчанию. Остальные — это фильтры для тех исключений, для которых подсистема имеет встроенные фильтры. Список определенных фильтров исключений см. в разделе Конкретные исключения.

3. Произвольные фильтры исключений. Это фильтры для событий исключений, добавленных вручную.

Фильтры в категориях 1 и 2 в совокупности называются конкретными фильтрами, а фильтры в категориях 2 и 3 в совокупности называются фильтрами исключений. Количество фильтров в каждой категории возвращается методом GetNumberEventFilters.

Событие соответствует определенному фильтру событий, если тип события совпадает с типом фильтра. Некоторые фильтры событий имеют дополнительный параметр, который дополнительно ограничивает соответствующие события.

Событие исключения соответствует фильтру исключений, если код исключения для события исключения совпадает с кодом исключения для фильтра исключений. Если фильтр исключений с тем же кодом исключения, что и событие исключения, отсутствует, событие исключения будет обрабатываться фильтром исключений по умолчанию.

Команды и параметры

С фильтрами событий может быть связана команда отладчика. Эта команда выполняется подсистемой при возникновении события, соответствующего фильтру. GetEventFilterCommand и SetEventFilterCommand можно использовать для получения и задания этой команды. Для фильтров исключений эта команда выполняется при первом возникновении исключения. Отдельную команду второго шанса можно выполнить при событии исключения второго шанса. Чтобы получить и задать команду второго шанса, используйте командлеты GetExceptionFilterSecondCommand и SetExceptionSecondChanceCommand.

Параметры для определенных фильтров событий и фильтров исключений возвращаются getSpecificFilterParameters и GetExceptionFilterParameters. Состояние останова и состояние обработки для фильтров событий можно задать с помощью setSpecificFilterParameters и SetExceptionFilterParameters.

SetExceptionFilterParameters также можно использовать для добавления и удаления произвольных фильтров исключений.

Краткое описание определенных фильтров возвращается методом GetEventFilterText.

Некоторые конкретные фильтры принимают аргументы, ограничивающие, какие события соответствуют фильтру. GetSpecificFilterArgument и SetSpecificFilterArgument будут получать и задавать аргументы для конкретных фильтров, поддерживающих аргументы. Если у определенного фильтра нет аргументов, нет ограничений на то, какие события он соответствует. В следующей таблице перечислены фильтры событий, которые принимают аргументы, и способы их ограничения на соответствующие события.

Событие	Критерии соответствия
Создание процесса	Имя созданного процесса должно соответствовать аргументу.1
Выход из процесса	Имя завершенного процесса должно соответствовать аргументу 1.
Модуль загрузки	Имя загруженного модуля должно соответствовать аргументу .1
Выгрузка модуля	Базовый адрес выгруженного модуля должен совпадать с аргументом 2.
Целевые выходные данные	Выходные данные отладки целевого объекта должны соответствовать аргументу 3.

Примечание  

1. Аргумент использует синтаксис подстановочных знаков строки и сравнивается с именем изображения (игнорируя путь) при возникновении события. Если имя модуля или процесса недоступно, оно считается совпадением.

2. Аргумент — это выражение, которое вычисляется подсистемой при установке аргумента.

3. Аргумент использует синтаксис строковых подстановочных знаков и сравнивается с выходными данными отладки целевого объекта. Если выходные данные неизвестны, они считаются совпадением.

Индекс и код исключения

Каждый фильтр событий имеет индекс. Индекс — это число от нуля до единицы меньше общего числа фильтров (включительно). Диапазон индексов для каждой категории фильтров можно найти в значениях SpecificEvents, SpecificExceptions и Произвольные Исключения , возвращаемых GetNumberEventFilters, как описано в следующей таблице:

Фильтры событий	Индекс первого фильтра	Количество фильтров
Фильтры определенных событий	0	SpecificEvents
фильтры конкретных исключений	SpecificEvents	SpecificExceptions
фильтры произвольных исключений	SpecificEvents + SpecificExceptions	Произвольные выражения

Индексы для определенных фильтров событий находятся в первой таблице, расположенной в разделе DEBUG_FILTER_XXX. Индекс фильтра исключений по умолчанию (первый конкретный фильтр исключений) — SpecificEvents. При удалении произвольного фильтра исключений индексы других фильтров произвольных исключений могут измениться.

Фильтры исключений обычно задаются кодом исключения. Однако для некоторых методов требуется индекс исключения. Чтобы найти индекс фильтра исключений для заданного исключения, используйте Метод GetExceptionFilterParameters для итерации по всем фильтрам исключений, пока не найдете тот, с тем же кодом исключения, что и исключение. Коды исключений для определенных фильтров исключений можно найти в разделе Конкретные исключения.

Системные ошибки

При возникновении системной ошибки подсистема врывается в отладчик или выводит ошибку в поток вывода, если ошибка возникает на уровне или ниже указанного уровня. Эти уровни возвращаются GetSystemErrorControl и могут быть изменены с помощью SetSystemErrorControl.