Filtres d’événements

Les filtres d’événements fournissent un filtrage d’événements simple ; elles influencent la façon dont le moteur de débogueur se déroule après qu’un événement se produit dans une cible. Lorsqu’un événement se produit, le moteur détermine si cet événement correspond à un filtre d’événement. Si c’est le cas, la status d’arrêt du filtre d’événements détermine si le débogueur s’infiltre dans la cible. Si l’événement est un événement d’exception, le status 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 requis, des 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. Il s’agit des filtres pour tous les événements non-exception. Consultez DEBUG_FILTER_XXX pour obtenir la liste de ces événements.

2. Filtres d’exception 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 dispose de filtres intégrés. Pour obtenir la liste des filtres d’exceptions spécifiques, consultez 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 des 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 auxquels 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 pour le 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

Une commande de débogueur peut être associée aux filtres d’événements. 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’exception, cette commande est exécutée à 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 deuxième chance, 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. La status d’arrêt et la gestion des status pour les filtres d’événements peuvent être définies à l’aide de SetSpecificFilterParameters et de SetExceptionFilterParameters.

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

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

Certains filtres spécifiques prennent des arguments qui limitent les événements auxquels le filtre correspond. GetSpecificFilterArgument et SetSpecificFilterArgument obtiennent et définissent des arguments pour les filtres spécifiques qui prennent en charge les arguments. Si un filtre spécifique n’a aucun argument, il n’existe aucune restriction quant aux événements auxquels 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 :

Événement	Critères de correspondance
Créer un processus	Le nom du processus créé doit correspondre à l’argument.1
Processus de sortie	Le nom du processus arrêté doit correspondre à l’argument.1
Module de chargement	Le nom du module chargé doit correspondre à l’argument.1
Décharger le module	L’adresse de base du module déchargé doit être identique à l’argument.2
Sortie cible	La sortie de débogage de la cible doit correspondre à l’argument.3

Remarque  

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

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

3. L’argument utilise la syntaxe générique de chaîne 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 correspondance.

Index et code 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 est disponible à partir des valeurs SpecificEvents, SpecificExceptions et ArbitraryExceptions retournées par GetNumberEventFilters, comme décrit dans le tableau suivant :

Filtres d’événements	Index du premier filtre	Nombre de filtres
Filtres d’événements spécifiques	0	Événements spécifiques
filtres d’exceptions spécifiques	Événements spécifiques	SpecificExceptions
filtres d’exceptions arbitraires	+ Événements spécifiquesSpecificExceptions	ArbitraireExceptions

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’exception jusqu’à ce que vous trouviez celui qui contient le même code d’exception que l’exception. Les codes d’exception des filtres d’exception spécifiques se trouvent dans la rubrique Exceptions spécifiques.

Erreurs système

Lorsqu’une erreur système se produit, le moteur s’insère dans le débogueur ou imprime l’erreur dans le flux de sortie, si l’erreur se produit au niveau ou en dessous des niveaux spécifiés. Ces niveaux sont retournés par GetSystemErrorControl et peuvent être modifiés à l’aide de SetSystemErrorControl.