Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
Ez a témakör bemutatja és áttekinti, hogyan használható a Hibakereső adatmodell C++ interfésze a hibakereső képességeinek kibővítéséhez és testreszabásához.
Hibakereső adatmodell C++ gazdafelületei
Hibakereső adatmodell gazdagépe
A Hibakereső adatmodell úgy lett kialakítva, hogy egy olyan összetevőalapú rendszer legyen, amely számos különböző környezetben üzemeltethető. Az adatmodellt általában egy hibakereső alkalmazás környezetében üzemeltetik. Ahhoz, hogy az adatmodell gazdagépe lehessen, számos interfészt kell implementálnunk a hibakereső alapvető jellemzőinek elérhetővé tételéhez: célzását, memóriatereit, kiértékelőjét, szimbolikus és típusrendszerét stb. Bár ezeket az interfészeket minden olyan alkalmazás implementálja, amely az adatmodellt szeretné üzemeltetni, azokat az alapvető adatmodell, valamint az adatmodellel együttműködő bővítmények is felhasználják.
Az alapvető interfészek halmaza a következő:
| Felület neve | Leírás |
|---|---|
| IDebugHost | A hibakeresési gazdagép alapvető felülete. |
| IDebugHostStatus | Egy felület, amellyel az ügyfél lekérdezheti a gazdagép állapotát. |
| IDebugHostContext | A gazdagépen belüli környezet absztrakciója (pl. egy adott cél, egy adott folyamat, egy adott címtér stb.) |
| IDebugHostErrorSink | A hívók által a gazdagép és az adatmodell egyes részeiből származó hibák fogadásához implementált felület |
| IDebugHostEvaluator /IDebugHostEvaluator2 | A hibakeresési gazdagép kifejezésértékelője. |
| IDebugHostExtensibility | A gazdagép vagy annak egyes részei (például a kifejezésértékelő) képességeinek bővítésére szolgáló felület. |
A típusrendszer és a szimbolikus interfészek a következők:
| InterfaceName | Leírás |
|---|---|
| IDebugHostSymbols | Alapvető felület, amely hozzáférést biztosít a szimbólumokhoz és feloldja a szimbólumokat |
| IDebugHostSymbol / IDebugHostSymbol2 | Bármilyen szimbólumot jelöl. Az adott szimbólum ennek a felületnek a származtatása. |
| IDebugHostModule | Egy folyamaton belül betöltött modult jelöl. Ez egyfajta szimbólum. |
| IDebugHostType /IDebugHostType2 | Natív/nyelvi típust jelöl. |
| IDebugHostConstant | Szimbólumadatokon belüli állandót jelöl (például: nem típusú sablonargumentum a C++-ban) |
| IDebugHostField | Egy struktúrán vagy osztályon belüli mezőt jelöl. |
| IDebugHostData | Egy modulon belüli adatokat jelöl (ha egy struktúrában vagy osztályban ez egy IDebugHostField lenne) |
| IDebugHostBaseClass | Alaposztályt jelöl. |
| IDebugHostPublic | Egy PDB nyilvános táblájának szimbólumát jelöli. Ehhez nincs társítva típusinformáció. Ez egy név és cím. |
| IDebugHostModuleSignature | Modul-aláírást jelöl – olyan definíciót, amely név és/vagy verzió szerint megfelel a modulok egy készletének |
| IDebugHostTypeSignature | Típusadakciót jelöl – olyan definíciót, amely modul és/vagy név szerinti típuskészletnek felel meg |
Az alapvető gazdafelület: IDebugHost
Az IDebugHost felület minden adatmodell-gazdagép alapvető felülete. A definíció a következő:
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;
}
A GetHostDefinedInterface metódus visszaadja a gazdagép fő privát felületét, ha létezik ilyen az adott gazdagéphez. A Windows hibakeresési eszközei esetében az itt visszaadott felület egy IDebugClient (az IUnknown szolgáltatásba kerül).
A GetCurrentContext metódus egy felületet ad vissza, amely a hibakereső gazdagép aktuális állapotát jelöli. Ennek pontos jelentése a gazdagépre marad, de általában olyan dolgokat tartalmaz, mint a munkamenet, a folyamat és a címtér, amely aktív a hibakeresési gazdagép felhasználói felületén. A visszaadott környezeti objektum nagyrészt átlátszatlan a hívó számára, de fontos objektum, amelyet át kell adni a hívások között a hibakeresési gazdagépnek. Ha például egy hívó olvas memóriát, fontos tudnia, hogy melyik folyamatból és címtérből olvassa be a memóriát. A rendszer ezt a fogalmat a metódusból visszaadott környezeti objektum fogalmába foglalja bele.
A GetDefaultMetadata metódus egy alapértelmezett metaadattárat ad vissza, amely bizonyos műveletekhez (például sztringátalakításhoz) használható, ha nem ad át explicit metaadatokat. Ez lehetővé teszi, hogy a hibakeresési gazdagép szabályozhassa az adatok megjelenítési módját. Az alapértelmezett metaadatok közé tartozhat például egy PreferredRadix-kulcs, amely lehetővé teszi, hogy a gazdagép jelezze, hogy az ordinálokat tizedes vagy hexadecimális értékben kell-e megjeleníteni, ha másként nincs megadva.
Vegye figyelembe, hogy az alapértelmezett metaadattár tulajdonságértékeinek manuálisan kell feloldani, és át kell adni azt az objektumot, amelyhez az alapértelmezett metaadatokat lekérdezik. A GetKey metódust a GetKeyValue helyett kell használni.
Az állapotkezelő felület: IDebugHostStatus
Az IDebugHostStatus felület lehetővé teszi, hogy az adatmodell vagy a hibakeresési gazdagép ügyfele érdeklődjön a hibakeresési gazdagép állapotának bizonyos aspektusairól. Az interfész a következőképpen van definiálva:
DECLARE_INTERFACE_(IDebugHostStatus, IUnknown)
{
STDMETHOD(PollUserInterrupt)(_Out_ bool* interruptRequested) PURE;
}
A PollUserInterrupt metódus segítségével megtudhatja, hogy a hibakeresési gazdagép felhasználója kérte-e az aktuális művelet megszakítását. Az adatmodell egyik tulajdonságeleme például tetszőleges kódba (például JavaScript-metódusba) hívhat be. Ez a kód tetszőleges ideig tarthat. A hibakeresési gazdagép válaszkészsége érdekében minden olyan kódnak, amely tetszőleges ideig tarthat, ennek a metódusnak a meghívásával meg kell keresnie egy megszakítási kérést. Ha az interruptRequested érték ismét igaz, a hívónak azonnal le kell szakítania és vissza kell adnia a E_ABORT eredményét.
A környezeti felület: IDebugHostContext
A környezet az adatmodell és a mögöttes hibakeresési gazdagép egyik legfontosabb aspektusa. Amikor egy objektumot tárol, fontos tudnia, hogy honnan származik egy objektum – milyen folyamat van benne, milyen címtérrel van társítva. Ennek az információnak a ismerete lehetővé teszi az olyan dolgok helyes értelmezését, mint a mutatóértékek. Az IDebugHostContext típusú objektumot számos metódusnak át kell adni a hibakeresési gazdagépen. Ez a felület többféleképpen is beszerezhető:
- A hibakereső aktuális környezetének lekérésével: az IDebugHost GetCurrentContext metódusának meghívása
- Objektum környezetének beolvasásával: az IModelObject GetContext metódusának meghívása
- Egy szimbólum környezetének lekérésével: az IDebugHostSymbol GetContext metódusának meghívása
Ezen kívül két érték van, amelyek különleges jelentéssel rendelkeznek egy IDebugHostContext interfész kontextusában, amelyet egy adatmodellből vagy egy hibakeresési gazdamódszerből adnak vissza vagy adnak át:
nullptr: azt jelzi, hogy nincs kontextus. Bizonyos objektumok esetében teljesen érvényes, hogy nincs kontextusa. Az adatmodell gyökérnévterében található Hibakereső objektum nem hivatkozik egy adott folyamaton vagy címtéren belüli semmire. Nincs kontextusa.
USE_CURRENT_HOST_CONTEXT: egy sentinel érték, amely azt jelzi, hogy a hibakeresési gazdagép aktuális felhasználói felületi környezetét kell használni. Ez az érték soha nem lesz visszaadva a hibakeresési gazdagépről. Azonban bármely olyan hibakeresési gazdamódszernek átadható, amely az IDebugHostContext bemenetét veszi igénybe az IDebugHost GetCurrentContext metódusának explicit meghívása helyett. Vegye figyelembe, hogy a USE_CURRENT_HOST_CONTEXT explicit átadása gyakran hatékonyabb, mint az aktuális környezet explicit lekérése.
A gazdagépkörnyezet környezetei nagyrészt átlátszatlanok a hívó számára. Az egyetlen művelet, amelyet a központi hibakeresési gazdagépen kívüli hívó végezhet egy gazdagépkörnyezettel, az egy másik gazdagépkörnyezettel való összehasonlítás.
Az IDebugHostContext felület a következőképpen van definiálva:
DECLARE_INTERFACE_(IDebugHostContext, IUnknown)
{
STDMETHOD(IsEqualTo)(_In_ IDebugHostContext *pContext, _Out_ bool *pIsEqual) PURE;
}
Az IsEqualTo metódus összehasonlít egy gazdagépkörnyezetet egy másik gazdagépkörnyezettel. Ha a két környezet egyenértékű, a rendszer ennek jelzését adja vissza. Vegye figyelembe, hogy ez az összehasonlítás nem felületi egyenértékűség. Ez a környezet mögöttes átlátszatlan tartalmát hasonlítja össze.
Hibaelosztó: IDebugHostErrorSink
Az IDebugHostErrorSink egy olyan eszköz, amellyel az ügyfél értesítéseket kaphat bizonyos műveletek során előforduló hibákról, és szükség esetén átirányíthatja ezeket a hibákat. Az interfész a következőképpen van definiálva:
enum ErrorClass
{
ErrorClassWarning,
ErrorClassError
}
DECLARE_INTERFACE_(IDebugHostErrorSink, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrError, _In_ PCWSTR message) PURE;
}
A ReportError metódus a hibaelosztó visszahívása, amely értesíti arról, hogy hiba történt, és lehetővé teszi a fogadó számára, hogy a hibát a megfelelő felhasználói felületre vagy mechanizmusra irányozza.
A gazdagép kiértékelője: IDebugHostEvaluator / IDebugHostEvaluator2
A hibakeresési gazdagép által az ügyfelek számára biztosított egyik legfontosabb funkció a nyelvalapú kifejezésértékelőhöz való hozzáférés. Az IDebugHostEvaluator és az IDebugHostEvaluator2 interfészek jelentik a funkció elérését a hibakeresési gazdagépről.
Az interfészek a következőképpen vannak definiálva:
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;
}
A EvaluateExpression metódus lehetővé teszi, hogy a hibakeresési gazdagép kiértékeljen egy nyelvi (például C++) kifejezést, és visszaadja a kifejezés kiértékelésének eredményül kapott értékét IModelObjectként. A módszernek ez a különleges változata csak nyelvi szerkezeteket tesz lehetővé. A hibakeresési gazdagép kifejezésértékelőjében megjelenő, a nyelvben nem szereplő további funkciók (pl. LINQ lekérdezési módszerek) ki vannak kapcsolva a kiértékeléshez.
A EvaluateExtendedExpression metódus hasonló a EvaluateExpression metódushoz, azzal a kivételrel, hogy egy adott hibakereső gazdagép további nem nyelvi funkciókat ad hozzá a kifejezésértékelőhöz. A Windows hibakeresési eszközei esetében például ez lehetővé teszi a névtelen típusok, LINQ-lekérdezések, modul-minősítők, formátumjelölők és egyéb nem C/C++ funkciók használatát.
IDebugHostEvaluator2
A AssignTo metódus a hibakeresés alatt álló nyelv szemantikájának megfelelően végzi a hozzárendelést.
Gazdagép bővíthetőségi felülete: IDebugHostExtensibility
A hibakeresési gazdagép bizonyos funkciói opcionálisan bővíthetőséghez kötöttek. Ez lehet például a kifejezés kiértékelője is. Az IDebugHostExtensibility felület az az eszköz, amellyel ezek a bővíthetőségi pontok elérhetők. Az interfész a következőképpen van definiálva:
DECLARE_INTERFACE_(IDebugHostExtensibility, IUnknown)
{
STDMETHOD(CreateFunctionAlias)(_In_ PCWSTR aliasName, _In_ IModelObject *functionObject) PURE;
STDMETHOD(DestroyFunctionAlias)(_In_ PCWSTR aliasName) PURE;
}
A CreateFunctionAlias metódus létrehoz egy "függvény aliast", egy "gyors aliast" egy olyan metódushoz, amelyet valamilyen bővítményben implementálnak. Ennek az aliasnak a jelentése gazdagépspecifikus. Kiterjesztheti a gazdagép kifejezésértékelőjét a függvénnyel, vagy teljesen másképpen működhet.
A DestroyFunctionAlias metódus visszavon egy korábbi hívást a CreateFunctionAlias metódushoz. A függvény a továbbiakban nem lesz elérhető a gyors aliasnév alatt.
Az adatmodell elérése
Először is az adatmodell bővíthetőségi API-jait úgy tervezték, hogy semlegesek legyenek az alkalmazás (általában egy hibakereső) számára, amely az adatmodell gazdagépeként működik. Elméletileg bármely alkalmazás üzemeltetheti az adatmodellt úgy, hogy olyan gazdagép API-kat biztosít, amelyek elérhetővé teszik az alkalmazás hibakeresési cél(ok) típusrendszerét, valamint egy előrejelzett objektumkészletet az adatmodell névterébe arról, hogy milyen célokat, folyamatokat, szálakat stb. hibakeresési cél(ok) között vannak.
Bár az adatmodell API-k - amelyek az IDataModel, az IDebugHostés az IModelObject külső részei - hordozhatóak, nem határozzák meg, hogy mi a "hibakereső bővítmény". Ma egy olyan összetevőnek, amely ki szeretné terjeszteni a Windows hibakeresési eszközeit és az általa biztosított motort, meg kell írnia egy motorbővítményt az adatmodellhez való hozzáférés érdekében. A motorbővítménynek csak motorkiterjesztésnek kell lennie annyiban, hogy ez a bővítmény betöltési és rendszerindítási mechanizmusa. Ezért a minimális megvalósítás a következőt nyújtaná:
- DebugExtensionInitialize: Egy olyan módszer, amely egy létrehozott IDebugClient használatával fér hozzá az adatmodellhez, és beállítja az objektummodell-manipulációkat.
- DebugExtensionUninitialize: Olyan módszer, amely visszavonja a DebugExtensionInitialize alkalmazásban végrehajtott objektummodell-manipulációkat.
- DebugExtensionCanUnload: Egy metódus, amely visszaadja, hogy a bővítmény eltávolítható-e. Ha továbbra is vannak élő COM-objektumok a bővítményben, ezt kell jeleznie. Ez a hibakereső a COM DllCanUnloadNow fájljának megfelelője. Ha ez visszaadja a S_FALSE a kiürítés sikertelenségének jelzését, a hibakereső később lekérdezheti, hogy biztonságos-e a kiürítés, vagy újraincializálhatja a bővítményt a DebugExtensionInitialize meghívásával. A bővítménynek mindkét útvonal kezelésére fel kell készülnie.
- DebugExtensionUnload: Olyan módszer, amely elvégzi a DLL eltávolítása előtt szükséges végleges törlést
A híd felülete: IHostDataModelAccess
Ahogy említettük, a DebugExtensionInitialize meghívásakor létrehoz egy hibakeresési ügyfelet, és hozzáférést kap az adatmodellhez. Az ilyen hozzáférést egy hídfelület biztosítja a Windows hibakeresési eszközeinek régi IDebug* felületei és az adatmodell között. Ez a hídfelület az "IHostDataModelAccess", és a következőképpen van definiálva:
DECLARE_INTERFACE_(IHostDataModelAccess, IUnknown)
{
STDMETHOD(GetDataModel)(_COM_Outptr_ IDataModelManager** manager, _COM_Outptr_ IDebugHost** host) PURE;
}
A GetDataModel metódus a hídfelület azon metódusa, amely hozzáférést biztosít az adatmodell mindkét oldalához: A hibakeresési gazdagépet (a hibakereső alsó szélét) a visszaadott IDebugHost felület fejezi ki Az adatmodell fő összetevője - az adatmodell-kezelőt a visszaadott IDataModelManager interfész fejezi ki
hibakereső adatmodell rendszerillesztői
Az adatmodell-gazdagép
A Hibakereső adatmodell úgy lett kialakítva, hogy egy olyan összetevőalapú rendszer legyen, amely számos különböző környezetben üzemeltethető. Az adatmodellt általában egy hibakereső alkalmazás környezetében üzemeltetik. Ahhoz, hogy az adatmodell gazdagépe lehessen, számos interfészt kell implementálnunk a hibakereső alapvető jellemzőinek elérhetővé tételéhez: célzását, memóriatereit, kiértékelőjét, szimbolikus és típusrendszerét stb. Bár ezeket az interfészeket minden olyan alkalmazás implementálja, amely az adatmodellt szeretné üzemeltetni, azokat az alapvető adatmodell, valamint az adatmodellel együttműködő bővítmények is felhasználják.
A típusrendszer és a szimbolikus interfészek a következők:
| Felület neve | Leírás |
|---|---|
| IDebugHostSymbols | Alapvető felület, amely hozzáférést biztosít a szimbólumokhoz és feloldja a szimbólumokat |
| IDebugHostSymbol / IDebugHostSymbol2 | Bármilyen szimbólumot jelöl. Az adott szimbólum ennek a felületnek a származtatása. |
| IDebugHostModule | Egy folyamaton belül betöltött modult jelöl. Ez egyfajta szimbólum. |
| IDebugHostType /IDebugHostType2 | Natív/nyelvi típust jelöl. |
| IDebugHostConstant | Szimbólumadatokon belüli állandót jelöl (például: nem típusú sablonargumentum a C++-ban) |
| IDebugHostField | Egy struktúrán vagy osztályon belüli mezőt jelöl. |
| IDebugHostData | Egy modulon belüli adatokat jelöl (ha egy struktúrában vagy osztályban ez egy IDebugHostField lenne) |
| IDebugHostBaseClass | Alaposztályt jelöl. |
| IDebugHostPublic | Egy PDB nyilvános táblájának szimbólumát jelöli. Ehhez nincs társítva típusinformáció. Ez egy név és cím. |
| IDebugHostModuleSignature | Modul-aláírást jelöl – olyan definíciót, amely név és/vagy verzió szerint megfelel a modulok egy készletének |
| IDebugHostTypeSignature | Típusadakciót jelöl – olyan definíciót, amely modul és/vagy név szerinti típuskészletnek felel meg |
A többi alapvető interfész a következő:
| Felület neve | Leírás |
|---|---|
| IDebugHost | A hibakeresési gazdagép alapvető felülete. |
| IDebugHostStatus | Egy felület, amellyel az ügyfél lekérdezheti a gazdagép állapotát. |
| IDebugHostContext | A gazdagépen belüli környezet absztrakciója (pl. egy adott cél, egy adott folyamat, egy adott címtér stb.) |
| IDebugHostErrorSink | A hívók által a gazdagép és az adatmodell egyes részeiből származó hibák fogadásához implementált felület |
| IDebugHostEvaluator /IDebugHostEvaluator2 | A hibakeresési gazdagép kifejezésértékelője. |
| IDebugHostExtensibility | A gazdagép vagy annak egyes részei (például a kifejezésértékelő) képességeinek bővítésére szolgáló felület. |
A fő szimbolikus felület: IDebugHostSymbols
Az IDebugHostSymbols felület a fő kiindulópont a hibakeresési cél szimbólumainak eléréséhez. Ez a felület lekérdezhető az IDebugHost egy példányából, és a következőképpen van definiálva:
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;
}
A CreateModuleSignature metódus létrehoz egy aláírást, amely felhasználható adott modulok név szerinti és opcionális verzió szerinti egyeztetésére. A modul-aláírásnak három összetevője van:
- Név: az egyező modulnak olyan névvel kell rendelkeznie, amely pontosan érzéketlen egyezés az aláírásban szereplő névvel
- Minimális verzió: ha meg van adva, az egyező modulnak legalább akkora verzióval kell rendelkeznie, mint ez a verzió. A verziók "A.B.C.D" formátumban vannak megadva, és minden további rész kevésbé fontos, mint az előző. Csak az első szegmens kötelező.
- Maximális verzió: ha meg van adva, a megfelelő modulnak olyan maximális verzióval kell rendelkeznie, amely nem lehet magasabb ennél a verziónál. A verziók "A.B.C.D" formátumban vannak megadva, és minden további rész kevésbé fontos, mint az előző. Csak az első szegmens kötelező.
A CreateTypeSignature metódus létrehoz egy aláírást, amely a modul és a típusnév használatával használható konkrét típuskészletek egyeztetésére. A típusnév-aláírási sztring formátuma a hibakeresés alatt álló nyelvre (és a hibakeresési gazdagépre) vonatkozik. C/C++ esetén az aláírási sztring egyenértékű a NatVis-típus specifikációval. Ez azt jelzi, hogy az aláírási sztring egy olyan típusnév, ahol a sablon argumentumaihoz helyettesítő karakterek (*) használhatók.
CreateTypeSignatureForModuleRange
A CreateTypeSignatureForModuleRange metódus létrehoz egy aláírást, amely felhasználható a konkrét típusok modulaláírás és típusnév szerinti egyeztetésére. Ez hasonló a CreateTypeSignature metódushoz, azzal a kivétellel, hogy egy adott modul átadása helyett a hívó átadja a modulaláírás létrehozásához szükséges argumentumokat (mintha a modulaláírás a CreateModuleSignature metódussal lett volna létrehozva).
Az EnumerateModules metódus létrehoz egy enumerátort, amely egy adott gazdagépkörnyezetben elérhető összes modult számba veszi. Ez a gazdagépkörnyezet beágyazhat egy folyamatkörnyezetet, vagy a Windows kernelhez hasonlót ágyazhat be.
A FindModuleByName metódus végignézi a megadott gazdagépkörnyezetet, és megkeres egy modult, amely a megadott névvel rendelkezik, és visszaad egy felületet. A modult a fájlkiterjesztéssel vagy anélkül, név szerint lehet keresni.
A FindModuleByLocation metódus áttekinti a megadott gazdagépkörnyezetet, és meghatározza, hogy melyik modul tartalmazza a megadott hely által megadott címet. Ezután egy interfészt ad vissza az ilyen modulhoz.
A GetMostDerivedObject a hibakereső típusrendszerével határozza meg egy objektum futásidejének típusát a statikus típusából. Ez a módszer csak a típusrendszerrétegben elérhető szimbolikus információkat és heurisztikus elemeket használja az elemzés elvégzéséhez. Ilyen információ lehet például a C++ RTTI (futási idő típusa) vagy az objektum virtuális függvénytábláinak alakzatának elemzése. Nem tartalmaz olyan dolgokat, mint például az előnyben részesített futtatókörnyezet-típus koncepciója egy IModelObjecten. Ha az elemzés nem talál futtatókörnyezettípust, vagy nem talál a metódusnak átadott statikus típustól eltérő futtatókörnyezettípust, előfordulhat, hogy a bemeneti hely és a típus el lesz adva. A metódus ezen okok miatt nem fog meghiúsulni.
A core individual symbol interface: IDebugHostSymbol
Az adatmodell-gazdagépről visszaadható szimbólumok valamilyen módon az IDebugHostSymbolból származnak. Ez az a központi felület, amelyet minden szimbólum implementál, függetlenül attól, hogy milyen típusú szimbólumot. A szimbólum típusától függően egy adott szimbólum más illesztők készletét is megvalósíthatja, amelyek az ezen interfész által képviselt szimbólumtípushoz egyedibb attribútumokat adnak vissza. Az IDebugHostSymbol2/IDebugHostSymbol felület a következőképpen van definiálva:
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;
}
Nagyon fontos megjegyezni, hogy ez a felület számos szimbólumtípust jelöl – a SymbolKind enumerálás által tagolt szimbólumokat, amelyek értékei a következők:
| Enumarant | Értelmezés |
|---|---|
| Jelkép | Meghatározatlan szimbólumtípus |
| SymbolModule | A szimbólum egy modul, és lekérdezhető az IDebugHostModule-hoz |
| SymbolType | A szimbólum egy típus, és lekérdezhető az IDebugHostType esetében |
| Szimbólummező | A szimbólum egy mező (egy struktúra vagy osztály adattagja), és lekérdezhető az IDebugHostFieldhez |
| SymbolConstant | A szimbólum állandó érték, és lekérdezhető az IDebugHostConstant esetében |
| SymbolData | A szimbólum olyan adat, amely nem tagja egy struktúrának vagy osztálynak, és lekérdezhető az IDebugHostData esetében |
| SymbolBaseClass | A szimbólum egy alaposztály, és lekérdezhető az IDebugHostBaseClass esetében |
| SymbolPublic | A szimbólum egy bejegyzés egy modul nyilvános táblájában (amely nem tartalmaz típusinformációt), és lekérdezhető az IDebugHostPublichez |
| SymbolFunction | A szimbólum egy függvény, és lekérdezhető az IDebugHostData esetében |
A GetContext metódus azt a környezetet adja vissza, amelyben a szimbólum érvényes. Bár ez olyan dolgokat jelöl, mint a hibakeresési cél és a folyamat/címtér, amelyben a szimbólum létezik, lehet, hogy nem olyan specifikus, mint egy más eszközökről lekért környezet (például egy IModelObject).
Az EnumerateChildren metódus egy enumerátort ad vissza, amely egy adott szimbólum összes gyermekét számba veszi. Egy C++ típus esetében például az alaposztályok, mezők, tagfüggvények és hasonlók mind a típusszimbólum gyermekének számítanak.
A modul felülete: IDebugHostModule
A hibakereső fogalma egy bizonyos címtérbe betöltött modulról az adatmodellben két különböző módon jelenik meg: A típusrendszer szintjén az IDebugHostModule felületen keresztül. Itt egy modul egy szimbólum, és a modul alapvető attribútumai az adatmodell szintjén kivetített felületi metódushívások a Debugger.Models.Module adatmodellen keresztül. Ez egy modul IDebugHostModule típusú rendszerének bővíthető beágyazása.
Az IDebugHostModule felület a következőképpen van definiálva (az IDebugHostSymbol általános metódusainak figyelmen kívül hagyása):
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;
}
A GetImageName metódus a modul képnevét adja vissza. Az allowPath argumentum értékétől függően előfordulhat, hogy a visszaadott kép neve tartalmazza a kép teljes elérési útját.
A GetBaseLocation metódus helystruktúraként adja vissza a modul alapterhelési címét. A modul visszaadott helystruktúrája általában egy virtuális címre hivatkozik.
A GetVersion metódus a modul verzióadatait adja vissza (feltéve, hogy ezek az információk sikeresen olvashatók ki a fejlécek közül). Ha egy adott verziót kér (nem null értékű kimeneti mutatón keresztül), és nem olvasható, a metódushívás megfelelő hibakódot ad vissza.
A FindTypeByName metódus megkeresi a modulban a típusnév alapján definiált típust, és egy típusszimbólumot ad vissza. Ez a módszer egy érvényes IDebugHostType értéket adhat vissza, amelyet soha nem ad vissza a modul gyermekeinek explicit rekurziója. A hibakeresési gazdagép lehetővé teheti származékos típusok létrehozását – a modulon belül soha nem használt, de olyan típusokból származó típusokat, amelyekből származik. Ha például a MyStruct struktúra a modul szimbólumaiban van definiálva, de a MyStruct ** típus soha nem használatos, a FindTypeByName metódus jogosan visszaadhat egy típusszimbólumot a MyStruct ** számára annak ellenére, hogy a típusnév soha nem jelenik meg explicit módon a modul szimbólumaiban.
A FindSymbolByRVA metódus egyetlen egyező szimbólumot talál a modul adott relatív virtuális címén. Ha a megadott RVA-n nincs egyetlen szimbólum (például több egyezés van), a rendszer hibát ad vissza ezzel a módszerrel. Vegye figyelembe, hogy ez a módszer inkább egy privát szimbólumot ad vissza a nyilvános táblák egyik szimbóluma helyett.
A FindSymbolByName metódus egyetlen globális szimbólumot talál a megadott névből a modulon belül. Ha egyetlen szimbólum sem felel meg a megadott névnek, ez a metódus hibát ad vissza. Vegye figyelembe, hogy ez a módszer inkább egy privát szimbólumot ad vissza a nyilvános táblák egyik szimbóluma helyett.
Hozzáférés a típusrendszerhez: IDebugHostType2/ IDebugHostType
Egy adott nyelvet/natív típust az IDebugHostType2 vagy az IDebugHostType felület ír le. Vegye figyelembe, hogy az ezen felületeken található metódusok némelyike csak bizonyos típusokra vonatkozik. Egy adott típusszimbólum a TypeKind enumerálásban leírt alábbi típusok egyikére hivatkozhat:
| Típus típusa | Leírás |
|---|---|
| TypeUDT | Felhasználó által definiált típus (struct, class, union stb.). A typeUDT típusú natív típussal rendelkező modellobjektumok az ObjectTargetObject vesszővel rendelkező reprezentációját használják, ahol a típus mindig a megfelelő IModelObject-ben van tárolva. |
| TypePointer | Egy mutató. A TypePointer típusú natív típusú modellobjektumok az ObjectIntrinsic canonical reprezentációjával rendelkezik, ahol a mutató értéke nulla, és VT_UI8 van kiterjesztve, és ebben a 64 bites formában belső adatként van tárolva. A TypePointer bármely típusszimbólumának van egy alaptípusa (a GetBaseType metódus által visszaadott) típusnak, amelyre a mutató mutat. |
| TypeMemberPointer | Mutató az osztálytagra. A TypeMemberPointer típusú natív típussal rendelkező modellobjektumnak belsőleg (az érték megegyezik a mutató értékével) van egy belső reprezentációja. Ennek az értéknek a pontos jelentése a fordító/hibakeresési gazdagép specifikus. |
| TypeArray | Egy tömb. A TypeArray típusú natív típusú modellobjektumok az ObjectTargetObject kanonikus ábrázolását használják. A tömb alapcíme az objektum helye (a GetLocation metódussal kérhető le), és a tömb típusa mindig megmarad. A TypeArray bármely típusszimbóluma rendelkezik egy alaptípussal (a GetBaseType metódus által visszaadott) típussal, amelynek tömbje a tömb. |
| TypeFunction | Egy függvény. |
| TypeTypedef | Egy typedef. Egy olyan natív típusú modellobjektum, amelynek típusa egyébként TypeTypedef, a típusdef alapjául szolgáló végső típus canonical reprezentációjához hasonló canval rendelkezik. Ez teljesen transzparensnek tűnik az objektum végfelhasználója és a típusinformációk számára, kivéve, ha az IDebugHostType2 explicit typedef metódusait használják a typedef-információk lekérdezésére, vagy van egy explicit adatmodell, amely a typedef-ben van regisztrálva. Vegye figyelembe, hogy a GetTypeKind metódus soha nem ad vissza TypeTypedef értéket. Minden metódus azt adja vissza, amit a típusdef alapjául szolgáló végső típus visszaad. Az IDebugHostType2 típusdefiniált metódusai a typedef-specifikus információk lekérésére használhatók. |
| TypeEnum | Egy szám. A TypeEnum típusú natív típusú modellobjektumok az ObjectIntrinsic canonical reprezentációját használják, ahol az intrinsic értéke és típusa megegyezik az enumerálási értékkel. |
| TypeIntrinsic | Belső (alaptípusú) típus. A typeIntrinsic típusú natív típusú modellobjektumok az ObjectIntrinsic canonical reprezentációját használják. A típusadatok megőrizhetők vagy nem tárolhatók – különösen akkor, ha az alapul szolgáló típust teljes mértékben az IModelObjectben tárolt belső adatok variáns adattípusa (VT_*) írja le |
A teljes IDebugHostType2/IDebugHostType felület a következőképpen van definiálva (az IDebugHostSymbol metódusok kivételével):
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 általános metódusok
A következő IDebugHostType metódusok minden típusra általánosak, függetlenül attól, hogy a GetTypeKind metódus milyen típusút ad vissza:
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
A GetTypeKind metódus visszaadja, hogy a szimbólum milyen típusra (mutató, tömb, belső stb.) hivatkozik.
A GetSize metódus a típus méretét adja vissza (mintha a C++-ban végrehajtotta volna a sizeof(type) értéket).
Ha a típus egy másik egyetlen típus származéka (például: mivel a MyStruct * a MyStructből származik), a GetBaseType metódus a származtatás alaptípusát adja vissza. A mutatók esetében ez a mutatott típust adja vissza. Tömbök esetén ez azt adja vissza, hogy a tömb milyen tömbből áll. Ha a típus nem ilyen származékos típus, hibaüzenet jelenik meg.
A GetHashCode metódus egy 32 bites kivonatkódot ad vissza a típushoz. A globális egyezés kivételével (például: a *-nak megfelelő típusaláírás, amely mindenre megfelel, ha a gazdagép engedélyezi), az adott típusaláírásnak megfelelő típuspéldánynak ugyanazt a kivonatkódot kell visszaadnia. Ezt a metódust a típus-aláírásokkal együtt használjuk a típusaadékok típuspéldányokhoz való egyeztetéséhez.
IDebugHostType2/IDebugHostType belső metódusok
Az alábbi IDebugHostType metódusok a belső típusokra (vagy olyan típusokra vonatkoznak, amelyek belső adatokat, például számokat) tárolnak:
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
A GetIntrinsicType metódus információt ad vissza arról, hogy milyen belső típusról van szó. Ebből a metódusból két érték lesz visszaadva:
- A belső típus a teljes típust (pl. egész szám, aláíratlan, lebegőpontos) jelöli, de a típus méretét nem (pl. 8 bit, 16 bit, 32 bit, 64 bit)
- A hordozó típusa azt jelzi, hogy a belső típus hogyan csomagolja be a VARIANT struktúrát. Ez egy VT_* állandó.
A két érték kombinációja biztosítja a belső információ teljes készletét.
IDebugHostType2/IDebugHostType Bitfield metódusok
Az alábbi IDebugHostType metódusok olyan típusokra vonatkoznak, amelyek bitmezőkben tárolják az adatokat. Az adatmodellben a bitmező elhelyezésére vonatkozó információk a hely attribútuma helyett az adatmodell típusszimbólumának részeként lesznek tárolva.
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
Ha egy adatstruktúra egy adott tagja bitmező (pl. ULONG MyBits:8), a mező típusadatai a bitmező elhelyezésére vonatkozó információkat hordoznak. A GetBitField metódussal lekérheti ezeket az információkat. Ez a metódus minden olyan típuson sikertelen lesz, amely nem bitmező. Ez az egyetlen oka annak, hogy a metódus sikertelen lesz. Elég egyszerűen meghívni ezt a metódust, és a sikert/hibát megtekinteni ahhoz, hogy megkülönböztessük a bitmezőt a nem bites mezőktől. Ha egy adott típus bitmezővel rendelkezik, a mezőpozíciókat a félig nyitott készlet (lsbOfField + lengthOfField : lsbOfField]
IDebugHostType2/IDebugHostType mutatóval kapcsolatos metódusok
Az alábbi IDebugHostType metódusok a mutatótípusokra vonatkoznak. Ilyenek azok a típusok, amelyeknél a GetTypeKind TypePointert vagy TypeMemberPointert ad vissza:
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
A mutatótípusok esetében a GetPointerKind metódus a mutató típusát adja vissza. Ezt a PointerKind enumerálás határozza meg.
Az olyan típusok esetében, amelyek mutató-tag típusúak (a TypeMemberPointer típusának jelzése szerint), a GetMemberType metódus azt az osztályt adja vissza, amelynek a mutatója az adott taghoz tartozik.
IDebugHostType2/IDebugHostType tömbhöz kapcsolódó metódusok
A tömbök olyan típusok, amelyeknél a GetTypeKind TypeArray értéket ad vissza. Vegye figyelembe, hogy a hibakeresési gazdagép típusrendszere által definiált tömbök nem azonosak a C által használt egydimenziós, nulla indexalapú, csomagolt lineáris egydimenziós tömbökével. A C stílusú tömbök illeszkednek a definícióba, de a tömbök általános hatóköre szélesebb az IDebugHostType-ban. A hibakeresési gazdagép egy tömbje többdimenziós lehet, és a tömbön belüli minden dimenziót egy ArrayDimensionThis leíróként ismert leíró definiálja a következő mezőkkel:
| Mező | Értelmezés |
|---|---|
| Alsó határ | A tömb alapindexe aláírt 64 bites értékként. C stílusú tömb esetén ez mindig nulla lesz. Nem kell. Egy tömb egyedi dimenziója bármely 64 bites indexnél kezdődhet, akár negatív is. |
| Hosszúság | A tömbdimenzió hossza aláíratlan 64 bites értékként. A tömb indexei a félig nyitott halmazra terjednek ki [LowerBound, LowerBound + Length). |
| Lovaglóülésben ráül | Meghatározza a tömbdimenzió lépéshosszát. A dimenzió indexében egy (N-ről N + 1)-ra való növekedés esetén ez azt jelzi, hogy hány bájtot kell előrelépni a memóriában. C stílusú tömb esetén ez a tömb egyes elemeinek mérete lenne. Nem kell. Az elemek közötti párnázás az egyes elemek méreténél nagyobb léptékben kifejezhető. Többdimenziós tömbök esetén ez az érték azt jelzi, hogyan lehet egy teljes dimenziót előremozdulni. Fontolja meg az M x N mátrixot. Ez a sor fő formájában két dimenzióként írható le: |
{ [LowerBound: 0, Length: M, Stride: N \* sizeof(element)], [LowerBound: 0, Length: N, Stride: sizeof(element)]}
vagy oszlopfőalakban két dimenzióként írható le:
{ [LowerBound: 0, Length: M, Stride: sizeof(element)], [LowerBound: 0, Length: N, Stride: M \* sizeof(element)]}
A ArrayDimension koncepciója ezt a rugalmasságot teszi lehetővé.
Az alábbi IDebugHostType metódusok tömbtípusokra vonatkoznak.
STDMETHOD(GetArrayDimensionality)(\_Out_ ULONG64\* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(\_In_ ULONG64 dimensions, \_Out_writes_(dimensions) ArrayDimension \*pDimensions) PURE;
A GetArrayDimensionality metódus a tömb indexelt dimenzióinak számát adja vissza. C stílusú tömbök esetén az itt visszaadott érték mindig 1 lesz.
A GetArrayDimensions metódus egy leírókészletet ad vissza a tömb minden dimenziójához a GetArrayDimensionality metódusnak megfelelően. Minden leíró egy ArrayDimension struktúra, amely az egyes tömbdimenziók kezdő indexét, hosszát és előremenetét írja le. Ez lehetővé teszi a C típusú rendszerben megengedettnél lényegesen hatékonyabb tömbszerkezetek leírását.
C-stílusú tömbök esetén a rendszer itt egyetlen tömbdimenziót ad vissza, amely mindig az alábbi értékeket adja vissza:
- LowerBound = 0
- Hossz = ARRAYSIZE(tömb)
- Stride = sizeof(elementType)
IDebugHostType2/IDebugHostType függvényhez kapcsolódó metódusok
Az IDebugHostType és az IDebugHostType2 esetében az alábbi metódusokat támogatják azok a típustípusok, amelyek azt jelzik, hogy függvénytípusok.
//
// 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;
A GetFunctionCallingConvention metódus a függvény hívási konvencióját adja vissza. Ezt a Rendszer a CallingConventionKind enumerálás tagjaként adja vissza.
A GetFunctionReturnType metódus a függvény visszatérési típusát adja vissza.
A GetFunctionParameterTypeCount metódus a függvény argumentumainak számát adja vissza. Vegye figyelembe, hogy ebben a számban a C/C++ három pontalapú változó argumentumjelölője nem számít bele. Ennek jelenlétét a GetFunctionVargsKind metóduson keresztül kell észlelni. Ez csak a három pont előtti argumentumokat tartalmazza.
A GetFunctionParameterTypeAt metódus az i-edik argumentum típusát adja vissza a függvénynek.
A GetFunctionVargsKind metódus azt adja vissza, hogy egy adott függvény használ-e változó argumentumlistát, és ha igen, milyen típusú változóargumentumokat használ. Ezt a VarArgsKind enumerálás egy tagja határozza meg a következőképpen:
| Enumeráns | Értelmezés |
|---|---|
| VarArgsNone | A függvény nem használ változóargumentumokat. |
| VarArgsCStyle | A függvény egy C stílusú varargs függvény (returnType(arg1, arg2, ...)). A függvény által jelentett argumentumok száma nem tartalmazza a három pont argumentumot. A változó argumentumátadás a GetFunctionParameterTypeCount metódus által visszaadott argumentumok száma után történik. |
IDebugHostType2 GetFunctionVarArgsKind
A GetFunctionVargsKind metódus azt adja vissza, hogy egy adott függvény használ-e változó argumentumlistát, és ha igen, milyen típusú változóargumentumokat használ. Ezt a VarArgsKind enumerálás egy tagja határozza meg a következőképpen:
IDebugHostType2/IDebugHostType typedef related methods
Minden típusdef úgy fog viselkedni, mintha a típus az utolsó típus, amely a typedef alapjául szolgál. Ez azt jelenti, hogy az olyan metódusok, mint a GetTypeKind, nem jelzik, hogy a típus típusdef. Hasonlóképpen, a GetBaseType nem azt a típust adja vissza, amelyre a definíció hivatkozik. Ehelyett úgy fognak viselkedni, mintha a típusdef alapjául szolgáló végső definícióban hívták volna meg őket. Példaként:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
A "PMYSTRUCT vagy PTRMYSTRUCT" típusú IDebugHostType a következő információkat jelenti:
- A GetTypeKind metódus a TypePointert adja vissza. A MYSTRUCT * végső mögöttes típusa valóban mutató.
- A GetBaseType metódus a MYSTRUCT típusát adja vissza. A MYSTRUCT * mögöttes típusa a MYSTRUCT.
Az egyetlen különbség itt az, hogy az IDebugHostType2 típusdefiniált metódusai hogyan viselkednek. Ezek a módszerek a következők:
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
Ebben a példában:
- Az IsTypedef metódus a PMYSTRUCT és a PTRMYSTRUCT esetében is igaz értéket ad vissza
- A GetTypedefBaseType metódus a MYSTRUCT * értéket adja vissza a PMYSTRUCT és a PMYSTRUCT függvényhez a PTRMYSTRUCT-hez
- A GetTypedefFinalBaseType metódus a MYSTRUCT * értéket adja vissza mindkét típushoz
Az IsTypedef metódus az egyetlen olyan módszer, amely képes ellenőrizni, hogy egy típus típusdef-e. A GetTypeKind metódus úgy fog viselkedni, mintha az alapul szolgáló típusra hívták volna.
A GetTypedefBaseType metódus a typedef azonnali definícióját adja vissza. A dokumentációban leírt példákban:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
ez a metódus a PMYSTRUCT és a PMYSTRUCT függvényhez a MYSTRUCT * értéket adja vissza a PTRMYSTRUCT-hez.
A GetTypedefFinalBaseType metódus azt a végső típust adja vissza, amelyhez a typedef definíciója tartozik. Ha a typedef egy másik típusdef definíciója, akkor ez mindaddig követi a definíciós láncot, amíg el nem éri azt a típusdef típust, amely nem típusdef, és a rendszer visszaadja a típust. A dokumentációban leírt példákban:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
ez a metódus a MYSTRUCT* függvényt adja vissza, ha a PMYSTRUCT vagy a PTRMYSTRUCT meghívást kap.
IDebugHostType2/IDebugHostType típusú létrehozási módszerek
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;
állandó szimbólumértékek: IDebugHostConstant
Azon helyek esetében, ahol az állandó értékek szimbolikus információkban vannak jelen (ahol egy adott érték egy szimbólum, amely lehet vagy nem állandó érték), az IDebugHostConstant felület kifejezi az ilyen állandó fogalmát. Ezt általában olyan helyeken használják, mint például a sablonargumentumok, ahol egy adott argumentum általában típus, de lehet, hogy nem típus típusú sablonargumentum (például állandó).
Az IDebugHostConstant felület a következőképpen van definiálva (az IDebugHostSymbol által implementált általános módszerek figyelmen kívül hagyása):
DECLARE_INTERFACE_(IDebugHostConstant, IDebugHostSymbol)
{
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
A GetValue metódus a VARIANT-ba csomagolt állandó értékét adja vissza. Fontos megjegyezni, hogy az IDebugHostSymbol GetType metódusa egy adott típusszimbólumot adhat vissza az állandóhoz. Ilyen esetekben nincs garancia arra, hogy a típusszimbólum által meghatározott állandó érték csomagolása megegyezik a GetValue metódus által itt visszaadott csomagolással.
adattagok hozzáférése: IDebugHostField
Az IDebugHostField osztály egy olyan szimbólumot jelöl, amely egy osztály, struktúra, unió vagy más típusú szerkezet adattagja. Nem szabad adatokat (például globális adatokat) jelöl. A felület meghatározása az alábbiak szerint történik (az IDebugHostSymbol általános metódusainak figyelmen kívül hagyása):
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;
}
A GetLocationKind metódus a LocationKind enumerálásnak megfelelően adja vissza, hogy a szimbólum milyen helyen található. Az ilyen számbavétel a következő értékek egyike lehet:
| Enumeráns | Értelmezés |
|---|---|
| LocationMember | A mező egy osztály, struktúra, egyesítő vagy más típusú szerkezet rendszeres adattagja. Eltolása a tartalmazó típusszerkezet alapcíméhez viszonyítva van. Az ilyen alapcímeket általában ez a mutató jelöli. A mező eltolása a GetOffset metódussal kérhető le. A GetLocation és a GetValue metódus sikertelen lesz egy LocationMember nevű mező esetében. |
| LocationStatic | A mező statikus, és saját címmel rendelkezik. A GetLocation metódus a statikus mező absztrakt helyét (például: címét) adja vissza. A GetOffset és a GetValue metódusok sikertelenek lesznek egy LocationStatic nevű mező esetében. |
| LocationConstant | A mező egy állandó és egy értékkel rendelkezik. A GetValue metódus az állandó értékét adja vissza. A GetOffset és a GetLocation metódus sikertelen lesz egy LocationConstant nevű mező esetében |
| LocationNone | A mezőnek nincs helye. Lehet, hogy a fordító optimalizálta, vagy lehet egy statikus mező, amely deklarált, de soha nem definiált. Függetlenül attól, hogy egy ilyen mező hogyan jött létre, nincs fizikai jelenléte vagy értéke. Csak a szimbólumokban van. Az összes beszerzési módszer (GetOffset, GetLocation és GetValue) sikertelen lesz egy LocationNone nevű mező esetében. |
Az eltolással rendelkező mezők esetében (például: olyan mezőknél, amelyek helytípusa a LocationMember értéket jelzi), a GetOffset metódus az eltolást az eltolást adja vissza az eltolást a tartalmazó típus alapcímétől (ez a mutató) a mező adataihoz. Az ilyen eltolások mindig aláíratlan 64 bites értékekként vannak kifejezve. Ha a megadott mező nem rendelkezik olyan helynel, amely eltolást jelent a tárolótípus alapcímétől, a GetOffset metódus sikertelen lesz.
Azon mezők esetében, amelyek címe az adott típuspéldánytól függetlenül (például a hely típusa a LocationStatic értéket jelzi), a GetLocation metódus a mező absztrakt helyét (címét) adja vissza. Ha a megadott mezőnek nincs statikus helye, a GetLocation metódus sikertelen lesz.
A szimbolikus információkban konstans értékkel rendelkező mezőknél (például: olyan mezőknél, amelyek helytípusa a LocationConstant értéket jelzi), a GetValue metódus a mező állandó értékét adja vissza. Ha a megadott mező nem rendelkezik állandó értékkel, a GetValue metódus sikertelen lesz.
ingyenes adathozzáférés: IDebugHostData
Az olyan modulokban lévő adatokat, amelyek nem más típusúak, az IDebugHostData felület képviseli. Ez a felület az alábbiak szerint van definiálva (az IDebugHostSymbol általános metódusainak figyelmen kívül hagyása):
DECLARE_INTERFACE_(IDebugHostData, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Ezek a módszerek szemantikailag egyenértékűek az IDebugHostFieldben található társaikkal. Az egyetlen különbség az, hogy a GetLocationKind metódus soha nem ad vissza LocationMember értéket az ingyenes adatokhoz.
A GetLocationKind metódus a LocationKind enumerálásnak megfelelően adja vissza, hogy a szimbólum milyen helyen található. Az enumerálás leírása az IDebugHostField dokumentációjában található.
A címmel rendelkező adatok esetében a GetLocation metódus a mező absztrakt helyét (címét) adja vissza. Ha a megadott adatoknak nincs statikus helye, a GetLocation metódus sikertelen lesz.
Ha az adatwhich egy állandó értéket határoz meg a szimbolikus információkban (például: az adatok, amelyek helytípusa a LocationConstant értéket jelzi), a GetValue metódus a mező állandó értékét adja vissza. Ha a megadott adatok nem rendelkeznek állandó értékkel, a GetValue metódus sikertelen lesz.
alaposztályok: IDebugHostBaseClass
Egy adott típus öröklési hierarchiáját egy típusszimbólum gyermekei fejezik ki. Ha egy adott típus egy vagy több típusból származik (öröklési szempontból bölcs), a típus szimbólumának egy vagy több SymbolBaseClass gyermeke lesz. A SymbolBaseClass szimbólumok mindegyike egy adott típusból való közvetlen öröklést jelöl. Az alaposztály neve mind a SymbolBaseClass szimbólum neve, mind az alaposztály típusszimbóluma. A SymbolBaseClass szimbólum GetType metódusával lekérheti magának az alaposztálynak a típusszimbólumát. A teljes öröklési hierarchia átjárható a SymbolBaseClass gyermekszimbólumainak rekurzív feltárásával. Mindegyik alaposztályszimbólumot az IDebugHostBaseClass felület fejezi ki, amely az alábbiak szerint van definiálva (az IDebugHostSymbol általános metódusainak figyelmen kívül hagyásával):
DECLARE_INTERFACE_(IDebugHostBaseClass, IDebugHostSymbol)
{
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
}
A GetOffset metódus az alaposztály eltolását adja vissza a származtatott osztály alapcíméből. Az ilyen eltolás lehet nulla vagy pozitív, nem aláírt 64 bites érték.
nyilvános szimbólumok: IDebugHostPublic
A nyilvános szimbólumok a nyilvános táblában lévő dolgokat jelölik egy szimbólumfájlban. Ezek tulajdonképpen exportálási címek. Nyilvános szimbólumhoz nincs típusinformáció társítva – csak egy cím. Hacsak a hívó nem kér kifejezetten nyilvános szimbólumot, a hibakereső gazdagép minden vizsgálathoz inkább privát szimbólumokat ad vissza. A nyilvános szimbólumokat az IDebugHostPublic felület fejezi ki, amely az alábbiak szerint van definiálva (figyelmen kívül hagyva az IDebugHostSymbol általános metódusait):
DECLARE_INTERFACE_(IDebugHostPublic, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
}
Ezek a módszerek szemantikailag egyenértékűek az IDebugHostFieldben található társaikkal. Az egyetlen különbség az, hogy a GetLocationKind metódus soha nem ad vissza LocationMember vagy LocationConstant értéket az ilyen szimbólumokhoz.
A GetLocationKind metódus a LocationKind enumerálásnak megfelelően adja vissza, hogy a szimbólum milyen helyen található. Az enumerálás leírása az IDebugHostField dokumentációjában található.
A címmel rendelkező adatok esetében a GetLocation metódus a mező absztrakt helyét (címét) adja vissza. Ha az adott nyilvános helyen nincs statikus hely, a GetLocation metódus sikertelen lesz.
modulaláírások és verzióegyezés: IDebugHostModuleSignature
A modul-aláírások azt jelzik, hogy egy adott modul megfelel-e az elnevezéssel és verziószámozással kapcsolatos feltételeknek. A modul aláírása az IDebugHostSymbols createModuleSignature metódusával jön létre. Megfelelhet a modul nevének és a modul verziószámainak választható tartományának. Az ilyen aláírás létrehozása után az ügyfél egy IDebugHostModuleSignature felületet kap, amely az alábbiak szerint van definiálva:
DECLARE_INTERFACE_(IDebugHostModuleSignature, IUnknown)
{
STDMETHOD(IsMatch)(_In_ IDebugHostModule* pModule, _Out_ bool* isMatch) PURE;
}
Az IsMatch metódus összehasonlít egy adott modult (egy IDebugHostModule szimbólum alapján) egy aláírással, és összehasonlítja a modul nevét és verzióját az aláírásban megadott névvel és verziótartománysal. Annak jelzése, hogy a megadott modulszimbólum megfelel-e az aláírásnak.
Írja be az aláírásokat és a típusegyezést: IDebugHostTypeSignature
A típus-aláírások azt jelzik, hogy egy adott típuspéldány megfelel-e a típus nevének, a típus általános argumentumainak és a típus moduljának egy halmazának. Az IDebugHostSymbols createTypeSignature metódusával létrejön egy típusaláírás. Az ilyen aláírás létrehozása után az ügyfél kap egy IDebugHostTypeSignature felületet, amely a következőképpen van definiálva:
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;
}
A GetHashCode metódus egy 32 bites kivonatkódot ad vissza a típusaláíráshoz. A hibakeresési gazdagép garantálja, hogy a implementáció szinkronizációt biztosít a típuspéldányokhoz visszaadott kivonatkód és a típusaláírásokhoz visszaadott kivonatkód között. A globális egyezés kivételével, ha egy típuspéldány képes megfeleltetni egy típusaláírást, mindkettő ugyanazzal a 32 bites kivonatkóddal fog rendelkezni. Ez lehetővé teszi a kezdeti gyors összehasonlítást és egyezést egy típuspéldány és az adatmodell-kezelőben regisztrált számos típusaadék között.
Az IsMatch metódus azt jelzi, hogy egy adott típuspéldány megfelel-e a típusaalásban megadott feltételeknek. Ha igen, akkor a rendszer egy enumerátor mellett egy enumerátort is visszaad, amely a típuspéldány összes konkrét részét (szimbólumként) jelzi, amelyek helyettesítő karaktereket egyeztetnek a típus-aláírásban.
A CompareAgainst metódus összehasonlítja a típus-aláírást egy másik típus-aláírással, és visszaadja a két aláírás összehasonlítását. A visszaadott összehasonlítási eredmény a SignatureComparison enumerálás tagja, amely a következőképpen van definiálva:
| Enumeráns | Értelmezés |
|---|---|
| Össze nem függő | Nincs kapcsolat az összehasonlítandó két aláírás vagy típus között. |
| Félreérthető | Az egyik aláírás vagy típus kétértelműen hasonlít a másikhoz. Két típusaadék esetében ez azt jelenti, hogy vannak olyan lehetséges típuspéldányok, amelyek mindkét aláírásnak egyformán megfelelhetnek. Például az alább látható két típusaadék nem egyértelmű. Signature 1: std::pair<*, int> Signature 2: std::pair<int,*>, mert a típuspéldány std::pair<int, int> egy egyenlően jól egyezik (mindkettő egy konkrét és egy helyettesítő karakter egyezés). |
| LessSpecific | Az egyik aláírás vagy típus kevésbé specifikus, mint a másik. Ez gyakran azt jelenti, hogy a kevésbé specifikus aláírás egy helyettesítő karakterrel rendelkezik, ahol a konkrétabbnak konkrét típusa van. Az alábbi első aláírás például kevésbé specifikus, mint a második. 1. aláírás: std::pair<*, int> 2. aláírás: std::pair<int, int>, mert helyettesítő karakterrel (a *) rendelkezik, ahol a második konkrét típussal (int) rendelkezik. |
| MoreSpecific | Az egyik aláírás vagy típus pontosabb, mint a másik. Ez gyakran azt jelenti, hogy a konkrétabb aláírás konkrét típussal rendelkezik, ahol a kevésbé specifikus egy helyettesítő karakterrel rendelkezik. Példaként az alábbi első aláírás pontosabb, mint a második. Signature 1: std::pair<int, int> Signature 2: std::pair<*, int>, mert egy konkrét típus (int), ahol a második egy helyettesítő karakter (a *). |
| Azonos | A két aláírás vagy típus azonos. |
Lásd még:
Ez a témakör egy olyan sorozat része, amely leírja a C++-ból elérhető felületeket, a C++ alapú hibakeresőbővítmények készítésének módját, valamint azt, hogy miként használhat más adatmodell-szerkezeteket (pl. JavaScript vagy NatVis) egy C++ adatmodell-bővítményből.
Hibakereső adatmodell C++ áttekintése
Hibakereső adatmodell C++ objektumai
Hibakereső adatmodell C++ további felületei