Anteckning
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Det här avsnittet innehåller och översikt över hur du använder felsökardatamodellens C++-gränssnitt för att utöka och anpassa funktionerna i felsökningsprogrammet.
Data Model C++ Värdgränssnitt för felsökning
datamodellvärden för felsökningsprogrammet
Datamodellen för felsökaren är utformad för att vara ett komponentiserat system som kan hanteras i en mängd olika kontexter. Normalt finns datamodellen i kontexten för ett felsökningsprogram. För att vara en värd för datamodellen måste ett antal gränssnitt implementeras för att exponera kärnaspekter av felsökningsprogrammet: dess mål, dess minnesutrymmen, dess utvärderare, dess symboliska system och typsystem osv. Dessa gränssnitt implementeras av alla program som vill vara värdar för datamodellen, men de används av både kärndatamodellen och alla tillägg som interoperates med datamodellen.
Uppsättningen med kärngränssnitt är:
| Gränssnittsnamn | Beskrivning |
|---|---|
| IDebugHost | Kärngränssnittet till felsökningsvärden. |
| IDebugHostStatus | Ett gränssnitt som gör att en klient kan fråga efter värdens status. |
| IDebugHostContext | En abstraktion av en kontext i värden (t.ex. ett visst mål, en viss process, ett visst adressutrymme osv.) |
| IDebugHostErrorSink | Ett gränssnitt som implementeras av anropare för att ta emot fel från vissa delar av värd- och datamodellen |
| IDebugHostEvaluator/IDebugHostEvaluator2 | Felsök värdens uttrycksutvärdering. |
| IDebugHostExtensibility | Ett gränssnitt för att utöka funktionerna i värden eller delar av den (till exempel uttrycksutvärderaren). |
Typsystemet och symboliska gränssnitt är:
| InterfaceName | Beskrivning |
|---|---|
| IDebugHostSymbols | Kärngränssnitt som ger åtkomst till och upplösning av symboler |
| IDebugHostSymbol/IDebugHostSymbol2 | Representerar en enda symbol av något slag. Den specifika symbolen är en härledning av det här gränssnittet. |
| IDebugHostModule | Representerar en modul som läses in i en process. Det här är en slags symbol. |
| IDebugHostType/IDebugHostType2 | Representerar en in-/språktyp. |
| IDebugHostConstant | Representerar en konstant inom symbolisk information (t.ex. ett mallargument som inte är av typen i C++) |
| IDebugHostField | Representerar ett fält inom en struktur eller klass. |
| IDebugHostData | Representerar data i en modul (om detta fanns i en struktur eller klass skulle det vara ett IDebugHostField) |
| IDebugHostBaseClass | Representerar en basklass. |
| IDebugHostPublic | Representerar en symbol i tabellen publics i en PDB. Detta har inte typinformation associerad med den. Det är ett namn och en adress. |
| IDebugHostModuleSignature | Representerar en modulsignatur – en definition som matchar en uppsättning moduler efter namn och/eller version |
| IDebugHostTypeSignature | Representerar en typsignatur – en definition som matchar en uppsättning typer efter modul och/eller namn |
Core Host Interface: IDebugHost
IDebugHost-gränssnittet är kärngränssnittet för alla datamodellvärdar. Den definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHost, IUnknown)
{
STDMETHOD(GetHostDefinedInterface)(_COM_Outptr_ IUnknown** hostUnk) PURE;
STDMETHOD(GetCurrentContext)(_COM_Outptr_ IDebugHostContext** context) PURE;
STDMETHOD(GetDefaultMetadata)(_COM_Outptr_ IKeyStore** defaultMetadataStore) PURE;
}
Metoden GetHostDefinedInterface returnerar värdens huvudsakliga privata gränssnitt, om så finns för den angivna värden. För felsökningsverktyg för Windows är gränssnittet som returneras här en IDebugClient (cast till IUnknown).
Metoden GetCurrentContext returnerar ett gränssnitt som representerar det aktuella tillståndet för felsökarvärden. Den exakta innebörden av detta lämnas upp till värden, men den innehåller vanligtvis saker som sessionen, processen och adressutrymmet som är aktivt i användargränssnittet för felsökningsvärden. Det returnerade kontextobjektet är till stor del ogenomskinlig för anroparen, men det är ett viktigt objekt att skicka mellan anrop till felsökningsvärden. När en anropare till exempel läser minne är det viktigt att veta vilken process och adressutrymme som minnet läss från. Begreppet är inkapslat i begreppet kontextobjekt som returneras från den här metoden.
Metoden GetDefaultMetadata returnerar ett standardmetadatalager som kan användas för vissa åtgärder (t.ex. strängkonvertering) när inga explicita metadata har skickats. På så sätt kan felsökningsvärden ha viss kontroll över hur vissa data visas. Standardmetadata kan till exempel innehålla en PreferredRadix-nyckel, vilket gör att värden kan ange om ordningstal ska visas i decimal eller hexadecimalt om inget annat anges.
Observera att egenskapsvärden i standardmetadatalagret måste matchas manuellt och måste skicka det objekt som standardmetadata efterfrågas för. GetKey-metoden ska användas i stället för GetKeyValue.
statusgränssnittet: IDebugHostStatus
Med gränssnittet IDebugHostStatus kan en klient för datamodellen eller felsökningsvärden fråga om vissa aspekter av felsökningsvärdens status. Gränssnittet definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostStatus, IUnknown)
{
STDMETHOD(PollUserInterrupt)(_Out_ bool* interruptRequested) PURE;
}
Metoden PollUserInterrupt används för att fråga om användaren av felsökningsvärden har begärt ett avbrott i den aktuella åtgärden. En egenskapsåtkomst i datamodellen kan till exempel anropa godtycklig kod (t.ex. en JavaScript-metod). Koden kan ta en godtycklig tid. För att hålla felsökningsvärden responsivt bör all sådan kod som kan ta en godtycklig tid söka efter en avbrottsbegäran via att anropa den här metoden. Om värdet interruptRequested kommer tillbaka som sant bör anroparen omedelbart avbryta och returnera ett resultat av E_ABORT.
kontextgränssnittet: IDebugHostContext
Kontext är en av de viktigaste aspekterna av datamodellen och den underliggande felsökningsvärden. När du håller ett objekt är det viktigt att kunna veta var ett objekt kommer ifrån – vilken process det finns i, vilket adressutrymme det är associerat med. Om du känner till den här informationen kan du tolka saker som pekarvärden korrekt. Ett objekt av typen IDebugHostContext måste skickas till många metoder på felsökningsvärden. Det här gränssnittet kan hämtas på flera olika sätt:
- Genom att hämta den aktuella kontexten för felsökningsprogrammet: anropa metoden GetCurrentContext för IDebugHost
- Genom att hämta kontexten för ett objekt: anropa metoden GetContext i IModelObject
- Genom att hämta kontexten för en symbol: anropa metoden GetContext för IDebugHostSymbol
Dessutom finns det två värden som har särskild betydelse i kontexten för ett IDebugHostContext-gränssnitt som antingen returneras från eller skickas till en datamodell eller felsöker värdmetoden:
nullptr: en indikation på att det inte finns någon kontext. Det är helt giltigt för vissa objekt att inte ha någon kontext. Felsökningsobjektet i datamodellens rotnamnområde refererar inte till något inom en specifik process eller adressutrymme. Den har inget sammanhang.
USE_CURRENT_HOST_CONTEXT: ett sentinel-värde som anger att man ska använda den aktuella användargränssnittskontexten för felsökningsvärden. Det här värdet returneras aldrig från felsökningsvärden. Den kan dock skickas till alla felsökningsvärdmetoder som tar en indata-IDebugHostContext i stället för att uttryckligen anropa metoden GetCurrentContext för IDebugHost. Observera att det ofta är mer presterar att uttryckligen skicka USE_CURRENT_HOST_CONTEXT än att uttryckligen hämta den aktuella kontexten.
Kontexterna för en värdkontext är till stor del ogenomskinliga för anroparen. Den enda åtgärd som en anropare utanför den centrala felsökningsvärden kan göra med en värdkontext är att jämföra den med en annan värdkontext.
Gränssnittet IDebugHostContext definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostContext, IUnknown)
{
STDMETHOD(IsEqualTo)(_In_ IDebugHostContext *pContext, _Out_ bool *pIsEqual) PURE;
}
Metoden IsEqualTo jämför en värdkontext med en annan värdkontext. Om de två kontexterna är likvärdiga returneras en indikation på detta. Observera att den här jämförelsen inte är gränssnittsjämförelse. Detta jämför det underliggande ogenomskinliga innehållet i själva kontexten.
felmottagaren: IDebugHostErrorSink
IDebugHostErrorSink är ett sätt som en klient kan ta emot meddelanden om fel som inträffar under vissa åtgärder och dirigera dessa fel där det behövs. Gränssnittet definieras på följande sätt:
enum ErrorClass
{
ErrorClassWarning,
ErrorClassError
}
DECLARE_INTERFACE_(IDebugHostErrorSink, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrError, _In_ PCWSTR message) PURE;
}
Metoden ReportError är ett återanrop till felmottagaren för att meddela att ett fel har inträffat och låta mottagaren dirigera felet till det användargränssnitt eller den mekanism som är lämplig.
Värdutvärdering: IDebugHostEvaluator/IDebugHostEvaluator2
En av de viktigaste funktionerna som felsökningsvärden tillhandahåller klienter är åtkomst till dess språkbaserade uttrycksutvärdering. Gränssnitten IDebugHostEvaluator och IDebugHostEvaluator2 är ett sätt att komma åt den funktionen från felsökningsvärden.
Gränssnitten definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostEvaluator2, IDebugHostEvaluator)
{
//
// IDebugHostEvaluator:
//
STDMETHOD(EvaluateExpression)(_In_ IDebugHostContext* context, _In_ PCWSTR expression, _In_opt_ IModelObject* bindingContext, _COM_Errorptr_ IModelObject** result, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(EvaluateExtendedExpression)(_In_ IDebugHostContext* context, _In_ PCWSTR expression, _In_opt_ IModelObject* bindingContext, _COM_Errorptr_ IModelObject** result, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
//
// IDebugHostEvaluator2:
//
STDMETHOD(AssignTo)(_In_ IModelObject* assignmentReference, _In_ IModelObject* assignmentValue, _COM_Errorptr_ IModelObject** assignmentResult, _COM_Outptr_opt_result_maybenull_ IKeyStore** assignmentMetadata) PURE;
}
Med metoden EvaluateExpression kan begäranden av felsökningsvärden utvärdera ett språkuttryck (t.ex. C++) och returnera det resulterande värdet för uttrycksutvärderingen boxats som en IModelObject. Den här specifika varianten av metoden tillåter endast språkkonstruktioner. Eventuella ytterligare funktioner som presenteras i uttrycksutvärderaren för den felsökningsvärd som inte finns på språket (t.ex. LINQ-frågemetoder) inaktiveras för utvärderingen.
Metoden EvaluateExtendedExpression liknar metoden EvaluateExpression, förutom att den aktiverar ytterligare icke-språkfunktioner som en viss felsökningsvärd väljer att lägga till i sin uttrycksutvärdering. För felsökningsverktyg för Windows möjliggör detta till exempel anonyma typer, LINQ-frågor, modulkvalificerare, formatspecificerare och andra icke-C/C++-funktioner.
IDebugHostEvaluator2
Metoden AssignTo utför tilldelning enligt semantiken för det språk som debuggas.
Gränssnittet för utökningsbarhet för värd: IDebugHostExtensibility
Vissa funktioner i felsökningsvärden kan också omfattas av utökningsbarhet. Detta kan till exempel inkludera uttrycksutvärderaren. Gränssnittet IDebugHostExtensibility är det sätt på vilket dessa utökningspunkter används. Gränssnittet definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostExtensibility, IUnknown)
{
STDMETHOD(CreateFunctionAlias)(_In_ PCWSTR aliasName, _In_ IModelObject *functionObject) PURE;
STDMETHOD(DestroyFunctionAlias)(_In_ PCWSTR aliasName) PURE;
}
Metoden CreateFunctionAlias skapar ett "funktionsalias", ett "snabbalias" för en metod som implementeras i något tillägg. Innebörden av det här aliaset är värdspecifik. Den kan utöka värdens uttrycksutvärdering med funktionen eller göra något helt annat.
Metoden DestroyFunctionAlias ångrar ett tidigare anrop till metoden CreateFunctionAlias. Funktionen är inte längre tillgänglig under namnet på snabbaliaset.
åtkomst till datamodellen
Först och främst är utöknings-API:erna för datamodellen utformade för att vara neutrala för programmet (vanligtvis ett felsökningsprogram) som fungerar som värd för datamodellen. I teorin kan alla program vara värdar för datamodellen genom att tillhandahålla en uppsättning värd-API:er som exponerar typsystemet för programmets felsökningsmål och en uppsättning projekterade objekt i datamodellens namnområde om vilka mål, processer, trådar osv. finns i dessa felsökningsmål.
Även om api:erna för datamodellen – de som påbörjar IDataModel, IDebugHostoch avsökningarna av IModelObject – är utformade för att vara portabla, definierar de inte vad ett "felsökningstillägg" är. I dag måste en komponent som vill utöka felsökningsverktygen för Windows och den motor som den tillhandahåller skriva ett motortillägg för att få åtkomst till datamodellen. Motortillägget behöver bara vara ett motortillägg i så mycket som det är inläsnings- och bootstrappingmekanismen för tillägget. Därför skulle en minimal implementering ge:
- DebugExtensionInitialize: En metod som använder en skapad IDebugClient för att få åtkomst till datamodellen och konfigurerar objektmodellmanipuleringar.
- DebugExtensionUninitialize: En metod som ångrar objektmodellmanipuleringarna som utfördes i DebugExtensionInitialize.
- DebugExtensionCanUnload: En metod som returnerar om tillägget kan tas bort. Om det fortfarande finns LIVE COM-objekt i tillägget måste det indikera detta. Det här är felsökarens motsvarighet till COM:s DllCanUnloadNow. Om detta returnerar S_FALSE indikation på att det inte går att ta bort kan felsökaren fråga detta senare för att se om en avlastning är säker eller om tillägget kan initieras igen genom att anropa DebugExtensionInitialize igen. Tillägget måste vara förberett för att hantera båda sökvägarna.
- DebugExtensionUnload: En metod som utför eventuell slutlig rensning som krävs precis innan DLL-filen tas bort
Bridge-gränssnittet: IHostDataModelAccess
Som nämnts, när DebugExtensionInitialize anropas skapar den en felsökningsklient och får åtkomst till datamodellen. Sådan åtkomst tillhandahålls av ett brygggränssnitt mellan äldre IDebug*-gränssnitt för felsökningsverktyg för Windows och datamodellen. Det här brygggränssnittet är IHostDataModelAccess och definieras på följande sätt:
DECLARE_INTERFACE_(IHostDataModelAccess, IUnknown)
{
STDMETHOD(GetDataModel)(_COM_Outptr_ IDataModelManager** manager, _COM_Outptr_ IDebugHost** host) PURE;
}
Metoden GetDataModel är metoden i brygggränssnittet som ger åtkomst till båda sidor av datamodellen: Felsökningsvärden (den nedre kanten av felsökningsprogrammet) uttrycks av det returnerade IDebugHost-gränssnittet Datamodellens huvudkomponent – datamodellhanteraren uttrycks av det returnerade IDataModelManager-gränssnittet
Data Model System Interfaces för felsökning
datamodellvärdens
Datamodellen för felsökaren är utformad för att vara ett komponentiserat system som kan hanteras i en mängd olika kontexter. Normalt finns datamodellen i kontexten för ett felsökningsprogram. För att vara en värd för datamodellen måste ett antal gränssnitt implementeras för att exponera kärnaspekter av felsökningsprogrammet: dess mål, dess minnesutrymmen, dess utvärderare, dess symboliska system och typsystem osv. Dessa gränssnitt implementeras av alla program som vill vara värdar för datamodellen, men de används av både kärndatamodellen och alla tillägg som interoperates med datamodellen.
Typsystemet och symboliska gränssnitt är:
| Gränssnittsnamn | Beskrivning |
|---|---|
| IDebugHostSymbols | Kärngränssnitt som ger åtkomst till och upplösning av symboler |
| IDebugHostSymbol/IDebugHostSymbol2 | Representerar en enda symbol av något slag. Den specifika symbolen är en härledning av det här gränssnittet. |
| IDebugHostModule | Representerar en modul som läses in i en process. Det här är en slags symbol. |
| IDebugHostType/IDebugHostType2 | Representerar en in-/språktyp. |
| IDebugHostConstant | Representerar en konstant inom symbolisk information (t.ex. ett mallargument som inte är av typen i C++) |
| IDebugHostField | Representerar ett fält inom en struktur eller klass. |
| IDebugHostData | Representerar data i en modul (om detta fanns i en struktur eller klass skulle det vara ett IDebugHostField) |
| IDebugHostBaseClass | Representerar en basklass. |
| IDebugHostPublic | Representerar en symbol i tabellen publics i en PDB. Detta har inte typinformation associerad med den. Det är ett namn och en adress. |
| IDebugHostModuleSignature | Representerar en modulsignatur – en definition som matchar en uppsättning moduler efter namn och/eller version |
| IDebugHostTypeSignature | Representerar en typsignatur – en definition som matchar en uppsättning typer efter modul och/eller namn |
De andra kärngränssnitten är:
| Gränssnittsnamn | Beskrivning |
|---|---|
| IDebugHost | Kärngränssnittet till felsökningsvärden. |
| IDebugHostStatus | Ett gränssnitt som gör att en klient kan fråga efter värdens status. |
| IDebugHostContext | En abstraktion av en kontext i värden (t.ex. ett visst mål, en viss process, ett visst adressutrymme osv.) |
| IDebugHostErrorSink | Ett gränssnitt som implementeras av anropare för att ta emot fel från vissa delar av värd- och datamodellen |
| IDebugHostEvaluator/IDebugHostEvaluator2 | Felsök värdens uttrycksutvärdering. |
| IDebugHostExtensibility | Ett gränssnitt för att utöka funktionerna i värden eller delar av den (till exempel uttrycksutvärderaren). |
det huvudsakliga symboliska gränssnittet: IDebugHostSymbols
Gränssnittet IDebugHostSymbols är huvudstartpunkten för att komma åt symboler i felsökningsmålet. Det här gränssnittet kan frågas från en instans av IDebugHost och definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostSymbols, IUnknown)
{
STDMETHOD(CreateModuleSignature)(_In_z_ PCWSTR pwszModuleName, _In_opt_z_ PCWSTR pwszMinVersion, _In_opt_z_ PCWSTR pwszMaxVersion, _Out_ IDebugHostModuleSignature** ppModuleSignature) PURE;
STDMETHOD(CreateTypeSignature)(_In_z_ PCWSTR signatureSpecification, _In_opt_ IDebugHostModule* module, _Out_ IDebugHostTypeSignature** typeSignature) PURE;
STDMETHOD(CreateTypeSignatureForModuleRange)(_In_z_ PCWSTR signatureSpecification, _In_z_ PCWSTR moduleName, _In_opt_z_ PCWSTR minVersion, _In_opt_z_ PCWSTR maxVersion, _Out_ IDebugHostTypeSignature** typeSignature) PURE;
STDMETHOD(EnumerateModules)(_In_ IDebugHostContext* context, _COM_Outptr_ IDebugHostSymbolEnumerator** moduleEnum) PURE;
STDMETHOD(FindModuleByName)(_In_ IDebugHostContext* context, _In_z_ PCWSTR moduleName, _COM_Outptr_ IDebugHostModule **module) PURE;
STDMETHOD(FindModuleByLocation)(_In_ IDebugHostContext* context, _In_ Location moduleLocation, _COM_Outptr_ IDebugHostModule **module) PURE;
STDMETHOD(GetMostDerivedObject)(_In_opt_ IDebugHostContext *pContext, _In_ Location location, _In_ IDebugHostType* objectType, _Out_ Location* derivedLocation, _Out_ IDebugHostType** derivedType) PURE;
}
Metoden CreateModuleSignature skapar en signatur som kan användas för att matcha en uppsättning specifika moduler efter namn och valfritt, efter version. Det finns tre komponenter till en modulsignatur:
- Ett namn: en matchande modul måste ha ett namn som är en exakt skiftlägesokänslig matchning mot namnet i signaturen
- En lägsta version: om den anges måste en matchande modul ha en lägsta version som är minst lika hög som den här versionen. Versioner anges i formatet "A.B.C.D" där varje efterföljande del är mindre viktig än tidigare. Endast det första segmentet är obligatoriskt.
- En högsta version: om den anges måste en matchande modul ha en högsta version som inte är högre än den här versionen. Versioner anges i formatet "A.B.C.D" där varje efterföljande del är mindre viktig än tidigare. Endast det första segmentet är obligatoriskt.
Metoden CreateTypeSignature skapar en signatur som kan användas för att matcha en uppsättning betongtyper genom att innehålla modul- och typnamn. Formatet för typnamnssignatursträngen är specifikt för det språk som debuggas (och felsöka värden). För C/C++motsvarar signatursträngen en NatVis-typspecifikation. Det vill säga signatursträngen är ett typnamn där jokertecken (anges som *) tillåts för mallargument.
CreateTypeSignatureForModuleRange
Metoden CreateTypeSignatureForModuleRange skapar en signatur som kan användas för att matcha en uppsättning betongtyper efter modulsignatur och typnamn. Detta liknar metoden CreateTypeSignature, förutom att i stället för att skicka en specifik modul som matchar signaturen skickar anroparen de argument som krävs för att skapa en modulsignatur (som om modulsignaturen skapades med metoden CreateModuleSignature).
Metoden EnumerateModules skapar en uppräkning som räknar upp varje modul som är tillgänglig i en viss värdkontext. Värdkontexten kan kapsla in en processkontext eller kapsla in något som liknar Windows-kerneln.
Metoden FindModuleByName tittar igenom den angivna värdkontexten och letar upp en modul som har det angivna namnet och returnerar ett gränssnitt till den. Det är lagligt att söka efter modulen efter namn med eller utan filnamnstillägget.
Metoden FindModuleByLocation tittar igenom den angivna värdkontexten och avgör vilken modul som innehåller adressen som anges av den angivna platsen. Sedan returneras ett gränssnitt till en sådan modul.
GetMostDerivedObject använder typsystemet för felsökningsprogrammet för att fastställa körningstypen för ett objekt från dess statiska typ. Den här metoden använder endast symbolisk information och heuristik som är tillgänglig på typsystemlagret för att utföra den här analysen. Sådan information kan omfatta C++ RTTI (information om körningstidstyp) eller analys av formen på objektets virtuella funktionstabeller. Den innehåller inte sådant som det föredragna körningstypskonceptet på en IModelObject. Om analysen inte kan hitta en körningstyp eller inte kan hitta en körningstyp som skiljer sig från den statiska typ som skickas till metoden, kan indataplatsen och typen skickas ut. Metoden misslyckas inte av dessa skäl.
Gränssnittet för enskilda kärnsymboler: IDebugHostSymbol
Varje symbol som kan returneras från datamodellvärden härleds på något sätt från IDebugHostSymbol. Det här är kärngränssnittet som varje symbol implementerar oavsett typ av symbol. Beroende på typen av symbol kan en viss symbol implementera en uppsättning andra gränssnitt som returnerar attribut som är mer unika för den specifika typ av symbol som representeras av det här gränssnittet. Gränssnittet IDebugHostSymbol2/IDebugHostSymbol definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostSymbol2, IDebugHostSymbol)
{
//
// IDebugHostSymbol:
//
STDMETHOD(GetContext)(_COM_Outptr_ IDebugHostContext** context) PURE;
STDMETHOD(EnumerateChildren)(_In_ SymbolKind kind, _In_opt_z_ PCWSTR name, _Out_ IDebugHostSymbolEnumerator **ppEnum) PURE;
STDMETHOD(GetSymbolKind)(_Out_ SymbolKind *kind) PURE;
STDMETHOD(GetName)(_Out_ BSTR* symbolName) PURE;
STDMETHOD(GetType)(_Out_ IDebugHostType** type) PURE;
STDMETHOD(GetContainingModule)(_Out_ IDebugHostModule **containingModule) PURE;
STDMETHOD(CompareAgainst)(_In_ IDebugHostSymbol *pComparisonSymbol, _In_ ULONG comparisonFlags, _Out_ bool *pMatches) PURE;
//
// IDebugHostSymbol2
//
STDMETHOD(EnumerateChildrenEx)(_In_ SymbolKind kind, _In_opt_z_ PCWSTR name, _In_opt_ SymbolSearchInfo* searchInfo, _Out_ IDebugHostSymbolEnumerator **ppEnum) PURE;
}
Det är mycket viktigt att observera att det här gränssnittet representerar många typer av symboler – avgränsade med SymbolKind-uppräkningen som har värden på följande sätt:
| Enumarant | Innebörd |
|---|---|
| Symbol | Ospecificerad symboltyp |
| SymbolModule | Symbolen är en modul och kan efterfrågas för IDebugHostModule |
| Symboltyp | Symbolen är en typ och kan efterfrågas för IDebugHostType |
| SymbolFält | Symbolen är ett fält (en datamedlem i en struktur eller klass) och kan efterfrågas för IDebugHostField |
| SymbolConstant | Symbolen är ett konstant värde och kan efterfrågas för IDebugHostConstant |
| SymbolData | Symbolen är data som inte är medlem i en struktur eller klass och som kan efterfrågas för IDebugHostData |
| SymbolBaseClass | Symbolen är en basklass och kan köra frågor för IDebugHostBaseClass |
| SymbolPublic | Symbolen är en post i en moduls offentliga tabell (utan typinformation) och kan köra frågor mot IDebugHostPublic |
| SymbolFunction | Symbolen är en funktion och kan köra frågor mot IDebugHostData |
Metoden GetContext returnerar kontexten där symbolen är giltig. Även om detta representerar saker som felsökningsmål och process-/adressutrymme där symbolen finns, kanske det inte är lika specifikt som en kontext som hämtats från andra medel (t.ex. från en IModelObject).
Metoden EnumerateChildren returnerar en uppräkning som räknar upp alla underordnade till en viss symbol. För en C++-typ betraktas till exempel basklasserna, fälten, medlemsfunktionerna och liknande alla som underordnade av typsymbolen.
Modulgränssnittet: IDebugHostModule
Felsökningsprogrammets uppfattning om en modul som läses in inom ett visst adressutrymme representeras på två olika sätt i datamodellen: På typsystemnivå via gränssnittet IDebugHostModule. Här är en modul en symbol och kärnattribut för modulen är gränssnittsmetodanrop som projiceras på datamodellnivå via datamodellen Debugger.Models.Module. Det här är en utökningsbar inkapsling av typsystemet IDebugHostModule-representation av en modul.
Gränssnittet IDebugHostModule definieras på följande sätt (ignorera metoder som är generiska för IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostModule, IDebugHostSymbol)
{
//
// IDebugHostModule:
//
STDMETHOD(GetImageName)(_In_ bool allowPath, _Out_ BSTR* imageName) PURE;
STDMETHOD(GetBaseLocation)(_Out_ Location* moduleBaseLocation) PURE;
STDMETHOD(GetVersion)(_Out_opt_ ULONG64* fileVersion, _Out_opt_ ULONG64* productVersion) PURE;
STDMETHOD(FindTypeByName)(_In_z_ PCWSTR typeName, _Out_ IDebugHostType** type) PURE;
STDMETHOD(FindSymbolByRVA)(_In_ ULONG64 rva, _Out_ IDebugHostSymbol** symbol) PURE;
STDMETHOD(FindSymbolByName)(_In_z_ PCWSTR symbolName, _Out_ IDebugHostSymbol** symbol) PURE;
}
Metoden GetImageName returnerar avbildningsnamnet för modulen. Beroende på värdet för argumentet allowPath kan det returnerade avbildningsnamnet innehålla den fullständiga sökvägen till bilden.
Metoden GetBaseLocation returnerar basinläsningsadressen för modulen som en platsstruktur. Den returnerade platsstrukturen för en modul refererar vanligtvis till en virtuell adress.
Metoden GetVersion returnerar versionsinformation om modulen (förutsatt att sådan information kan läsas ut från rubrikerna). Om en viss version begärs (via en utdatapekare som inte är nullptr) och den inte kan läsas, returneras en lämplig felkod från metodanropet.
Metoden FindTypeByName hittar en typ som definierats i modulen med typnamnet och returnerar en typsymbol för den. Den här metoden kan returnera en giltig IDebugHostType som aldrig skulle returneras via explicit rekursion av underordnade i modulen. Felsökningsvärden kan tillåta skapande av derivattyper – typer som aldrig används i själva modulen men som härleds från typer som är. Om strukturen MyStruct till exempel definieras i symbolerna för modulen men typen MyStruct ** aldrig används, kan metoden FindTypeByName legitimt returnera en typsymbol för MyStruct ** trots att typnamnet aldrig uttryckligen visas i symbolerna för modulen.
Metoden FindSymbolByRVA hittar en enda matchande symbol på den angivna relativa virtuella adressen i modulen. Om det inte finns en enda symbol på den angivna RVA:n (t.ex. flera matchningar) returneras ett fel med den här metoden. Observera att den här metoden föredrar att returnera en privat symbol framför en symbol i tabellen publics.
Metoden FindSymbolByName hittar en enda global symbol för det angivna namnet i modulen. Om det inte finns en enda symbol som matchar det angivna namnet returneras ett fel med den här metoden. Observera att den här metoden föredrar att returnera en privat symbol framför en symbol i tabellen publics.
åtkomst till typsystemet: IDebugHostType2/IDebugHostType
Ett visst språk/en inbyggd typ beskrivs av gränssnitten IDebugHostType2 eller IDebugHostType. Observera att vissa av metoderna i dessa gränssnitt endast gäller för specifika typer av typer. En viss typsymbol kan referera till någon av följande typer enligt beskrivningen i TypeKind-uppräkningen:
| Typtyp | Beskrivning |
|---|---|
| TypeUDT | En användardefinierad typ (en struct, klass, union osv.). Ett modellobjekt som har en intern typ vars typ är TypeUDT har en kanonisk representation av ObjectTargetObject där typen alltid finns i motsvarande IModelObject. |
| TypePointer | En pekare. Ett modellobjekt som har en intern typ vars typ är TypePointer har en kanonisk representation av ObjectIntrinsic där pekarens värde är noll utökat till VT_UI8 och behålls som inbyggda data i den här 64-bitarsformen. En typsymbol för TypePointer har en bastyp (som returneras av metoden GetBaseType) av den typ som pekaren pekar på. |
| TypeMemberPointer | En pekare till klassmedlem. Ett modellobjekt som har en intern typ vars typ är TypeMemberPointer har en kanonisk representation som är inbyggd (värdet är detsamma som pekarvärdet). Den exakta innebörden av det här värdet är kompilator-/felsökningsvärdspecifik. |
| TypeArray | En matris. Ett modellobjekt som har en intern typ vars typ är TypeArray har en kanonisk representation av ObjectTargetObject. Basadressen för matrisen är objektets plats (hämtas via metoden GetLocation) och matristypen behålls alltid. En typsymbol för TypeArray har en bastyp (som returneras av metoden GetBaseType) av den typ som matrisen är en matris av. |
| TypeFunction | En funktion. |
| TypeTypedef | En typedef. Ett modellobjekt som har en intern typ vars typ annars skulle vara TypeTypedef har en kanonisk representation som är identisk med den kanoniska representationen av den slutliga typen som ligger bakom typedef. Detta verkar helt transparent för slutanvändaren av objektet och typinformationen såvida inte de explicita typedef-metoderna för IDebugHostType2 används för att fråga typedef-information eller om det finns en explicit datamodell registrerad mot typedef. Observera att metoden GetTypeKind aldrig returnerar TypeTypedef. Varje metod returnerar den slutliga typ som ligger till grund för typedef. Det finns typedef-specifika metoder på IDebugHostType2 som kan användas för att hämta typedef-specifik information. |
| TypeEnum | En uppräkning. Ett modellobjekt som har en intern typ vars typ är TypeEnum har en kanonisk representation av ObjectIntrinsic där värdet och typen av den inbyggda är identiska med uppräkningsvärdet. |
| TypeIntrinsic | En inbyggd (bastyp). Ett modellobjekt som har en intern typ vars typ är TypeIntrinsic har en kanonisk representation av ObjectIntrinsic. Typinformationen kan eller får inte behållas – särskilt om den underliggande typen beskrivs fullständigt av variantdatatypen (VT_*) för de inbyggda data som lagras i IModelObject |
Det övergripande gränssnittet IDebugHostType2/IDebugHostType definieras på följande sätt (exklusive IDebugHostSymbol-metoder):
DECLARE_INTERFACE_(IDebugHostType2, IDebugHostType)
{
//
// IDebugHostType:
//
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
STDMETHOD(CreatePointerTo)(_In_ PointerKind kind, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(GetArrayDimensionality)(_Out_ ULONG64* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(_In_ ULONG64 dimensions, _Out_writes_(dimensions) ArrayDimension *pDimensions) PURE;
STDMETHOD(CreateArrayOf)(_In_ ULONG64 dimensions, _In_reads_(dimensions) ArrayDimension *pDimensions, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(GetFunctionCallingConvention)(_Out_ CallingConventionKind* conventionKind) PURE;
STDMETHOD(GetFunctionReturnType)(_COM_Outptr_ IDebugHostType** returnType) PURE;
STDMETHOD(GetFunctionParameterTypeCount)(_Out_ ULONG64* count) PURE;
STDMETHOD(GetFunctionParameterTypeAt)(_In_ ULONG64 i, _Out_ IDebugHostType** parameterType) PURE;
STDMETHOD(IsGeneric)(_Out_ bool* isGeneric) PURE;
STDMETHOD(GetGenericArgumentCount)(_Out_ ULONG64* argCount) PURE;
STDMETHOD(GetGenericArgumentAt)(_In_ ULONG64 i, _Out_ IDebugHostSymbol** argument) PURE;
//
// IDebugHostType2:
//
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
STDMETHOD(GetFunctionVarArgsKind)(_Out_ VarArgsKind* varArgsKind) PURE;
}
IDebugHostType2/IDebugHostType Allmänna metoder
Följande IDebugHostType-metoder är allmänna för alla typer oavsett vilken typ som returneras från metoden GetTypeKind:
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
Metoden GetTypeKind returnerar vilken typ av typ (pekare, matris, inbyggd osv.) som symbolen refererar till.
Metoden GetSize returnerar storleken på typen (som om en hade gjort sizeof(type) i C++).
Om typen är ett derivat av en annan enskild typ (t.ex. som MyStruct * härleds från MyStruct) returnerar metoden GetBaseType bastypen för härledning. För pekare returnerar detta den typ som pekar på. För matriser returnerar detta vad matrisen är en matris med. Om typen inte är en sådan derivattyp returneras ett fel.
Metoden GetHashCode returnerar en 32-bitars hashkod för typen. Med undantag för en global matchning (t.ex. en typsignatur som motsvarar * som matchar allt om det tillåts av värden), måste alla typinstanser som kan matcha en viss typsignatur returnera samma hash-kod. Den här metoden används tillsammans med typsignaturer för att matcha typsignaturer för att skriva instanser.
IDebugHostType2/IDebugHostType Intrinsic Methods
Följande IDebugHostType-metoder är specifika för inbyggda typer (eller typer som innehåller inbyggda data, till exempel uppräkningar):
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
Metoden GetIntrinsicType returnerar information om vilken typ av inbyggd typ som är. Två värden returneras från den här metoden:
- Den inbyggda typen anger den övergripande typen (t.ex. heltal, osignerad, flyttal) men inte storleken på typen (t.ex. 8 bitar, 16 bitar, 32 bitar, 64 bitar)
- Transportörens typ anger hur den inbyggda typen packar i en VARIANT-struktur. Det här är en VT_* konstant.
Kombinationen av de två värdena ger den fullständiga uppsättningen information om det inbyggda.
IDebugHostType2/IDebugHostType Bitfield-metoder
Följande IDebugHostType-metoder är specifika för typer som lagrar data i bitfält. Information om bitfältsplacering inom en inbyggd lagras som en del av typsymbolen i datamodellen i stället för att vara ett attribut för platsen.
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
Om en viss medlem i en datastruktur är en bitfält (t.ex. ULONG MyBits:8) innehåller typinformationen för fältet information om bitfältsplaceringen. Metoden GetBitField kan användas för att hämta den informationen. Den här metoden misslyckas på alla typer som inte är en bitfält. Det här är den enda anledningen till att metoden misslyckas. Att bara anropa den här metoden och titta på lyckade/misslyckade är tillräckligt för att skilja ett bitfält från ett icke-bitfält. Om en viss typ råkar vara ett bitfält definieras fältpositionerna av den halvöppna uppsättningen (lsbOfField + lengthOfField : lsbOfField]
IDebugHostType2/IDebugHostType Pointer-relaterade metoder
Följande IDebugHostType-metoder är specifika för pekartyper. Det här är typer där GetTypeKind returnerar TypePointer eller TypeMemberPointer":
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
För typer som är pekare returnerar metoden GetPointerKind typen av pekare. Detta definieras av PointerKind-uppräkningen.
För typer som är pekare-till-medlem (vilket anges av en typtyp av TypeMemberPointer) returnerar metoden GetMemberType klassen som pekaren är pekare-till-medlem för.
IDebugHostType2/IDebugHostType Matrisrelaterade metoder
Matriser är typer där GetTypeKind returnerar TypeArray. Observera att matriser som definieras av felsökningsvärdens typsystem inte är samma som den endimensionella, nollindexbaserade, packade linjära endimensionella matriser som C använder. C-formatmatriser passar in i definitionen, men den övergripande omfattningen för en matris är bredare i IDebugHostType. En matris i felsökningsvärden kan vara flerdimensionell och varje dimension i matrisen definieras av en beskrivning som kallas en ArrayDimensionThis-beskrivning har följande fält:
| Fält | Innebörd |
|---|---|
| LowerBound | Matrisens basindex som ett signerat 64-bitarsvärde. För en C-formatmatris är detta alltid noll. Det behöver det inte vara. En enskild dimension av en matris kan anses starta vid valfritt 64-bitars index, även ett negativt. |
| Längd | Längden på matrisdimensionen som ett osignerat 64-bitarsvärde. Matrisens diktadata sträcker sig över den halvöppna uppsättningen [LowerBound, LowerBound + Length). |
| Steg | Definierar matrisdimensionens steg. För en ökning av en (från N till N + 1) i indexet för den här dimensionen anger detta hur många byte som ska flyttas framåt i minnet. För en C-formatmatris skulle det här vara storleken på varje element i matrisen. Det behöver det inte vara. Utfyllnad mellan element kan uttryckas som ett steg större än storleken på varje enskilt element. För flerdimensionella matriser anger det här värdet hur du flyttar en hel dimension framåt. Överväg en M x N-matris. Detta kan beskrivas i rad-större form som två dimensioner: |
{ [LowerBound: 0, Length: M, Stride: N \* sizeof(element)], [LowerBound: 0, Length: N, Stride: sizeof(element)]}
eller så kan det också beskrivas i kolumn-större form som två dimensioner:
{ [LowerBound: 0, Length: M, Stride: sizeof(element)], [LowerBound: 0, Length: N, Stride: M \* sizeof(element)]}
Konceptet ArrayDimension tillåter den här graden av flexibilitet.
Följande IDebugHostType-metoder är specifika för matristyper.
STDMETHOD(GetArrayDimensionality)(\_Out_ ULONG64\* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(\_In_ ULONG64 dimensions, \_Out_writes_(dimensions) ArrayDimension \*pDimensions) PURE;
Metoden GetArrayDimensionality returnerar antalet dimensioner som matrisen indexeras i. För C-formatmatriser är det värde som returneras här alltid 1.
Metoden GetArrayDimensions returnerar en uppsättning deskriptorer, en för varje dimension i matrisen enligt metoden GetArrayDimensionality. Varje beskrivning är en ArrayDimension-struktur som beskriver startindex, längd och framåtsteg för varje matrisdimension. Detta möjliggör beskrivningar av betydligt kraftfullare matriskonstruktioner än vad som tillåts i C-typsystemet.
För matriser i C-format returneras en enda matrisdimension här med värden som alltid är:
- LowerBound = 0
- Längd = ARRAYSIZE(matris)
- Stride = sizeof(elementType)
IDebugHostType2/IDebugHostType Funktionsrelaterade metoder
Typer som anger att de är funktionstyper via en typ av TypeFunction stöder följande metoder i både IDebugHostType och IDebugHostType2.
//
// IDebugHostType:
//
STDMETHOD(GetFunctionCallingConvention)(_Out_ CallingConventionKind* conventionKind) PURE;
STDMETHOD(GetFunctionReturnType)(_COM_Outptr_ IDebugHostType** returnType) PURE;
STDMETHOD(GetFunctionParameterTypeCount)(_Out_ ULONG64* count) PURE;
STDMETHOD(GetFunctionParameterTypeAt)(_In_ ULONG64 i, _Out_ IDebugHostType** parameterType) PURE;
//
// IDebugHostType2:
//
STDMETHOD(GetFunctionVarArgsKind)(_Out_ VarArgsKind* varArgsKind) PURE;
Metoden GetFunctionCallingConvention returnerar funktionens anropande konvention. Sådan returneras som medlem i uppräkningen CallingConventionKind.
Metoden GetFunctionReturnType returnerar funktionens returtyp.
Metoden GetFunctionParameterTypeCount returnerar antalet argument som funktionen tar. Observera att den C/C++-ellipsbaserade variabelargumentmarkören inte beaktas i det här antalet. Förekomsten av sådana måste identifieras via metoden GetFunctionVarArgsKind. Detta inkluderar endast argument före ellipsen.
Metoden GetFunctionParameterTypeAt returnerar typen av i-th-argumentet till funktionen.
Metoden GetFunctionVarArgsKind returnerar om en viss funktion använder en lista med variabelargument och i så fall vilken typ av variabelargument den använder. Sådan definieras av en medlem i uppräkningen VarArgsKind som definieras på följande sätt:
| Uppräkning | Innebörd |
|---|---|
| VarArgsNone | Funktionen tar inga variabelargument. |
| VarArgsCStyle | Funktionen är en varargs-funktion i C-stil (returnType(arg1, arg2, ...)). Antalet argument som rapporteras av funktionen inkluderar inte ellipsargumentet. Varje variabel argumentöverföring sker efter det antal argument som returneras av metoden GetFunctionParameterTypeCount. |
IDebugHostType2 GetFunctionVarArgsKind
Metoden GetFunctionVarArgsKind returnerar om en viss funktion använder en lista med variabelargument och i så fall vilken typ av variabelargument den använder. Sådan definieras av en medlem i uppräkningen VarArgsKind som definieras på följande sätt:
IDebugHostType2/IDebugHostType Typedef-relaterade metoder
Alla typer som är en typedef fungerar som om typen är den sista typen som ligger bakom typedef. Det innebär att metoder som GetTypeKind inte anger att typen är en typedef. På samma sätt returnerar GetBaseType inte den typ som definitionen refererar till. De anger i stället att de beter sig som om de anropades på den slutliga definitionen som ligger till grund för typedef. Som exempel:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
En IDebugHostType för "antingen PMYSTRUCT eller PTRMYSTRUCT rapporterar följande information:
- Metoden GetTypeKind returnerar TypePointer. Den slutliga underliggande typen MYSTRUCT * är verkligen en pekare.
- Metoden GetBaseType returnerar en typ för MYSTRUCT. Den underliggande typen av MYSTRUCT * är MYSTRUCT.
Den enda skillnaden här är hur typedef-specifika metoder på IDebugHostType2 beter sig. Dessa metoder är:
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
I det här exemplet:
- Metoden IsTypedef returnerar true för både PMYSTRUCT och PTRMYSTRUCT
- Metoden GetTypedefBaseType returnerar MYSTRUCT * för PMYSTRUCT och PMYSTRUCT för PTRMYSTRUCT
- Metoden GetTypedefFinalBaseType returnerar MYSTRUCT * för båda typerna
Metoden IsTypedef är den enda metoden som kan se om en typ är en typedef. Metoden GetTypeKind fungerar som om den anropades för den underliggande typen.
Metoden GetTypedefBaseType returnerar den omedelbara definitionen av typedef. I exemplen som beskrivs i dokumentationen:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
Den här metoden returnerar MYSTRUCT * för PMYSTRUCT och PMYSTRUCT för PTRMYSTRUCT.
Metoden GetTypedefFinalBaseType returnerar den slutliga typen som typedef är en definition för. Om typedef är en definition av en annan typedef fortsätter detta att följa definitionskedjan tills den når en typ som inte är en typedef och den typen returneras. I exemplen som beskrivs i dokumentationen:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
Den här metoden returnerar MYSTRUCT * när den anropas på antingen PMYSTRUCT eller PTRMYSTRUCT.
metoder för att skapa IDebugHostType2/IDebugHostType-typ
STDMETHOD(CreatePointerTo)(_In_ PointerKind kind, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(CreateArrayOf)(_In_ ULONG64 dimensions, _In_reads_(dimensions) ArrayDimension *pDimensions, _COM_Outptr_ IDebugHostType** newType) PURE;
konstanta symbolvärden: IDebugHostConstant
För platser där konstanta värden finns i symbolisk information (där ett visst värde är en symbol som kan vara ett konstant värde) uttrycker gränssnittet IDebugHostConstant begreppet en sådan konstant. Detta används vanligtvis på platser som mallargument där ett visst argument vanligtvis är en typ, men i stället kan vara ett mallargument av icke-typ (t.ex. en konstant).
Gränssnittet IDebugHostConstant definieras på följande sätt (ignorera allmänna metoder som implementeras av IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostConstant, IDebugHostSymbol)
{
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Metoden GetValue returnerar värdet för konstanten som är packad till en VARIANT. Observera att Metoden GetType på IDebugHostSymbol kan returnera en specifik typsymbol för konstanten. I sådana fall finns det ingen garanti för att förpackning av det konstanta värdet som definieras av typsymbolen är detsamma som förpackningsvärdet som returneras av metoden GetValue här.
Data Member Access: IDebugHostField
Klassen IDebugHostField representerar en symbol som är en datamedlem i en klass, struktur, union eller annan typkonstruktion. Den representerar inte kostnadsfria data (t.ex. globala data). Gränssnittet definieras på följande sätt (ignorerar metoder som är generiska för IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostField, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Metoden GetLocationKind returnerar vilken typ av plats symbolen är på enligt LocationKind-uppräkningen. En sådan uppräkning kan vara något av följande värden:
| Uppräkning | Innebörd |
|---|---|
| LocationMember | Fältet är en vanlig datamedlem i en klass, struktur, union eller annan typkonstruktion. Den har en förskjutning som är relativ till basadressen för den innehållande typkonstruktionen. Den här basadressen representeras vanligtvis av den här pekaren. Förskjutningen av fältet kan hämtas via metoden GetOffset. Metoderna GetLocation och GetValue misslyckas för ett fält som är LocationMember. |
| LocationStatic | Fältet är statiskt och har en egen adress. Metoden GetLocation returnerar den abstrakta platsen (t.ex. adress) för det statiska fältet. Metoderna GetOffset och GetValue misslyckas för ett fält som är LocationStatic. |
| LocationConstant | Fältet är en konstant och har ett värde. Metoden GetValue returnerar värdet för konstanten. Metoderna GetOffset och GetLocation misslyckas för ett fält som är LocationConstant |
| LocationNone | Fältet har ingen plats. Det kan ha optimerats av kompilatorn eller så kan det vara ett statiskt fält som deklareras men aldrig definieras. Oavsett hur ett sådant fält blev har det ingen fysisk närvaro eller något värde. Det finns bara i symbolerna. Alla anskaffningsmetoder (GetOffset, GetLocation och GetValue) misslyckas för ett fält som är LocationNone. |
För fält som har en förskjutning (t.ex. fält vars platstyp anger LocationMember) returnerar metoden GetOffset förskjutningen från basadressen för den innehållande typen (den här pekaren) till data för själva fältet. Sådana förskjutningar uttrycks alltid som osignerade 64-bitarsvärden. Om det angivna fältet inte har någon plats som är en förskjutning från basadressen för den innehållande typen misslyckas metoden GetOffset.
För fält som har en adress oavsett den specifika typinstansen (t.ex. fält vars platstyp anger LocationStatic) returnerar metoden GetLocation fältets abstrakta plats (adress). Om det angivna fältet inte har någon statisk plats misslyckas metoden GetLocation.
För fält som har ett konstant värde som definierats i den symboliska informationen (t.ex. fält vars platstyp anger LocationConstant) returnerar metoden GetValue fältets konstanta värde. Om det angivna fältet inte har ett konstant värde misslyckas metoden GetValue.
kostnadsfri dataåtkomst: IDebugHostData
Data i moduler som inte är medlem av en annan typ representeras av gränssnittet IDebugHostData. Gränssnittet definieras på följande sätt (ignorerar metoder som är generiska för IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostData, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Alla dessa metoder är semantiskt likvärdiga med deras motsvarigheter i IDebugHostField. Den enda skillnaden är att metoden GetLocationKind aldrig returnerar LocationMember för kostnadsfria data.
Metoden GetLocationKind returnerar vilken typ av plats symbolen är på enligt LocationKind-uppräkningen. Beskrivningen av den här uppräkningen finns i dokumentationen för IDebugHostField.
För data som har en adress returnerar metoden GetLocation den abstrakta platsen (adressen) för fältet. Om angivna data inte har någon statisk plats misslyckas metoden GetLocation.
För data som har ett konstant värde som definierats i den symboliska informationen (t.ex. data vars platstyp anger LocationConstant) returnerar metoden GetValue fältets konstanta värde. Om angivna data inte har ett konstant värde misslyckas metoden GetValue.
Basklasser: IDebugHostBaseClass
Arvshierarkin för en viss typ uttrycks genom underordnade av en typsymbol. Om en viss typ härleds (arvsmässigt) från en eller flera typer, kommer det att finnas en eller flera SymbolBaseClass-underordnade av typsymbolen för typen. Var och en av dessa SymbolBaseClass-symboler representerar omedelbart arv från en viss typ. Namnet på basklassen är både namnet på SymbolBaseClass-symbolen och namnet på typsymbolen för basklassen. Metoden GetType på SymbolBaseClass-symbolen kan användas för att hämta typsymbolen för själva basklassen. Den fullständiga arvshierarkin kan passeras genom att rekursivt utforska symbolbasklassens underordnade symboler. Var och en av dessa basklasssymboler uttrycks av gränssnittet IDebugHostBaseClass som definieras på följande sätt (ignorera metoder som är generiska för IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostBaseClass, IDebugHostSymbol)
{
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
}
Metoden GetOffset returnerar förskjutningen av basklassen från basadressen för den härledda klassen. En sådan förskjutning kan vara noll eller vara ett positivt osignerat 64-bitarsvärde.
offentliga symboler: IDebugHostPublic
Offentliga symboler representerar saker i den offentliga tabellen i en symbolfil. De är i själva verket exportadresser. Det finns ingen typinformation som är associerad med en offentlig symbol – endast en adress. Om inte en offentlig symbol uttryckligen begärs av anroparen föredrar felsökningsvärden att returnera privata symboler för varje förfrågan. En offentlig symbol uttrycks av IDebugHostPublic-gränssnittet som definieras på följande sätt (ignorera metoder som är generiska för IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostPublic, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
}
Alla dessa metoder är semantiskt likvärdiga med deras motsvarigheter i IDebugHostField. Den enda skillnaden är att metoden GetLocationKind aldrig returnerar LocationMember eller LocationConstant för sådana symboler.
Metoden GetLocationKind returnerar vilken typ av plats symbolen är på enligt LocationKind-uppräkningen. Beskrivningen av den här uppräkningen finns i dokumentationen för IDebugHostField.
För data som har en adress returnerar metoden GetLocation den abstrakta platsen (adressen) för fältet. Om den angivna allmänheten inte har någon statisk plats misslyckas metoden GetLocation.
-modulens signaturer och versionsmatchning: IDebugHostModuleSignature
Modulsignaturer representerar ett sätt att kontrollera om en viss modul uppfyller en uppsättning kriterier för namngivning och versionshantering. En modulsignatur skapas via metoden CreateModuleSignature på IDebugHostSymbols. Den kan matcha modulnamnet och ett valfritt intervall med versionsnummer för modulen. När en sådan signatur har skapats får klienten ett IDebugHostModuleSignature-gränssnitt som definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostModuleSignature, IUnknown)
{
STDMETHOD(IsMatch)(_In_ IDebugHostModule* pModule, _Out_ bool* isMatch) PURE;
}
Metoden IsMatch jämför en viss modul (enligt en IDebugHostModule-symbol) med en signatur och jämför modulnamnet och versionen med namnet och versionsintervallet som anges i signaturen. En indikation på om den angivna modulsymbolen matchar signaturen returneras.
typsignaturer och typmatchning: IDebugHostTypeSignature
Typsignaturer representerar ett sätt att kontrollera om en viss typinstans uppfyller en uppsättning kriterier om namnet på typen, de allmänna argumenten för typen och modulen som typen finns i. En typsignatur skapas via metoden CreateTypeSignature på IDebugHostSymbols. När en sådan signatur har skapats får klienten ett IDebugHostTypeSignature-gränssnitt som definieras på följande sätt:
DECLARE_INTERFACE_(IDebugHostTypeSignature, IUnknown)
{
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
STDMETHOD(IsMatch)(_In_ IDebugHostType* type, _Out_ bool* isMatch, _COM_Outptr_opt_ IDebugHostSymbolEnumerator** wildcardMatches) PURE;
STDMETHOD(CompareAgainst)(_In_ IDebugHostTypeSignature* typeSignature, _Out_ SignatureComparison* result) PURE;
}
Metoden GetHashCode returnerar en 32-bitars hash-kod för typsignaturen. Felsökningsvärden garanterar att det finns en synkronisering i implementeringen mellan hash-koden som returneras för typinstanser och hash-koden som returneras för typsignaturer. Med undantag för en global matchning, om en typinstans kan matcha en typsignatur, har båda samma 32-bitars hashkod. Detta möjliggör en inledande snabb jämförelse och matchning mellan en typinstans och en uppsjö av typsignaturer som registrerats med datamodellhanteraren.
Metoden IsMatch returnerar en indikation på om en viss typinstans matchar de kriterier som anges i typsignaturen. Om den gör det returneras en indikation på detta samt en uppräknare som anger alla specifika delar av typinstansen (som symboler) som matchade jokertecken i typsignaturen.
Metoden CompareAgainst jämför typsignaturen med en annan typsignatur och returnerar hur de två signaturerna jämförs. Jämförelseresultatet som returneras är medlem i SignatureComparison-uppräkningen som definieras på följande sätt:
| Uppräkning | Innebörd |
|---|---|
| Obesläktad | Det finns ingen relation mellan de två signaturer eller typer som jämförs. |
| Tvetydig | En signatur eller typ jämför tvetydigt med den andra. För två typsignaturer innebär det att det finns potentiella typinstanser som kan matcha båda signaturerna lika bra. Till exempel är de två typsignaturer som visas nedan tvetydiga. Signatur 1: std::pair<*, int> Signatur 2: std::pair<int,*> eftersom typinstansen std::pair<int, int> matchar antingen en lika bra (båda har en betong- och en jokerteckenmatchning). |
| LessSpecific | En signatur eller typ är mindre specifik än den andra. Ofta innebär detta att den mindre specifika signaturen har ett jokertecken där den mer specifika har en konkret typ. Till exempel är den första signaturen nedan mindre specifik än den andra. Signatur 1: std::pair<*, int> Signatur 2: std::pair<int, int> eftersom den har ett jokertecken (*) där den andra har en betongtyp (int). |
| MoreSpecific | En signatur eller typ är mer specifik än den andra. Ofta innebär detta att den mer specifika signaturen har en konkret typ där den mindre specifika har ett jokertecken. Till exempel är den första signaturen nedan mer specifik än den andra. Signatur 1: std::pair<int, int> Signatur 2: std::pair<*, int> eftersom den har en betongtyp (int) där den andra har ett jokertecken (*). |
| Identisk | De två signaturerna eller typerna är identiska. |
Se även
Det här avsnittet är en del av en serie som beskriver de gränssnitt som är tillgängliga från C++, hur du använder dem för att skapa ett C++-baserat felsökningstillägg och hur du använder andra datamodellkonstruktioner (t.ex. JavaScript eller NatVis) från ett C++-datamodelltillägg.
Felsökningsdatamodell C++ Översikt
Felsökningsdatamodell C++ Ytterligare gränssnitt