Event Filters

Event filters provide simple event filtering; they influence how the debugger engine proceeds after an event occurs in a target. When an event occurs, the engine determines whether that event matches an event filter. If it does, the break status for the event filter influences whether the debugger will break into the target. If the event is an exception event, the handling status determines whether the exception should be considered handled or not-handled in the target.

Note  If more sophisticated event filtering is required, event callbacks can be used.

Event filters are divided into three categories.

1. Specific event filters. These are the filters for all the non-exception events. See DEBUG_FILTER_XXX for a list of these events.
2. Specific exception filters. The first specific exception filter is the default exception filter. The rest are filters for those exceptions for which the engine has built-in filters. See Specific Exceptions for a list of the specific exception filters.
3. Arbitrary exception filters. These are filters for exception events that have been added manually.

The filters in categories 1 and 2 are collectively known as specific filters, and the filters in categories 2 and 3 are collectively known as exception filters. The number of filters in each category is returned by GetNumberEventFilters.

An event matches a specific event filter if the type of the event is the same as the type of the filter. Some event filters have an additional parameter which further restricts the events they match.

An exception event matches an exception filter if the exception code for the exception event is the same as the exception code for the exception filter. If there is no exception filter with the same exception code as the exception event, the exception event will be handled by the default exception filter.

Commands and Parameters

Event filters can have a debugger command associated with them. This command is executed by the engine when an event matching the filter occurs. GetEventFilterCommand and SetEventFilterCommand can be used to get and set this command. For exception filters, this command is executed on the first-chance of the exception. A separate second-chance command can be executed upon the second-chance exception event. To get and set the second-chance command, use GetExceptionFilterSecondCommand and SetExceptionSecondChanceCommand.

The parameters for specific event filters and exception filters are returned by GetSpecificFilterParameters and GetExceptionFilterParameters. The break status and handling status for event filters can be set using SetSpecificFilterParameters and SetExceptionFilterParameters.

SetExceptionFilterParameters can also be used to add and remove arbitrary exception filters.

A short description of specific filters is returned by GetEventFilterText.

Some specific filters take arguments that restrict which events the filter matches. GetSpecificFilterArgument and SetSpecificFilterArgument will get and set arguments for those specific filters which support arguments. If a specific filter has no argument, there is no restriction on which events it matches. The following table lists the event filters that take arguments and how they restrict the events which match them:

Notes  

1. The argument uses the string wildcard syntax and is compared with the image name (ignoring path) when the event occurs. If the name of the module or process is not available, it is considered a match.
2. The argument is an expression that is evaluated by the engine when the argument is set.
3. The argument uses the string wildcard syntax and is compared with the debug output from the target. If the output is not known, it is considered a match.

Index and Exception Code

Each event filter has an index. The index is a number between zero and one less than the total number of filters (inclusive). The index range for each category of filters can be found from the SpecificEvents, SpecificExceptions, and ArbitraryExceptions values returned by GetNumberEventFilters, as described in the following table:

The indices for the specific event filters are found in the first table located in the topic DEBUG_FILTER_XXX. The index of the default exception filter (the first specific exception filter) is SpecificEvents. When an arbitrary exception filter is removed, the indices of the other arbitrary exception filters can change.

The exception filters are usually specified by exception code. However, some methods require the index of the exception. To find the index of an exception filter for a given exception, use GetExceptionFilterParameters to iterate over all the exception filters until you find the one with the same exception code as the exception. The exception codes for the specific exception filters can be found in the topic Specific Exceptions.

System Errors

When a system error occurs, the engine will break into the debugger or print the error to the output stream, if the error occurs at or below specified levels. These levels are returned by GetSystemErrorControl and can be changed using SetSystemErrorControl.