Interfaces supplémentaires C++ du modèle de données du débogueur
Cette rubrique décrit quelques interfaces supplémentaires associées au modèle de données Debugger C++, telles que les métadonnées, les concepts et l’énumération des objets.
Interfaces de métadonnées du modèle de données du débogueur
L’une des notions fondamentales dans le modèle de données est qu’un objet (particulièrement un objet synthétique) est un dictionnaire de tuples clé/valeur/métadonnées. Chaque clé peut avoir un ensemble complet de métadonnées associées qui décrivent une variété de choses concernant la clé et sa valeur potentielle. Notez que les métadonnées ne modifient en aucun cas la valeur de la clé. Il s’agit uniquement d’informations auxiliaires associées à la clé et à sa valeur qui peuvent affecter la présentation ou d’autres attributs associés de la clé et de sa valeur.
Dans un certain sens, un magasin de métadonnées n’est pas si différent des tuples clé/valeur/métadonnées qui sont l’essence d’un objet dans le modèle de données. Cependant, il est simplifié par rapport à cette vue. Un magasin de métadonnées est représenté par l’interface IKeyStore. Bien qu’il s’agisse également d’une collection de tuples clé/valeur/métadonnées, il existe des limitations quant à ce qui peut être fait avec un magasin de clés de métadonnées par rapport à un objet modèle :
- Un magasin de clés ne peut avoir qu’un seul magasin parent - il ne peut pas avoir une chaîne arbitraire de modèles parents.
- Un magasin de clés n’a pas de concepts. Il ne peut avoir que le dictionnaire de tuples clé/valeur/métadonnées. Cela signifie que les clés présentes dans un magasin de clés sont statiques. Elles ne peuvent pas être créées à la demande par un système de langage dynamique.
- Par convention uniquement, les valeurs dans un magasin de clés défini par des métadonnées sont limitées à des valeurs de base (intrinsèques et accesseurs de propriétés)
Bien qu’un magasin de clés puisse avoir un nombre arbitraire (et des noms arbitraires) de clés, certains noms ont des valeurs sémantiques définies. Actuellement, ces noms sont :
| Nom de la clé | Type de valeur | Description |
|---|---|---|
| PreferredRadix | Entier : 2, 8, 10 ou 16 | Indique la base dans laquelle une valeur ordinale doit être affichée |
| PreferredFormat | Entier : tel que défini par l’énumération PreferredFormat | Indique le type de formatage préféré pour l’affichage de la valeur |
| PreferredLength | Integer | Pour les tableaux et autres conteneurs, indique combien d’éléments doivent être affichés par défaut |
| FindDerivation | Boolean | Indique si l’hôte de débogage doit effectuer une analyse de type dérivé sur la valeur avant de l’utiliser (par exemple : affichage) |
| Aide | Chaîne | Texte d’aide de style info-bulle pour la clé qui peut être présenté par l’interface utilisateur de manière appropriée |
| ActionName | Chaîne | Indique que la méthode donnée (celle qui ne prend aucun argument et ne retourne aucune valeur) est une action. Le nom de l’action est spécifié dans les métadonnées. Une interface utilisateur peut utiliser ce nom pour présenter l’option dans un menu contextuel ou une autre interface appropriée |
| ActionIsDefault | Boolean | Seulement valide si la clé ActionName est spécifiée, indique qu’il s’agit de l’action par défaut pour l’objet. |
| ActionDescription | Chaîne | Seulement valide si la clé ActionName est spécifiée, ceci donne une description de style info-bulle pour l’action. Ce type de texte peut être présenté par l’interface utilisateur de manière appropriée. |
Notez que bien que les clés dans le magasin de métadonnées puissent avoir leurs propres métadonnées (ad infinitum), il n’y a actuellement aucune utilisation pour cela. La plupart des appelants spécifieront null pour tous les paramètres de métadonnées dans les méthodes de l’interface IKeyStore.
L’interface principale de métadonnées : IKeyStore
L’interface IKeyStore est définie comme suit :
DECLARE_INTERFACE_(IKeyStore, IUnknown)
{
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_ IModelObject* object) PURE;
STDMETHOD(ClearKeys)() PURE;
}
La méthode GetKey est analogue à la méthode GetKey sur IModelObject. Elle renverra la valeur de la clé spécifiée si elle existe dans le magasin de clés ou dans le magasin parent du magasin de clés. Notez que si la valeur de la clé est un accesseur de propriétés, la méthode GetValue ne sera pas appelée sur l’accesseur de propriétés. L’IModelPropertyAccessor réel encapsulé dans un IModelObject sera renvoyé. Il est typique qu’un client appelle GetKeyValue pour cette raison.
La méthode SetKey est analogue à la méthode SetKey sur IModelObject. C’est la seule méthode capable de créer une clé et d’y associer des métadonnées dans le magasin de clés.
La méthode GetKeyValue est la première méthode qu’un client utilisera pour trouver la valeur d’une clé particulière dans le magasin de métadonnées. Si la clé spécifiée par l’argument key existe dans le magasin (ou son magasin parent), la valeur de cette clé et toutes les métadonnées associées seront renvoyées. Si la valeur de la clé est un accesseur de propriétés (un IModelPropertyAccessor encapsulé dans un IModelObject), la méthode GetValue de l’accesseur de propriétés sera automatiquement appelée par GetKeyValue et la valeur sous-jacente de la propriété sera renvoyée.
La méthode SetKeyValue est analogue à la méthode SetKeyValue sur IModelObject. Cette méthode n’est pas capable de créer une nouvelle clé dans le magasin de métadonnées. S’il existe une clé existante comme indiqué par l’argument key, sa valeur sera définie comme indiqué. Si la clé est un accesseur de propriétés, la méthode SetValue sera appelée sur l’accesseur de propriétés afin de définir la valeur sous-jacente. Notez que les métadonnées sont généralement statiques une fois créées. L’utilisation de cette méthode sur un magasin de clés de métadonnées devrait être peu fréquente.
La méthode ClearKeys est analogue à la méthode ClearKeys sur IModelObject. Elle supprimera chaque clé du magasin de métadonnées donné. Cette méthode n’a aucun effet sur un magasin parent.
Énumération des objets dans le modèle de données
Énumérer les objets dans le modèle de données
Il existe deux interfaces principales d’énumération de clés dans le modèle de données : IKeyEnumerator et IRawEnumerator. Bien que ce soient les deux interfaces principales, elles peuvent être utilisées pour énumérer les objets de trois manières :
Clés : l’interface IKeyEnumerator peut être obtenue via un appel à EnumerateKeys afin d’énumérer les clés d’un objet et leurs valeurs/métadonnées sans résoudre aucun accesseur de propriétés sous-jacent. Ce style d’énumération peut renvoyer des valeurs brutes IModelPropertyAccessor encapsulées dans des IModelObjects.
Valeurs : les interfaces IKeyEnumerator et IRawEnumerator peuvent être obtenues via des appels à EnumerateKeyValues ou EnumerateRawValues afin d’énumérer les clés/valeurs brutes sur un objet et leurs valeurs/métadonnées. Tous les accesseurs de propriétés présents dans l’énumération sont automatiquement résolus via un appel à la méthode GetValue sous-jacente lors d’une telle énumération.
Références : les interfaces IKeyEnumerator et IRawEnumerator peuvent être obtenues via des appels à EnumerateKeyReferences ou EnumerateRawReferences afin d’énumérer les références aux clés/valeurs brutes sur un objet. Ces références peuvent être sauvegardées et utilisées plus tard pour obtenir ou définir la clé ou la valeur brute sous-jacente.
KeyEnumerator : Énumération des clés synthétiques
L’interface IKeyEnumerator est l’interface unique pour l’énumération de toutes les clés (par clé, valeur ou référence) dans un objet d’instance et tous les modèles parents associés dans sa chaîne de modèles parents. L’interface se définit comme suit :
DECLARE_INTERFACE_(IKeyEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR* key, _COM_Errorptr_opt_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
}
La méthode Reset réinitialise l’énumérateur à la position qu’il occupait lorsqu’il a été acquis pour la première fois (par exemple : avant le premier élément de l’énumération). Un appel ultérieur à GetNext renverra la première clé énumérée.
La méthode GetNext déplace l’énumérateur vers l’avant et renvoie la clé à cette position dans l’énumération.
IRawEnumerator : Énumération des constructions natives ou de langage sous-jacentes (C/C++)
L’interface IRawEnumerator est l’interface unique pour l’énumération de toutes les constructions natives/du langage (par valeur ou référence) dans un objet qui représente une construction native dans l’espace d’adressage de la cible de débogage. L’interface se définit comme suit :
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
La méthode Reset réinitialise l’énumérateur à la position qu’il occupait lorsqu’il a été acquis pour la première fois (par exemple : avant le premier élément de l’énumération). Un appel ultérieur à GetNext renverra la première construction native/du langage énumérée.
La méthode GetNext déplace l’énumérateur vers l’avant et renvoie la construction native/du langage à cette position dans l’énumération.
Voir aussi
Cette rubrique fait partie d’une série qui décrit les interfaces accessibles à partir de C++, comment les utiliser pour générer une extension de débogueur C++ et comment utiliser d’autres constructions de modèle de données (par exemple, JavaScript ou NatVis) à partir d’une extension de modèle de données C++.
Vue d’ensemble du modèle de données du débogueur C++
Interfaces C++ du modèle de données du débogueur
Objets C++ du modèle de données du débogueur
Interfaces supplémentaires C++ du modèle de données du débogueur