Filtres d’événements

Les filtres d’événements fournissent un filtrage d’événements simple ; ils influencent la façon dont le moteur de débogueur se poursuit après qu’un événement se produise dans une cible. Lorsqu’un événement se produit, le moteur détermine si cet événement correspond à un filtre d’événements. Si c'est le cas, l'état d'arrêt du filtre d'événements détermine si le débogueur s'arrête sur la cible. Si l’événement est un événement d’exception, l’état de gestion détermine si l’exception doit être considérée comme gérée ou non gérée dans la cible.

Note Si un filtrage d’événements plus sophistiqué est nécessaire, les rappels d’événements peuvent être utilisés.

Les filtres d’événements sont divisés en trois catégories.

1. Filtres d’événements spécifiques. Ce sont les filtres pour tous les événements non exceptionnels. Consultez DEBUG_FILTER_XXX pour obtenir la liste de ces événements.

2. Filtres d’exceptions spécifiques. Le premier filtre d’exception spécifique est le filtre d’exception par défaut. Les autres sont des filtres pour les exceptions pour lesquelles le moteur a des filtres intégrés. Consultez exceptions spécifiques pour obtenir la liste des filtres d’exceptions spécifiques.

3. Filtres d’exceptions arbitraires. Il s’agit de filtres pour les événements d’exception qui ont été ajoutés manuellement.

Les filtres des catégories 1 et 2 sont collectivement appelés filtres spécifiques, et les filtres dans les catégories 2 et 3 sont collectivement appelés filtres d’exception. Le nombre de filtres dans chaque catégorie est retourné par GetNumberEventFilters.

Un événement correspond à un filtre d’événements spécifique si le type de l’événement est identique au type du filtre. Certains filtres d’événements ont un paramètre supplémentaire qui limite davantage les événements qu’ils correspondent.

Un événement d’exception correspond à un filtre d’exception si le code d’exception de l’événement d’exception est identique au code d’exception du filtre d’exception. S’il n’existe aucun filtre d’exception avec le même code d’exception que l’événement d’exception, l’événement d’exception est géré par le filtre d’exception par défaut.

Commandes et paramètres

Les filtres d’événements peuvent avoir une commande de débogueur associée. Cette commande est exécutée par le moteur lorsqu’un événement correspondant au filtre se produit. GetEventFilterCommand et SetEventFilterCommand peuvent être utilisés pour obtenir et définir cette commande. Pour les filtres d’exceptions, cette commande est exécutée lors de la première chance de l’exception. Une commande de deuxième chance distincte peut être exécutée lors de l'événement d'exception de deuxième chance. Pour obtenir et définir la commande de traitement des exceptions en second recours, utilisez GetExceptionFilterSecondCommand et SetExceptionSecondChanceCommand.

Les paramètres des filtres d’événements et des filtres d’exception spécifiques sont retournés par GetSpecificFilterParameters et GetExceptionFilterParameters. L’état d’arrêt et l’état de gestion des filtres d’événements peuvent être définis à l’aide de SetSpecificFilterParameters et de SetExceptionFilterParameters.

SetExceptionFilterParameters peut également être utilisé pour ajouter et supprimer des filtres d’exceptions arbitraires.

Une brève description des filtres spécifiques est retournée par GetEventFilterText.

Certains filtres spécifiques acceptent des arguments qui limitent les événements auxquels le filtre correspond. GetSpecificFilterArgument et SetSpecificFilterArgument obtiennent et définissent des arguments pour ces filtres spécifiques qui prennent en charge les arguments. Si un filtre spécifique n’a aucun argument, il n’existe aucune restriction sur les événements qu’il correspond. Le tableau suivant répertorie les filtres d’événements qui prennent des arguments et la façon dont ils limitent les événements qui les correspondent :

Note  

1. L’argument utilise la syntaxe générique de chaîne et est comparé au nom de l’image (ignorer le chemin d’accès) lorsque l’événement se produit. Si le nom du module ou du processus n’est pas disponible, il est considéré comme correspondant.

2. L’argument est une expression évaluée par le moteur lorsque l’argument est défini.

3. L’argument utilise la syntaxe de caractères génériques et est comparé à la sortie de débogage de la cible. Si la sortie n’est pas connue, elle est considérée comme une concordance.

Code d’index et d’exception

Chaque filtre d’événements a un index. L’index est un nombre compris entre zéro et un inférieur au nombre total de filtres (inclus). La plage d’index pour chaque catégorie de filtres se trouve à partir des valeurs SpecificEvents, SpecificExceptions et ArbitraryExceptions retournées par GetNumberEventFilters, comme décrit dans le tableau suivant :

Les index des filtres d’événements spécifiques se trouvent dans la première table située dans la rubrique DEBUG_FILTER_XXX. L’index du filtre d’exception par défaut (le premier filtre d’exception spécifique) est SpecificEvents. Lorsqu’un filtre d’exception arbitraire est supprimé, les index des autres filtres d’exceptions arbitraires peuvent changer.

Les filtres d’exception sont généralement spécifiés par le code d’exception. Toutefois, certaines méthodes nécessitent l’index de l’exception. Pour rechercher l’index d’un filtre d’exception pour une exception donnée, utilisez GetExceptionFilterParameters pour itérer sur tous les filtres d’exceptions jusqu’à ce que vous trouviez celui avec le même code d’exception que l’exception. Les codes d’exception pour les filtres d’exceptions spécifiques sont disponibles dans la rubrique Exceptions spécifiques.

Erreurs système

Lorsqu'une erreur système se produit, le moteur intervient dans le débogueur ou affiche l’erreur sur le flux de sortie, si l'erreur se produit à un niveau spécifié ou inférieur. Ces niveaux sont retournés par GetSystemErrorControl et peuvent être modifiés à l’aide de SetSystemErrorControl.