Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Toto téma obsahuje a přehled o tom, jak pomocí rozhraní datového modelu Ladicího programu C++ rozšířit a přizpůsobit možnosti ladicího programu.
rozhraní hostitele c++ datového modelu ladicího programu
hostitele datového modelu ladicího programu
Datový model ladicího programu je navržený tak, aby byl součástí systému, který lze hostovat v různých kontextech. Datový model je obvykle hostovaný v kontextu aplikace ladicího programu. Aby bylo možné být hostitelem datového modelu, musí být implementováno několik rozhraní pro zveřejnění základních aspektů ladicího programu: jeho cílení, paměťových prostorů, vyhodnocovače, symbolického systému a systému typů atd. I když jsou tato rozhraní implementována jakoukoli aplikací, která si přeje hostovat datový model, využívají je základní datový model i jakékoli rozšíření, které spolupracuje s datovým modelem.
Sada základních rozhraní:
| Název rozhraní | Popis |
|---|---|
| IDebugHost | Základní rozhraní pro hostitele ladění. |
| IDebugHostStatus | Rozhraní, které klientovi umožňuje dotazovat se na stav hostitele. |
| IDebugHostContext | Abstrakce kontextu v rámci hostitele (např. konkrétní cíl, konkrétní proces, konkrétní adresní prostor atd.) |
| IDebugHostErrorSink | Rozhraní implementované volajícími za účelem příjmu chyb z určitých částí hostitele a datového modelu |
| IDebugHostEvaluator / IDebugHostEvaluator2 | Vyhodnocovače výrazů hostitele ladění. |
| IDebugHostExtensibility | Rozhraní pro rozšíření možností hostitele nebo jeho částí (například vyhodnocovače výrazů). |
Systém typů a symbolické rozhraní jsou:
| InterfaceName | Popis |
|---|---|
| IDebugHostSymbols | Základní rozhraní, které poskytuje přístup k symbolům a jejich rozlišení |
| IDebugHostSymbol / IDebugHostSymbol2 | Představuje jeden symbol jakéhokoli druhu. Konkrétní symbol je odvozením tohoto rozhraní. |
| IDebugHostModule | Představuje modul načtený v rámci procesu. Toto je druh symbolu. |
| IDebugHostType / IDebugHostType2 | Představuje nativní typ nebo typ jazyka. |
| IDebugHostConstant | Představuje konstantu v symbolických informacích (např. argument šablony bez typu v jazyce C++). |
| IDebugHostField | Představuje pole v rámci struktury nebo třídy. |
| IDebugHostData | Představuje data v rámci modulu (byly by to v rámci struktury nebo třídy by se jednalo o IDebugHostField). |
| IDebugHostBaseClass | Představuje základní třídu. |
| IDebugHostPublic | Představuje symbol v tabulce veřejných souborů PDB. K tomu nejsou přidružené informace o typu. Je to jméno a adresa. |
| IDebugHostModuleSignature | Představuje podpis modulu – definice, která bude odpovídat sadě modulů podle názvu a/nebo verze. |
| IDebugHostTypeSignature | Představuje podpis typu – definice, která bude odpovídat sadě typů podle modulu nebo názvu. |
rozhraní základního hostitele: IDebugHost
Rozhraní IDebugHost je základním rozhraním libovolného hostitele datového modelu. Definuje se takto:
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;
}
Metoda GetHostDefinedInterface vrátí hlavní privátní rozhraní hostitele, pokud takový existuje pro daného hostitele. Pro nástroje ladění pro Windows, rozhraní vrácené zde je IDebugClient (přetypování na IUnknown).
GetCurrentContext metoda vrátí rozhraní, které představuje aktuální stav hostitele ladicího programu. Přesný význam je ponechán na hostiteli, ale obvykle zahrnuje například relaci, proces a adresní prostor, který je aktivní v uživatelském rozhraní hostitele ladění. Vrácený kontextový objekt je do značné míry neprůzný volajícímu, ale je to důležitý objekt pro předávání mezi voláními hostitele ladění. Pokud je volající například čtení paměti, je důležité vědět, ze kterého procesu a adresního prostoru se paměť čte. Tento pojem je zapouzdřen v pojem kontextového objektu, který je vrácen z této metody.
Metoda GetDefaultMetadata vrátí výchozí úložiště metadat, které lze použít pro určité operace (např. převod řetězce), pokud nebyla předána žádná explicitní metadata. Díky tomu může hostitel ladění mít určitou kontrolu nad tím, jak se některá data zobrazují. Výchozí metadata mohou například obsahovat klíč PreferredRadix, který hostiteli umožňuje určit, zda mají být ordinaly zobrazeny v desítkové nebo šestnáctkové, pokud není jinak zadáno.
Všimněte si, že hodnoty vlastností ve výchozím úložišti metadat musí být ručně vyřešeny a musí předat objekt, pro který se dotazují výchozí metadata. Metoda GetKey by měla být použita místo GetKeyValue.
rozhraní stavu: IDebugHostStatus
Rozhraní IDebugHostStatus umožňuje klientovi datového modelu nebo hostiteli ladění inquire o určitých aspektech stavu hostitele ladění. Rozhraní je definováno takto:
DECLARE_INTERFACE_(IDebugHostStatus, IUnknown)
{
STDMETHOD(PollUserInterrupt)(_Out_ bool* interruptRequested) PURE;
}
Metoda PollUserInterrupt slouží k inquire, zda uživatel hostitele ladění požádal o přerušení aktuální operace. Přístup k vlastnosti v datovém modelu může například volat libovolný kód (např. javascriptová metoda). Tento kód může trvat libovolnou dobu. Aby byl hostitel ladění responzivní, měl by jakýkoli takový kód, který může trvat libovolnou dobu, kontrolovat požadavek přerušení voláním této metody. Pokud se hodnota interruptRequested vrátí jako true, volající by měl okamžitě přerušit a vrátit výsledek E_ABORT.
kontextové rozhraní: IDebugHostContext
Kontext je jedním z nejdůležitějších aspektů datového modelu a základního hostitele ladění. Když držíte objekt, je důležité vědět, odkud objekt pochází – jaký je jeho proces, k jakému adresní prostoru je přidružený. Znalost těchto informací umožňuje správnou interpretaci věcí, jako jsou hodnoty ukazatele. Objekt typu IDebugHostContext musí být předán mnoha metodám v hostiteli ladění. Toto rozhraní lze získat mnoha způsoby:
- Získáním aktuálního kontextu ladicího programu: volání metody GetCurrentContext IDebugHost
- Získáním kontextu objektu: volání GetContext metody IModelObject
- Získáním kontextu symbolu: volání metody GetContext IDebugHostSymbol
Kromě toho existují dvě hodnoty, které mají zvláštní význam v kontextu IDebugHostContext rozhraní, které je vráceno z datového modelu nebo ladění hostitelské metody:
nullptr : indikuje, že neexistuje žádný kontext. Pro některé objekty je naprosto platné, aby neměly žádný kontext. Objekt Debugger v kořenovém oboru názvů datového modelu neodkazuje na nic v rámci konkrétního procesu nebo adresního prostoru. Nemá žádný kontext.
USE_CURRENT_HOST_CONTEXT: hodnota sentinelu označující, že by měl používat aktuální kontext uživatelského rozhraní hostitele ladění. Tato hodnota se nikdy nevrátí z hostitele ladění. Může však být předán do jakékoli ladicí hostitelské metody, která přebírá vstupní IDebugHostContext místo explicitní volání GetCurrentContext metoda IDebugHost. Mějte na paměti, že explicitní předávání USE_CURRENT_HOST_CONTEXT je často výkonnější než explicitní získání aktuálního kontextu.
Kontexty kontextu hostitele jsou z velké části neprůzné volajícímu. Jedinou operací, kterou volající mimo hlavního hostitele ladění může provádět s kontextem hostitele, je porovnat ho s jiným kontextem hostitele.
Rozhraní IDebugHostContext je definováno takto:
DECLARE_INTERFACE_(IDebugHostContext, IUnknown)
{
STDMETHOD(IsEqualTo)(_In_ IDebugHostContext *pContext, _Out_ bool *pIsEqual) PURE;
}
Metoda IsEqualTo porovnává kontext hostitele s jiným kontextem hostitele. Pokud jsou tyto dva kontexty ekvivalentní, je vrácena indikace. Všimněte si, že toto porovnání není ekvivalence rozhraní. Tím se porovná podkladový neprůhlený obsah samotného kontextu.
jímky chyb: IDebugHostErrorSink
IDebugHostErrorSink je prostředek, pomocí kterého může klient dostávat oznámení o chybách, ke kterým dochází během určitých operací, a v případě potřeby tyto chyby směrovat. Rozhraní je definováno takto:
enum ErrorClass
{
ErrorClassWarning,
ErrorClassError
}
DECLARE_INTERFACE_(IDebugHostErrorSink, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrError, _In_ PCWSTR message) PURE;
}
Metoda ReportError je zpětné volání v jímce chyby, která informuje, že došlo k chybě a umožní jímce směrovat chybu do libovolného uživatelského rozhraní nebo mechanismu.
vyhodnocovač hostitelů: IDebugHostEvaluator / IDebugHostEvaluator2
Jedním z nejdůležitějších funkcí, které hostitel ladění poskytuje klientům, je přístup ke svému vyhodnocovače výrazů na základě jazyka. Rozhraní IDebugHostEvaluator a IDebugHostEvaluator2 jsou prostředky pro přístup k této funkci z hostitele ladění.
Rozhraní jsou definována takto:
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;
}
Metoda EvaluateExpression umožňuje požadavkům hostitele ladění vyhodnotit jazyk (např. C++) výraz a vrátit výslednou hodnotu tohoto výrazu vyhodnocení box jako IModelObject. Tato konkrétní varianta metody umožňuje pouze jazykové konstrukce. Všechny další funkce, které se zobrazí v rámci vyhodnocovače výrazů hostitele ladění, který není k dispozici v jazyce (např. metody dotazu LINQ), jsou pro vyhodnocení vypnuté.
EvaluateExtendedExpression metoda je podobná EvaluateExpression metoda s tím rozdílem, že se vrátí na další nejazyčné funkce, které se konkrétní ladicí hostitel rozhodne přidat do vyhodnocovače výrazů. Nástroje pro ladění pro Windows například umožňují anonymní typy, dotazy LINQ, kvalifikátory modulů, specifikátory formátu a další funkce, které nejsou C/C++.
IDebugHostEvaluator2
Metoda AssignTo provádí přiřazení podle sémantiky jazyka, který je laděn.
rozhraní rozšiřitelnosti hostitele: IDebugHostExtensibility
Některé funkce hostitele ladění mohou být volitelně předmětem rozšiřitelnosti. To může například zahrnovat vyhodnocovače výrazů. Rozhraní IDebugHostExtensibility je způsob, jakým jsou tyto body rozšiřitelnosti přístupné. Rozhraní je definováno takto:
DECLARE_INTERFACE_(IDebugHostExtensibility, IUnknown)
{
STDMETHOD(CreateFunctionAlias)(_In_ PCWSTR aliasName, _In_ IModelObject *functionObject) PURE;
STDMETHOD(DestroyFunctionAlias)(_In_ PCWSTR aliasName) PURE;
}
Metoda CreateFunctionAlias vytvoří "alias funkce", "rychlý alias" pro metodu implementovanou v některém rozšíření. Význam tohoto aliasu je specifický pro hostitele. Může rozšířit vyhodnocovače výrazů hostitele s funkcí nebo může udělat něco úplně jiného.
DestroyFunctionAlias metoda vrátí zpět předchozí volání CreateFunctionAlias metoda. Funkce už nebude dostupná pod názvem rychlého aliasu.
přístup k datovému modelu
Rozhraní API rozšiřitelnosti datového modelu jsou především navržená tak, aby byla neutrální pro aplikaci (obvykle ladicí program), která funguje jako hostitel datového modelu. Teoreticky může libovolná aplikace hostovat datový model tím, že poskytuje sadu rozhraní API hostitele, která zpřístupňují typový systém cílů ladění aplikace a sadu projektovaných objektů do oboru názvů datového modelu o cílech, procesech, vláknech atd. jsou v těchto cílech ladění.
Zatímco rozhraní API datového modelu – ty, které začínají IDataModel, IDebugHosta offshoots IModelObject – jsou navrženy tak, aby byly přenosné, nedefinují, co je "rozšíření ladicího programu". Dnes musí komponenta, která chce rozšířit nástroje ladění pro Windows a modul, který poskytuje, zapsat rozšíření modulu, aby bylo možné získat přístup k datovému modelu. Toto rozšíření motoru musí být jen rozšířením motoru, protože se jedná o mechanismus načítání a spouštění pro rozšíření. Minimální implementace by proto poskytovala:
- DebugExtensionInitialize: Metoda, která využívá vytvořený IDebugClient k získání přístupu k datovému modelu a nastavení manipulace s objektovým modelem.
- DebugExtensionUninitialize: Metoda, která vrátí zpět manipulace s objektovým modelem, které byly provedeny v DebugExtensionInitialize.
- DebugExtensionCanUnload: Metoda, která vrátí, zda rozšíření může uvolnit. Pokud v rozšíření stále existují živé objekty COM, musí to znamenat. Toto je ekvivalent ladicího programu DllCanUnloadNow modelu COM. Pokud vrátí S_FALSE indikaci nemožnosti uvolnění, ladicí program se na tento dotaz může později dotazovat, aby zjistil, jestli je uvolnění bezpečné, nebo může znovu inicializovat rozšíření voláním DebugExtensionInitialize znovu. Rozšíření musí být připravené pro zpracování obou cest.
- DebugExtensionUnload: Metoda, která provede konečné vyčištění požadované přímo před uvolněním knihovny DLL.
rozhraní mostu: IHostDataModelAccess
Jak už bylo zmíněno, při volání DebugExtensionInitialize vytvoří ladicí klienta a získá přístup k datovému modelu. Takový přístup poskytuje rozhraní mostu mezi staršími rozhraními IDebug* nástrojů pro ladění pro Windows a datovým modelem. Toto rozhraní mostu je IHostDataModelAccess a je definováno takto:
DECLARE_INTERFACE_(IHostDataModelAccess, IUnknown)
{
STDMETHOD(GetDataModel)(_COM_Outptr_ IDataModelManager** manager, _COM_Outptr_ IDebugHost** host) PURE;
}
Metoda GetDataModel je metoda na rozhraní mostu, která poskytuje přístup k oběma stranám datového modelu: Ladicí hostitel (dolní okraj ladicího programu) je vyjádřen vráceným rozhraním IDebugHost hlavní komponentou datového modelu – správce datového modelu je vyjádřen vráceným rozhraním IDataModelManager.
rozhraní systému datových modelů ladicího programu
hostitele datového modelu
Datový model ladicího programu je navržený tak, aby byl součástí systému, který lze hostovat v různých kontextech. Datový model je obvykle hostovaný v kontextu aplikace ladicího programu. Aby bylo možné být hostitelem datového modelu, musí být implementováno několik rozhraní pro zveřejnění základních aspektů ladicího programu: jeho cílení, paměťových prostorů, vyhodnocovače, symbolického systému a systému typů atd. I když jsou tato rozhraní implementována jakoukoli aplikací, která si přeje hostovat datový model, využívají je základní datový model i jakékoli rozšíření, které spolupracuje s datovým modelem.
Systém typů a symbolické rozhraní jsou:
| Název rozhraní | Popis |
|---|---|
| IDebugHostSymbols | Základní rozhraní, které poskytuje přístup k symbolům a jejich rozlišení |
| IDebugHostSymbol / IDebugHostSymbol2 | Představuje jeden symbol jakéhokoli druhu. Konkrétní symbol je odvozením tohoto rozhraní. |
| IDebugHostModule | Představuje modul načtený v rámci procesu. Toto je druh symbolu. |
| IDebugHostType / IDebugHostType2 | Představuje nativní typ nebo typ jazyka. |
| IDebugHostConstant | Představuje konstantu v symbolických informacích (např. argument šablony bez typu v jazyce C++). |
| IDebugHostField | Představuje pole v rámci struktury nebo třídy. |
| IDebugHostData | Představuje data v rámci modulu (byly by to v rámci struktury nebo třídy by se jednalo o IDebugHostField). |
| IDebugHostBaseClass | Představuje základní třídu. |
| IDebugHostPublic | Představuje symbol v tabulce veřejných souborů PDB. K tomu nejsou přidružené informace o typu. Je to jméno a adresa. |
| IDebugHostModuleSignature | Představuje podpis modulu – definice, která bude odpovídat sadě modulů podle názvu a/nebo verze. |
| IDebugHostTypeSignature | Představuje podpis typu – definice, která bude odpovídat sadě typů podle modulu nebo názvu. |
Další základní rozhraní jsou:
| Název rozhraní | Popis |
|---|---|
| IDebugHost | Základní rozhraní pro hostitele ladění. |
| IDebugHostStatus | Rozhraní, které klientovi umožňuje dotazovat se na stav hostitele. |
| IDebugHostContext | Abstrakce kontextu v rámci hostitele (např. konkrétní cíl, konkrétní proces, konkrétní adresní prostor atd.) |
| IDebugHostErrorSink | Rozhraní implementované volajícími za účelem příjmu chyb z určitých částí hostitele a datového modelu |
| IDebugHostEvaluator / IDebugHostEvaluator2 | Vyhodnocovače výrazů hostitele ladění. |
| IDebugHostExtensibility | Rozhraní pro rozšíření možností hostitele nebo jeho částí (například vyhodnocovače výrazů). |
hlavní symbolické rozhraní: IDebugHostSymbols
IDebugHostSymbols rozhraní je hlavním výchozím bodem pro přístup k symbolům v cíli ladění. Toto rozhraní lze dotazovat z instance IDebugHost a je definováno takto:
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;
}
CreateModuleSignature metoda vytvoří podpis, který lze použít ke shodě sady konkrétních modulů podle názvu a volitelně podle verze. Podpis modulu má tři komponenty:
- Název: Odpovídající modul musí mít název, což je přesná shoda nerozlišující velká a malá písmena s názvem v podpisu.
- Minimální verze: Pokud je zadaná, musí mít odpovídající modul minimální verzi, která je alespoň tak vysoká jako tato verze. Verze jsou zadány ve formátu A.B.C.D, přičemž každá další část je méně důležitá než předchozí. Povinný je pouze první segment.
- Maximální verze: Pokud je zadána, musí mít odpovídající modul maximální verzi, která není vyšší než tato verze. Verze jsou zadány ve formátu A.B.C.D, přičemž každá další část je méně důležitá než předchozí. Povinný je pouze první segment.
CreateTypeSignature metoda vytvoří podpis, který lze použít k porovnání sady konkrétních typů obsahující modul a název typu. Formát řetězce podpisu názvu typu je specifický pro laděný jazyk (a hostitele ladění). Pro C/C++ je řetězec podpisu ekvivalentní specifikaci typu NatVis. To znamená, že řetězec podpisu je název typu, kde jsou pro argumenty šablony povoleny zástupné znaky (zadané jako *).
CreateTypeSignatureForModuleRange
CreateTypeSignatureForModuleRange metoda vytvoří podpis, který lze použít ke spárování sady konkrétních typů pomocí podpisu modulu a názvu typu. Podobá se metodě CreateTypeSignature s tím rozdílem, že místo předání konkrétního modulu, který se má shodovat s podpisem podpisu, volající předá argumenty potřebné k vytvoření podpisu modulu (jako kdyby byl podpis modulu vytvořen metodou CreateModuleSignature).
EnumerateModules metoda vytvoří enumerátor, který vytvoří výčet všech modulů dostupných v konkrétním kontextu hostitele. Tento kontext hostitele může zapouzdřovat kontext procesu nebo může zapouzdřovat něco jako jádro Windows.
Metoda FindModuleByName vyhledá daný kontext hostitele a vyhledá modul se zadaným názvem a vrátí do něj rozhraní. Modul je možné vyhledat podle názvu nebo bez přípony souboru.
Metoda FindModuleByLocation zkontroluje daný kontext hostitele a určí, jaký modul obsahuje adresu zadanou lokalitou. Pak vrátí rozhraní do tohoto modulu.
GetMostDerivedObject použije systém typů ladicího programu k určení typu modulu runtime objektu z jeho statického typu. Tato metoda bude k provedení této analýzy používat pouze symbolické informace a heuristiky dostupné ve vrstvě systému typů. Tyto informace mohou zahrnovat C++ RTTI (informace o typu běhu) nebo analýzu tvaru virtuálních tabulek funkcí objektu. Nezahrnuje například koncept upřednostňovaného typu modulu runtime v objektu IModelObject. Pokud analýza nemůže najít typ modulu runtime nebo nemůže najít jiný typ modulu runtime než statický typ předaný do metody, může být vstupní umístění a typ předány. Metoda se z těchto důvodů nezdaří.
rozhraní základního individuálního symbolu: IDebugHostSymbol
Každý symbol, který lze vrátit z hostitele datového modelu, bude odvozen nějakým způsobem z IDebugHostSymbol. Toto je základní rozhraní, které každý symbol implementuje bez ohledu na druh symbolu. V závislosti na druhu symbolu může daný symbol implementovat sadu dalších rozhraní, která vracejí atributy jedinečnější pro konkrétní druh symbolu reprezentovaný tímto rozhraním. IDebugHostSymbol2 / IDebugHostSymbol rozhraní je definováno takto:
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;
}
Je velmi důležité si uvědomit, že toto rozhraní představuje mnoho druhů symbolů – vymezený výčtem SymbolKind, který má hodnoty takto:
| Enumarant | Význam |
|---|---|
| Symbol | Typ nezadaného symbolu |
| SymbolModule | Symbol je modul a dá se dotazovat na IDebugHostModule. |
| SymbolType | Symbol je typ a dá se dotazovat na IDebugHostType. |
| SymbolField | Symbol je pole (datový člen ve struktuře nebo třídě) a lze ho dotazovat na IDebugHostField. |
| SymbolConstant | Symbol je konstantní hodnota a dá se dotazovat na IDebugHostConstant. |
| SymbolData | Symbol je data, která nejsou členem struktury nebo třídy a je dotazovatelná pro IDebugHostData. |
| SymbolBaseClass | Symbol je základní třída a je dotazovatelný pro IDebugHostBaseClass. |
| SymbolPublic | Symbol je položka v tabulce veřejných položek modulu (bez informací o typu) a je dotazovatelná pro IDebugHostPublic. |
| SymbolFunction | Symbol je funkce a je dotazovatelný pro IDebugHostData. |
Metoda GetContext vrátí kontext, kde je symbol platný. I když to bude představovat například cíl ladění a proces nebo adresní prostor, ve kterém symbol existuje, nemusí být tak specifický jako kontext načtený z jiných prostředků (např. z objektu IModelObject).
EnumerateChildren metoda vrátí enumerátor, který vytvoří výčet všech podřízených položek daného symbolu. Pro typ C++, například základní třídy, pole, členské funkce a podobné, jsou všechny považovány za podřízené položky symbolu typu.
rozhraní modulu: IDebugHostModule
Pojem ladicího programu modulu, který je načten v určitém adresní prostoru, je v datovém modelu reprezentován dvěma různými způsoby: Na úrovni systému typů prostřednictvím rozhraní IDebugHostModule. V této části je modul symbolem a základními atributy modulu jsou metody rozhraní volání Projected na úrovni datového modelu prostřednictvím datového modelu Debugger.Models.Module datového modelu. Jedná se o rozšiřitelný zapouzdření typového systému IDebugHostModule reprezentace modulu.
Rozhraní IDebugHostModule je definováno následujícím způsobem (ignorování metod, které jsou obecné pro 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;
}
Metoda GetImageName vrátí název image modulu. V závislosti na hodnotě argumentu allowPath může vrácený název image nebo nemusí obsahovat úplnou cestu k obrázku.
Metoda GetBaseLocation vrátí základní load adresu modulu jako strukturu umístění. Vrácená struktura umístění modulu obvykle odkazuje na virtuální adresu.
Metoda GetVersion vrátí informace o verzi modulu (za předpokladu, že tyto informace lze úspěšně přečíst z hlaviček). Pokud je požadovaná verze (prostřednictvím výstupního ukazatele jiného typu než nullptr) a nelze ji přečíst, vrátí se z volání metody odpovídající kód chyby.
FindTypeByName metoda najde typ definovaný v modulu podle názvu typu a vrátí pro něj symbol typu. Tato metoda může vrátit platnou IDebugHostType, která by se nikdy nevracela prostřednictvím explicitní rekurze podřízených položek modulu. Hostitel ladění může povolit vytváření odvozených typů – typy, které se nikdy nepoužívaly v rámci samotného modulu, ale odvozené od typů, které jsou. Pokud je například struktura MyStruct definována v symbolech modulu, ale typ MyStruct ** se nikdy nepoužívá, metoda FindTypeByName může legitimní vrácení symbolu typu pro MyStruct ** bez ohledu na tento název typu nikdy explicitně nezobrazuje v symbolech modulu.
Metoda FindSymbolByRVA najde jeden odpovídající symbol na dané relativní virtuální adrese v modulu. Pokud v zadaném protokolu RVA není jeden symbol (např. existuje více shod), vrátí se touto metodou chyba. Všimněte si, že tato metoda bude preferovat vrácení privátního symbolu nad symbolem v tabulce publics.
Metoda FindSymbolByName najde v modulu jeden globální symbol daného názvu. Pokud neexistuje jediný symbol odpovídající danému názvu, tato metoda vrátí chybu. Všimněte si, že tato metoda bude preferovat vrácení privátního symbolu nad symbolem v tabulce publics.
Přístup k systému typů: IDebugHostType2 / IDebugHostType
Daný jazyk/nativní typ je popsán rozhraními IDebugHostType2 nebo IDebugHostType. Všimněte si, že některé metody na těchto rozhraních platí pouze pro konkrétní typy typů. Daný symbol typu může odkazovat na jeden z následujících typů, jak popisuje výčet TypeKind:
| Druh typu | Popis |
|---|---|
| TypeUDT | Uživatelem definovaný typ (struktura, třída, sjednocení atd.). Objekt modelu, který má nativní typ, jehož druh je TypeUDT má kanonickou reprezentaci ObjectTargetObject, kde typ je vždy uložen uvnitř odpovídající objekt IModelObject. |
| TypePointer | Ukazatel. Objekt modelu s nativním typem, jehož druh je TypePointer, má kanonickou reprezentaci ObjectIntrinsic, kde hodnota ukazatele je nula rozšířena na VT_UI8 a uložena jako vnitřní data v tomto 64bitovém formuláři. Libovolný symbol typu TypePointer má základní typ (vrácený metodou GetBaseType) typu, na který ukazatel odkazuje. |
| TypeMemberPointer | Ukazatel na člen třídy. Objekt modelu, který má nativní typ, jehož druh je TypeMemberPointer, má kanonické vyjádření, které je vnitřní (hodnota je stejná jako hodnota ukazatele). Přesný význam této hodnoty je specifický pro kompilátor nebo ladění hostitele. |
| TypeArray | Pole. Objekt modelu, který má nativní typ, jehož druh je TypeArray má kanonickou reprezentaci ObjectTargetObject. Základní adresa pole je umístění objektu (načteno metodou GetLocation) a typ pole je vždy zachován. Libovolný symbol typu TypeArray má základní typ (vrácený Metodou GetBaseType) typu, který pole je pole pole. |
| TypeFunction | Funkce. |
| TypeTypedef | Definice typu. Objekt modelu, který má nativní typ, jehož druh by jinak typeTypedef má kanonické vyjádření identické s kanonickou reprezentací konečného typu podkladového type typedef. Toto zobrazení je pro koncového uživatele objektu a informace o typu zcela transparentní, pokud explicitní metody typedef IDebugHostType2 nejsou použity k dotazování na informace typedef nebo je explicitní datový model registrován proti typedef. Všimněte si, že GetTypeKind metoda nikdy nevrátí TypeTypedef. Každá metoda vrátí, jaký konečný typ podkladového typedef by vrátil. Existují metody specifické pro typedef pro IDebugHostType2, které lze použít k získání konkrétních informací typedef. |
| TypeEnum | Výčt. Objekt modelu, který má nativní typ, jehož druh je TypeEnum má kanonickou reprezentaci ObjectIntrinsic, kde hodnota a typ vnitřní je identický s hodnotou výčtu. |
| TypeIntrinsic | Vnitřní (základní typ). Objekt modelu, který má nativní typ, jehož druh je TypeIntrinsic má kanonickou reprezentaci ObjectIntrinsic. Informace o typu mohou nebo nemusí být zachovány – zejména pokud je podkladový typ plně popsán datovým typem varianty (VT_*) vnitřních dat uložených v objektu IModelObject. |
Celkové IDebugHostType2 / IDebugHostType rozhraní je definováno následujícím způsobem (s výjimkou IDebugHostSymbol metody):
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 – obecné metody
Následující IDebugHostType metody jsou obecné pro jakýkoli typ bez ohledu na to, jaký druh je vrácen z GetTypeKind metoda:
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
Metoda GetTypeKind vrátí typ (ukazatel, pole, vnitřní atd.) symbol odkazuje.
Metoda GetSize vrátí velikost typu (jako kdyby se v jazyce C++provedl typ sizeof(type).
Pokud je typ derivát jiného jednoho typu (např. jako MyStruct * je odvozen z MyStruct'), Metoda GetBaseType vrátí základní typ odvození. U ukazatelů se vrátí typ, na který odkazuje. U polí vrátí pole pole. Pokud typ není takový odvozený typ, vrátí se chyba.
Metoda GetHashCode vrátí 32bitový kód hash pro typ. S výjimkou globální shody (např. podpis typu ekvivalentní * , který odpovídá všemu, co je povoleno hostitelem), musí každá instance typu, která může odpovídat určitému podpisu typu, vrátit stejný hashovací kód. Tato metoda se používá ve spojení s podpisy typu, aby odpovídaly podpisům typu k typům instancí.
vnitřní metody IDebugHostType2/IDebugHostType
Následující metody IDebugHostType jsou specifické pro vnitřní typy (nebo typy, které obsahují vnitřní data, jako jsou výčty):
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
GetIntrinsicType metoda vrátí informace o tom, jaký druh vnitřní typ je. Z této metody se vrátí dvě hodnoty:
- Vnitřní typ označuje celkový typ (např. celé číslo, bez znaménka, plovoucí desetinabídka), ale ne velikost typu (např. 8 bitů, 16 bitů, 32 bitů, 64 bitů)
- Typ operátoru označuje, jak se vnitřní druh zabalí do struktury VARIANT. Toto je konstanta VT_*.
Kombinace těchto dvou hodnot poskytuje úplnou sadu informací o vnitřních objektech.
metody Bitfield IDebugHostType2/IDebugHostType
Následující metody IDebugHostType jsou specifické pro typy, které ukládají data v bitfields. Informace o umísťování bitových polí uvnitř vnitřní části jsou uloženy jako součást symbolu typu v datovém modelu, nikoli jako atribut umístění.
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
Pokud je daný člen datové struktury bitové pole (např. ULONG MyBits:8), informace o typu pole s sebou nese informace o umístění bitového pole. Metodu GetBitField lze použít k načtení informací. Tato metoda selže u jakéhokoli typu, který není bitové pole. To je jediný důvod, proč metoda selže. Stačí jednoduše zavolat tuto metodu a podívat se na úspěch/selhání, aby bylo možné rozlišovat bitové pole od nebitového pole. Pokud se daný typ stane bitovým polem, pozice polí jsou definovány poloviční otevřenou množinou (lsbOfField + lengthOfField : lsbOfField]
IDebugHostType2/IDebugHostType – metody související s ukazateli
Následující metody IDebugHostType jsou specifické pro typy ukazatelů. Jedná se o typy, ve kterých GetTypeKind vrací TypePointer nebo TypeMemberPointer:
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
Pro typy, které jsou ukazatele, GetPointerKind metoda vrátí druh ukazatele. To je definováno pomocí pointerKind výčtu.
Pro typy, které jsou ukazatel-na-člen (jak je uvedeno typem type TypeMemberPointer), GetMemberType metoda vrátí třídu, která ukazatel je ukazatel-na-člen.
IDebugHostType2/IDebugHostType – metody související s poli
Pole jsou typy, ve kterých GetTypeKind vrací TypeArray. Všimněte si, že pole definovaná systémem typů hostitele ladění nejsou stejná jako jednorozměrná, nulová indexová, zabalená lineární jednorozměrná pole, která C využívá. Pole stylu jazyka C se vejdou do definice, ale celkový rozsah pole je širší v IDebugHostType. Pole v hostiteli ladění může být multidimenzionální a každá dimenze v rámci pole je definována popisovačem označovaným jako popisovač ArrayDimensionThis má následující pole:
| (No improvements necessary, the translation is already optimal.) | Význam |
|---|---|
| LowerBound | Základní index pole jako podepsaná 64bitová hodnota. U pole stylu jazyka C to bude vždy nula. Nemusí to být. Jednotlivé rozměry pole lze považovat za počáteční na libovolném 64bitovém indexu, a to i záporně. |
| Délka | Délka dimenze pole jako 64bitová hodnota bez znaménka. Indikace pole zahrnuje polovinu otevřené sady [LowerBound, LowerBound + Length). |
| Krok | Definuje krok dimenze pole. Pro zvýšení jednoho (z N na N + 1) v indexu této dimenze to znamená, kolik bajtů se má posunout vpřed v paměti. U pole stylu jazyka C by to byla velikost každého prvku pole. Nemusí to být. Odsazení mezi prvky lze vyjádřit jako krok větší než velikost každého jednotlivého prvku. U multidimenzionálních polí by tato hodnota indikovala, jak přesunout celou dimenzi dopředu. Představte si matici M x N. To může být popsáno ve formě hlavního řádku jako dvě dimenze: |
{ [LowerBound: 0, Length: M, Stride: N \* sizeof(element)], [LowerBound: 0, Length: N, Stride: sizeof(element)]}
nebo může být případně popsána ve formě hlavního sloupce jako dvě dimenze:
{ [LowerBound: 0, Length: M, Stride: sizeof(element)], [LowerBound: 0, Length: N, Stride: M \* sizeof(element)]}
Koncept ArrayDimension umožňuje tento stupeň flexibility.
Následující metody IDebugHostType jsou specifické pro typy polí.
STDMETHOD(GetArrayDimensionality)(\_Out_ ULONG64\* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(\_In_ ULONG64 dimensions, \_Out_writes_(dimensions) ArrayDimension \*pDimensions) PURE;
Metoda GetArrayDimensionality vrátí počet dimenzí, ve které je pole indexováno. U polí stylu jazyka C bude vrácená hodnota vždy 1.
GetArrayDimensions metoda vrátí sadu popisovačů, jeden pro každou dimenzi pole, jak označuje GetArrayDimensionality metoda. Každý popisovač je arrayDimension struktura, která popisuje počáteční index, délku a dopředu krok každé dimenze pole. To umožňuje popisy výrazně výkonnějších maticových konstruktorů, než je povoleno v systému typů jazyka C.
U polí ve stylu jazyka C se zde vrátí jedna dimenze matice s hodnotami, které jsou vždy:
- LowerBound = 0
- Délka = ARRAYSIZE(matice)
- Stride = sizeof(elementType)
IDebugHostType2/IDebugHostType – metody související s funkcí
Typy, které označují, že jsou typy funkcí prostřednictvím typu TypeFunction podporují následující metody v IDebugHostType i 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;
GetFunctionCallingConvention metoda vrátí volání konvence funkce. Takový je vrácen jako člen CallConventionKind výčtu.
GetFunctionReturnType metoda vrátí návratový typ funkce.
GetFunctionParameterTypeCount metoda vrátí počet argumentů, které funkce přebírá. Všimněte si, že značka argumentu argumentu proměnné založené na teček C/C++ se v tomto počtu nepovažuje. Přítomnost takového musí být zjištěna metodou GetFunctionVarArgsKind. Bude obsahovat pouze argumenty před třemi tečky.
GetFunctionParameterTypeAt metoda vrátí typ i-th argumentu funkce.
GetFunctionVarArgsKind metoda vrátí, zda daná funkce využívá seznam argumentů proměnných, a pokud ano, jaký styl argumentů proměnné využívá. Takový je definován členem VarArgsKind výčtu definované takto:
| Výčet | Význam |
|---|---|
| VarArgsNone | Funkce nepřebírají žádné argumenty proměnných. |
| VarArgsCStyle | Funkce je funkce ve stylu jazyka C (returnType(arg1, arg2, ...)). Počet argumentů hlášených funkcí neobsahuje argument tří teček. K předání libovolného argumentu proměnné dojde po počtu argumentů vrácených GetFunctionParameterTypeCount metoda. |
IDebugHostType2 GetFunctionVarArgsKind
GetFunctionVarArgsKind metoda vrátí, zda daná funkce využívá seznam argumentů proměnných, a pokud ano, jaký styl argumentů proměnné využívá. Takový je definován členem VarArgsKind výčtu definované takto:
IDebugHostType2/IDebugHostType – metody Typedef Související
Jakýkoli typ, který je typedef, se bude chovat, jako kdyby typ byl posledním typem podkladového typedef. To znamená, že metody jako GetTypeKind nebudou indikovat, že typ je typedef. Stejně tak GetBaseType nevrátí typ, na který definice odkazuje. Místo toho budou indikovat chování, jako by byly volány v konečné definici podkladové definice typedef. Příklad:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
IDebugHostType pro PMYSTRUCT nebo PTRMYSTRUCT bude hlásit následující informace:
- Metoda GetTypeKind vrátí TypePointer. Konečný základní typ MYSTRUCT * je skutečně ukazatel.
- Metoda GetBaseType vrátí typ pro MYSTRUCT. Základní typ MYSTRUCT * je MYSTRUCT.
Jediným rozdílem je, jak se chovají metody specifické pro typedef v IDebugHostType2. Tyto metody jsou:
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
V tomto příkladu:
- Metoda IsTypedef vrátí hodnotu true pro PMYSTRUCT i PTRMYSTRUCT.
- Metoda GetTypedefBaseType vrátí MYSTRUCT * pro PMYSTRUCT a PMYSTRUCT pro PTRMYSTRUCT.
- Metoda GetTypedefFinalBaseType vrátí mySTRUCT * pro oba typy.
Metoda IsTypedef je jedinou metodou, která dokáže zjistit, zda je typ typedef. Metoda GetTypeKind se bude chovat, jako kdyby byla volána u základního typu.
GetTypedefBaseType metoda vrátí okamžitou definici typedef. V příkladech popsaných v dokumentaci:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
tato metoda vrátí MYSTRUCT * pro PMYSTRUCT a PMYSTRUCT pro PTRMYSTRUCT.
GetTypedefFinalBaseType metoda vrátí konečný typ, pro který typedef je definice. Pokud je typedef definicí jiné definice typedef, bude pokračovat v sledování řetězce definic, dokud nedosáhne typu, který není typedef a tento typ bude vrácen. V příkladech popsaných v dokumentaci:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
tato metoda vrátí MYSTRUCT * při zavolání na PMYSTRUCT nebo PTRMYSTRUCT.
metody vytváření typů IDebugHostType2/IDebugHostType
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;
hodnoty symbolů konstanty: IDebugHostConstant
Pro umístění, kde jsou konstantní hodnoty přítomny v symbolických informacích (kde konkrétní hodnota je symbol, který může nebo nemusí být konstantní hodnotou), rozhraní IDebugHostConstant vyjadřuje pojem takové konstanty. Obvykle se používá na místech, jako jsou argumenty šablony, kde daný argument je obvykle typem, ale může to být netypový argument šablony (např. konstanta).
Rozhraní IDebugHostConstant je definováno následujícím způsobem (ignorování obecných metod implementovaných IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostConstant, IDebugHostSymbol)
{
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Metoda GetValue vrátí hodnotu konstanty zabalené do VARIANT. Je důležité poznamenat, že GetType metoda na IDebugHostSymbol může vrátit konkrétní typ symbol pro konstantu. Vtakovýchch materiálech není v takových případech zaručeno, že balení konstantní hodnoty definované symbolem typu je stejné jako balení vrácené metodou GetValue zde.
přístup datových členů: IDebugHostField
IDebugHostField třída představuje symbol, který je datový člen třídy, struktury, sjednocení nebo jiného typu konstruktoru. Nepředstavuje bezplatná data (např. globální data). Rozhraní je definováno následujícím způsobem (ignorování metod obecných pro 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;
}
Metoda GetLocationKind vrátí, jaký druh umístění je symbol podle LocationKind výčtu. Takový výčet může být jedna z následujících hodnot:
| Výčet | Význam |
|---|---|
| LocationMember | Pole je běžný datový člen třídy, struktury, sjednocení nebo jiného typu konstruktoru. Má posun, který je relativní vzhledem k základní adrese obsahujícího konstruktoru typu. Tato základní adresa je obvykle reprezentována tímto ukazatelem. Posun pole lze načíst metodou GetOffset. Metody GetLocation a GetValue selžou pro pole, které je LocationMember. |
| LocationStatic | Pole je statické a má vlastní adresu. Metoda GetLocation vrátí abstraktní umístění (např. adresu) statického pole. Metody GetOffset a GetValue selžou pro pole, které je LocationStatic. |
| LocationConstant | Pole je konstanta a má hodnotu. GetValue metoda vrátí hodnotu konstanty. Metody GetOffset a GetLocation selžou pro pole, které je LocationConstant |
| LocationNone | Pole nemá žádné umístění. Je možné, že kompilátor optimalizoval nebo se jedná o statické pole, které je deklarováno, ale nikdy není definováno. Bez ohledu na to, jak se takové pole stalo, nemá žádnou fyzickou přítomnost ani hodnotu. Je to jen v symbolech. Všechny metody získání (GetOffset, GetLocation a GetValue) selžou pro pole, které je LocationNone. |
Pro pole, která mají posun (např. pole, jejichž druh umístění označuje LocationMember), Metoda GetOffset vrátí posun od základní adresy obsahujícího typu (tento ukazatel) na data pro samotné pole. Tyto posuny jsou vždy vyjádřeny jako 64bitové hodnoty bez znaménka. Pokud dané pole nemá umístění, které je posunem od základní adresy obsahujícího typu, metoda GetOffset selže.
Pro pole, která mají adresu bez ohledu na konkrétní instanci typu (např. pole, jejichž druh umístění označuje LocationStatic), metoda GetLocation vrátí abstraktní umístění (adresu) pole. Pokud dané pole nemá statické umístění, metoda GetLocation selže.
Pro pole, která mají definovanou konstantní hodnotu v rámci symbolických informací (například pole, jejichž druh umístění označuje LocationConstant), metoda GetValue vrátí konstantní hodnotu pole. Pokud dané pole nemá konstantní hodnotu, GetValue metoda selže.
bezplatný přístup k datům: IDebugHostData
Data v modulech, které nejsou členy jiného typu, jsou reprezentovány rozhraním IDebugHostData. Toto rozhraní je definováno následujícím způsobem (ignorování metod obecných pro IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostData, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Všechny tyto metody jsou sémanticky ekvivalentní jejich protějškům v IDebugHostField. Jediným rozdílem je, že Metoda GetLocationKind nikdy nevrátí LocationMember pro bezplatná data.
Metoda GetLocationKind vrátí, jaký druh umístění je symbol podle LocationKind výčtu. Popis tohoto výčtu najdete v dokumentaci pro IDebugHostField.
Pro data, která mají adresu, GetLocation metoda vrátí abstraktní umístění (adresu) pole. Pokud daná data nemají statické umístění, metoda GetLocation selže.
Pro datawhich má konstantní hodnotu definovanou v symbolických informacích (např. data, jejichž druh umístění označuje LocationConstant), Metoda GetValue vrátí konstantní hodnotu pole. Pokud daná data nemají konstantní hodnotu, GetValue metoda selže.
základní třídy : IDebugHostBaseClass
Hierarchie dědičnosti daného typu je vyjádřena podřízenými položkami symbolu typu. Pokud daný typ odvozuje (dědičnost moudrá) z jednoho nebo více typů, bude existovat jeden nebo více podřízených objektů SymbolBaseClass symbolu typu pro daný typ. Každý z těchto symbolů SymbolBaseClass představuje okamžitou dědičnost z určitého typu. Název základní třídy je jak název symbolu SymbolBaseClass, tak i název symbolu typu pro základní třídu. Metoda GetType na symbol SymbolBaseClass lze použít k získání symbolu typu pro samotnou základní třídu. Hierarchii úplné dědičnosti je možné přecházet rekurzivně zkoumáním podřízených symbolů SymbolBaseClass. Každý z těchto symbolů základní třídy je vyjádřen rozhraníM IDebugHostBaseClass, které je definováno následujícím způsobem (ignorování metod obecných pro IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostBaseClass, IDebugHostSymbol)
{
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
}
GetOffset metoda vrátí posun základní třídy ze základní adresy odvozené třídy. Takový posun může být nulový nebo může být kladné 64bitové hodnoty bez znaménka.
veřejné symboly : IDebugHostPublic
Veřejné symboly představují věci ve veřejné tabulce v souboru symbolů. Jsou to v podstatě adresy pro export. K veřejnému symbolu nejsou přidruženy žádné informace o typu – pouze adresa. Pokud volající výslovně nepožaduje veřejný symbol, hostitel ladění dává přednost vrácení privátních symbolů pro každý dotaz. Veřejný symbol je vyjádřen rozhraním IDebugHostPublic, které je definováno následujícím způsobem (ignorování metod, které jsou obecné pro IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostPublic, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
}
Všechny tyto metody jsou sémanticky ekvivalentní jejich protějškům v IDebugHostField. Jediným rozdílem je, že Metoda GetLocationKind nikdy nevrátí LocationMember nebo LocationConstant pro takové symboly.
Metoda GetLocationKind vrátí, jaký druh umístění je symbol podle LocationKind výčtu. Popis tohoto výčtu najdete v dokumentaci pro IDebugHostField.
Pro data, která mají adresu, GetLocation metoda vrátí abstraktní umístění (adresu) pole. Pokud daná veřejnost nemá statické umístění, metoda GetLocation selže.
podpisy modulů a porovnávání verzí: IDebugHostModuleSignature
Podpisy modulů představují způsob, jak zkontrolovat, jestli daný modul splňuje sadu kritérií týkajících se pojmenování a správy verzí. Podpis modulu se vytvoří prostřednictvím metody CreateModuleSignature v IDebugHostSymbols. Může odpovídat názvu modulu a volitelnému rozsahu čísel verzí modulu. Po vytvoření takového podpisu klient obdrží rozhraní IDebugHostModuleSignature, které je definováno takto:
DECLARE_INTERFACE_(IDebugHostModuleSignature, IUnknown)
{
STDMETHOD(IsMatch)(_In_ IDebugHostModule* pModule, _Out_ bool* isMatch) PURE;
}
Metoda IsMatch porovnává konkrétní modul (jak je dán symbolem IDebugHostModule) proti podpisu, porovnává název modulu a verzi s názvem a rozsahem verzí označeným v podpisu. Indikuje, jestli se daný symbol modulu shoduje s podpisem.
Podpisy typů a porovnávání typů: IDebugHostTypeSignature
Podpisy typu představují způsob, jak zkontrolovat, jestli daná instance typu splňuje sadu kritérií pro název typu, obecné argumenty typu a modul, ve které se typ nachází. Podpis typu se vytvoří prostřednictvím metody CreateTypeSignature na IDebugHostSymbols. Po vytvoření takového podpisu klient obdrží rozhraní IDebugHostTypeSignature, které je definováno takto:
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;
}
Metoda GetHashCode vrátí 32bitový kód hash pro podpis typu. Hostitel ladění zaručuje synchronizaci v implementaci mezi kódem hash vrácený pro instance typů a kódem hash vrácený pro podpisy typu. Pokud je instance typu schopná shodovat s podpisem typu s výjimkou globální shody, budou mít oba stejný 32bitový hashovací kód. To umožňuje počáteční rychlé porovnání a shodu mezi instancí typu a řadu podpisů typů zaregistrovaných ve správci datového modelu.
Metoda IsMatch vrátí indikaci, zda konkrétní instance typu odpovídá kritériím zadaným v podpisu typu. Pokud ano, vrátí se indikace, stejně jako enumerátor, který bude indikovat všechny konkrétní části instance typu (jako symboly), které odpovídají zástupným znakům v podpisu typu.
Metoda CompareAgainst porovnává podpis typu s jiným podpisem typu a vrátí způsob porovnání dvou podpisů. Výsledek porovnání vrácený je členem výčtu SignatureComparison, který je definován takto:
| Výčet | Význam |
|---|---|
| Nesouvisející | Mezi dvěma podpisy nebo typy, které se porovnávají, neexistuje žádný vztah. |
| Mnohoznačný | Jeden podpis nebo typ porovnává nejednoznačně s druhým. U dvou podpisů typu to znamená, že existují potenciální instance typu, které by mohly odpovídat každému podpisu stejně dobře. Jako příklad jsou dva podpisy typu uvedené níže nejednoznačné. Podpis 1: std::pair<*, int> Podpis 2: std::pair<int,*>, protože instance typu std::pair<int, int> odpovídá jedné stejně dobře (obě mají jeden beton a jednu shodu se zástupnými znamérnami). |
| LessSpecific | Jeden podpis nebo typ je méně specifický než druhý. Často to znamená, že méně specifický podpis má zástupný znak, ve kterém má konkrétnější typ. Například první podpis níže je méně specifický než druhý podpis. Podpis 1: std::pair<*, int> Podpis 2: std::pair<int, int>, protože má zástupný znak (*), kde druhý má konkrétní typ (int). |
| MoreSpecific | Jeden podpis nebo typ je konkrétnější než druhý. Často to znamená, že konkrétnější podpis má konkrétní typ, kde méně specifický podpis má zástupný znak. Například první podpis níže je konkrétnější než druhý. Podpis 1: std::pair<int, int> Podpis 2: std::pair<*, int>, protože má konkrétní typ (int), kde druhý má zástupný znak (*). |
| Identický | Dva podpisy nebo typy jsou identické. |
Viz také
Toto téma je součástí řady, která popisuje rozhraní přístupná z jazyka C++, jak je použít k sestavení rozšíření ladicího programu založeného na jazyce C++ a jak využít jiné konstruktory datového modelu (např. JavaScript nebo NatVis) z rozšíření datového modelu jazyka C++.
Přehled datového modelu Ladicího programu C++
objekty C++ datového modelu ladicího programu
datový model Ladicího programu C++ – další rozhraní