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 azt ismerteti, hogyan használhatók a Hibakereső adatmodell C++ objektumai, és hogyan bővíthetik a hibakereső képességeit.
Az alapvető hibakereső objektummodellje
Az adatmodell egyik legalapvetőbb, mégis leghatékonyabb tulajdonsága, hogy szabványosítja az objektum definícióját és az objektumokkal való interakciót. Az IModelObject felület egy objektum fogalmát foglalja magában – legyen szó akár egész számról, lebegőpontos értékről, sztringről, a hibakereső célcímterének valamilyen összetett típusáról, vagy valamilyen hibakeresői fogalomról, például egy folyamat vagy modul fogalmáról.
Az IModelObjectszámos különböző dolog tárolható (vagy be van jelölve):
belső értékek – Az IModelObject számos alaptípus tárolója lehet: 8, 16, 32 vagy 64 bites aláírt vagy aláíratlan egész számok, logikai értékek, sztringek, hibák vagy üres fogalmak.
natív objektumok – Az IModelObject egy összetett típust (a hibakereső típusrendszere által meghatározottak szerint) jelölhet annak címterén belül, amit a hibakereső céloz.
Szintetikus objektumok – Az IModelObject lehet dinamikus objektum – szótár, ha úgy kívánja: kulcs- és érték/metaadatok gyűjteménye, valamint fogalmak, amelyek olyan viselkedéseket határoznak meg, amelyeket nem egyszerűen kulcs/érték párok jelölnek.
Tulajdonságok – Egy IModelObject egy tulajdonságot jelölhet: olyasmit, amelynek értéke metódushívással kérhető le vagy módosítható. Az IModelObject tulajdonsága tulajdonképpen egy IModelPropertyAccessor felület, amely egy IModelObject
metódusok – Egy IModelObject jelölhet egy metódust: egy argumentumkészlettel hívható meg, és visszatérési értéket kaphat. Az IModelObject metódusa tulajdonképpen egy IModelMethod felület, amely egy IModelObject
Bővíthetőség az objektummodellen belül
Az IModelObject nem külön objektum. A fenti objektumtípusok egyikének ábrázolása mellett minden objektum a szülő adatmodellek láncának fogalmával rendelkezik. Ez a lánc úgy viselkedik, mint egy JavaScript-prototípuslánc. A JavaScripthez hasonló prototípusok lineáris lánca helyett minden adatmodell-objektum szülőmodellek lineáris láncát határozza meg. Mindegyik szülőmodell egy másik lineáris lánccal rendelkezik saját szülőkészletéből. Lényegében minden objektum önmagának és a fa minden objektumának képességeinek (tulajdonságainak stb.) összesítése. Egy adott tulajdonság lekérdezésekor, ha a lekérdezett objektum nem támogatja ezt a tulajdonságot, a lekérdezés lineáris sorrendben továbbítja az egyes szülőnek. Ez olyan viselkedést hoz létre, amelyben a tulajdonság keresését az összesítő fa első mélységi keresése oldja fel.
A bővíthetőség ebben az objektummodellben nagyon egyszerű, mivel ez a fogalma azt jelzi, hogy minden objektum önmagából és a szülőmodellek fájából áll. Egy bővítmény be tud jelentkezni, és felveheti magát egy másik objektum szülőmodelljeinek listájába. Ezzel a bővíti az objektumot. Ily módon bármihez hozzáadhat képességeket: egy objektum vagy érték egy adott példányát, egy natív típust, a hibakereső koncepcióját arról, hogy mi az a folyamat vagy szál, vagy akár a "minden iterálható objektum" fogalma.
Környezet, környezet és környezet: A ez a mutató, a címtér és a megvalósítási privát adatok
A környezeti három fogalma van, amelyek szükségesek az objektummodell kontextusának megértéséhez.
Környezet: A mutató
Mivel egy adott tulajdonság vagy metódus az adatmodellfa bármely szintjén implementálható, a metódus vagy tulajdonság implementálásához hozzá kell férnie az eredeti objektumhoz (ezt a mutatót a C++ vagy a JavaScript objektumának nevezheti. Ez a példányobjektum számos metódusnak lesz átadva, mint az első argumentum, amelyet környezetnek a leírt metódusokban.
Környezet: A címtér
Fontos megjegyezni, hogy a korábbi bővítménymodellekkel ellentétben, ahol környezeti (a megtekintett cél, folyamat, szál) egy olyan felhasználói felületi fogalom, amely az aktuális felhasználói felület állapotához képest minden API-t használ, az adatmodell-interfészek általában explicit módon vagy implicit módon használják ezt a környezetet IDebugHostContext felületként. Az adatmodellben minden IModelObject hordozza az ilyen típusú környezeti információkat, és propagálja ezt a környezetet az általa visszaadott objektumokra. Ez azt jelenti, hogy ha natív értéket vagy kulcsértéket olvas ki egy IModelObject, az kiolvassa a célból és a folyamatból, ahonnan az objektumot eredetileg beszerezték.
Van egy explicit állandó érték, USE_CURRENT_HOST_CONTEXT, amely átadható olyan metódusok számára, amelyek egy IDebugHostContext argumentumot vesznek fel. Ez az érték azt jelzi, hogy a környezetnek valóban a hibakereső aktuális felhasználói felületi állapotának kell lennie. Ennek a fogalmanak azonban explicitnek kell lennie.
Környezet: Privát adatok implementálása
Ne feledje, hogy az adatmodell minden objektuma valójában az objektumpéldány és a csatolt szülőmodellek fájának összesítése. Ezek a szülőmodellek (amelyek számos különböző objektum láncaiban csatolhatók) bármilyen példányobjektumhoz társíthatnak privát implementációs adatokat. A koncepcionálisan létrehozott IModelObject mindegyik rendelkezik egy kivonattáblával, amely egy adott szülőmodellből egy IUnknown-felület által meghatározott privát példányadatokra képez le. Ez lehetővé teszi, hogy a szülőmodell minden példányon gyorsítótárazza az adatokat, vagy más módon tetszőleges adatokkal rendelkezzen.
Ez a típusú környezet a GetContextForDataModel és SetContextForDataModel metóduson keresztül érhető el IModelObject.
Core Debugger Object Interface: IModelObject
Az IModelObject felület a következőképpen van definiálva:
DECLARE_INTERFACE_(IModelObject, IUnknown)
{
STDMETHOD(QueryInterface)(_In_ REFIID iid, _COM_Outptr_ PVOID* iface);
STDMETHOD_(ULONG, AddRef)();
STDMETHOD_(ULONG, Release)() PURE;
STDMETHOD(GetContext)(_COM_Outptr_result_maybenull_ IDebugHostContext** context) PURE;
STDMETHOD(GetKind)(_Out_ ModelObjectKind *kind) PURE;
STDMETHOD(GetIntrinsicValue)(_Out_ VARIANT* intrinsicData);
STDMETHOD(GetIntrinsicValueAs)(_In_ VARTYPE vt, _Out_ VARIANT* intrinsicData) PURE;
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_opt_ IModelObject* object) PURE;
STDMETHOD(EnumerateKeyValues)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(GetRawValue)(_In_ SymbolKind kind, _In_ PCWSTR name, _In_ ULONG searchFlags, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(EnumerateRawValues)(_In_ SymbolKind kind, _In_ ULONG searchFlags, _COM_Outptr_ IRawEnumerator** enumerator) PURE;
STDMETHOD(Dereference)(_COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(TryCastToRuntimeType)(_COM_Errorptr_ IModelObject** runtimeTypedObject) PURE;
STDMETHOD(GetConcept)(_In_ REFIID conceptId, _COM_Outptr_ IUnknown** conceptInterface, _COM_Outptr_opt_result_maybenull_ IKeyStore** conceptMetadata) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetTypeInfo)(_Out_ IDebugHostType** type) PURE;
STDMETHOD(GetTargetInfo)(_Out_ Location* location, _Out_ IDebugHostType** type) PURE;
STDMETHOD(GetNumberOfParentModels)(_Out_ ULONG64* numModels) PURE;
STDMETHOD(GetParentModel)(_In_ ULONG64 i, _COM_Outptr_ IModelObject **model, _COM_Outptr_result_maybenull_ IModelObject **contextObject) PURE;
STDMETHOD(AddParentModel)(_In_ IModelObject* model, _In_opt_ IModelObject* contextObject, _In_ bool override) PURE;
STDMETHOD(RemoveParentModel)(_In_ IModelObject* model) PURE;
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(GetKeyReference)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** objectReference, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(ClearKeys)() PURE;
STDMETHOD(EnumerateKeys)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(EnumerateKeyReferences)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(SetConcept)(_In_ REFIID conceptId, _In_ IUnknown* conceptInterface, _In_opt_ IKeyStore* conceptMetadata) PURE;
STDMETHOD(ClearConcepts)() PURE;
STDMETHOD(GetRawReference)(_In_ SymbolKind kind, _In_ PCWSTR name, _In_ ULONG searchFlags, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(EnumerateRawReferences)(_In_ SymbolKind kind, _In_ ULONG searchFlags, _COM_Outptr_ IRawEnumerator** enumerator) PURE;
STDMETHOD(SetContextForDataModel)(_In_ IModelObject* dataModelObject, _In_ IUnknown* context) PURE;
STDMETHOD(GetContextForDataModel)(_In_ IModelObject* dataModelObject, _Out_ IUnknown** context) PURE;
STDMETHOD(Compare)(_In_ IModelObject* other, _COM_Outptr_opt_result_maybenull_ IModelObject **ppResult) PURE;
STDMETHOD(IsEqualTo)(_In_ IModelObject* other, _Out_ bool* equal) PURE;
}
alapszintű metódusok
Az alábbiakban az IModelObject által képviselt bármilyen objektumra alkalmazható általános módszereket ismertetjük.
STDMETHOD(GetKind)(_Out_ ModelObjectKind *kind) PURE;
STDMETHOD(GetContext)(_COM_Outptr_result_maybenull_ IDebugHostContext** context) PURE;
STDMETHOD(GetIntrinsicValue)(_Out_ VARIANT* intrinsicData);
STDMETHOD(GetIntrinsicValueAs)(_In_ VARTYPE vt, _Out_ VARIANT* intrinsicData) PURE;
STDMETHOD(Compare)(_In_ IModelObject* other, _COM_Outptr_opt_result_maybenull_ IModelObject **ppResult) PURE;
STDMETHOD(IsEqualTo)(_In_ IModelObject* other, _Out_ bool* equal) PURE;
STDMETHOD(Dereference)(_COM_Errorptr_ IModelObject** object) PURE;
A GetKind metódus visszaadja, hogy milyen típusú objektum van beállítva az IModelObjectben.
A GetContext metódus az objektumhoz társított gazdagépkörnyezetet adja vissza.
A GetIntrinsicValue metódus visszaadja azt a dolgot, amely egy IModelObjectben van bekeretezve. Ez a módszer jogilag csak olyan IModelObject interfészeken hívható meg, amelyek egy dobozos belső vagy egy dobozolt felületet jelölnek. Natív objektumokra, értékobjektumokra, szintetikus objektumokra és referenciaobjektumokra nem hívható meg. A GetIntrinsicValueAs metódus ugyanúgy viselkedik, mint a GetIntrinsicValue metódus, azzal a kivételével, hogy az értéket a megadott változattípusra konvertálja. Ha az átalakítás nem hajtható végre, a metódus hibát ad vissza.
Az IsEqualTo metódus két modellobjektumot hasonlít össze, és visszaadja, hogy azok értéke megegyezik-e. A rendezéssel rendelkező objektumok esetében az igaz értéket visszaadó metódus egyenértékű a 0-t visszaadó Compare metódussal. Az olyan objektumok esetében, amelyek nem rendelkeznek rendezéssel, de egyenértékűek, a Compare metódus sikertelen lesz, de ez nem fog. Az értékalapú összehasonlítás jelentését az objektum típusa határozza meg. Jelenleg ez csak belső típusok és hibaobjektumok esetén van definiálva. Az egyenértékűségnek nincs aktuális adatmodell-fogalma.
A Dereference metódus egy objektumot késleltet. Ez a módszer adatmodell-alapú referencia (ObjectTargetObjectReference, ObjectKeyReference) vagy natív nyelvi referencia (mutató vagy nyelvi hivatkozás) elhalasztására használható. Fontos megjegyezni, hogy ez a módszer egyetlen szintű hivatkozási szemantikát távolít el az objektumon. Teljes mértékben lehetséges például, hogy egy adatmodell egy nyelvi hivatkozásra hivatkozzon. Ilyen esetben a Dereference metódus első meghívása eltávolítaná az adatmodell-hivatkozást, és elhagyná a nyelvi referenciát. Az eredményül kapott objektumra vonatkozó dereferencia meghívása ezt követően eltávolítja a nyelvi hivatkozást, és visszaadja a hivatkozás alatt lévő natív értéket.
kulcsmanipulációs módszerek
Minden olyan szintetikus objektum, amely a kulcsok, értékek és metaadatok szótára, számos metódussal rendelkezik a kulcsok, értékek és a hozzájuk társított metaadatok kezelésére.
Az API-k értékalapú formái a következők:
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_opt_ IModelObject* object) PURE;
STDMETHOD(EnumerateKeyValues)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
The key based forms of the APIs (including those used for key creation) are:
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(EnumerateKeys)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(ClearKeys)() PURE;
Az API-k referenciaalapú formái a következők:
STDMETHOD(GetKeyReference)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** objectReference, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(EnumerateKeyReferences)(_COM_Outptr_ IKeyEnumerator** enumerator) PURE;
A GetKeyValue metódus az első módszer, amelyhez az ügyfél fordul, hogy név alapján lekérje egy adott kulcs értékét (és a hozzájuk társított metaadatokat). Ha a kulcs tulajdonság-tartozék – vagyis IModelObject érték, amely egy dobozos IModelPropertyAccessor, a GetKeyValue metódus automatikusan meghívja a tulajdonság-tartozék GetValue metódusát a tényleges érték lekéréséhez.
A SetKeyValue metódus az első metódus, amelyre az ügyfél a kulcs értékének beállításához fordul. Ez a módszer nem használható új kulcs létrehozására egy objektumon. Csak egy meglévő kulcs értékét állítja be. Vegye figyelembe, hogy számos kulcs írásvédett (például egy tulajdonságkiegészítő implementálja őket, amely a SetValue metódusból E_NOT_IMPL ad vissza). Ez a metódus sikertelen lesz, ha csak olvasási kulcsot hív meg.
Az EnumerateKeyValues metódus az első módszer, ahová az ügyfél az objektum összes kulcsának számbavételéhez fordul (ez magában foglalja a szülőmodellek fájában bárhol implementált összes kulcsot). Fontos megjegyezni, hogy az EnumerateKeyValues az objektumfa ismétlődő nevei által definiált kulcsokat számba veszi; azonban - az olyan metódusok, mint a GetKeyValue és a SetKeyValue, csak a megadott névvel rendelkező kulcs első példányát módosítják a mélységi első bejárás által felfedezett módon.
A GetKey metódus név alapján lekéri egy adott kulcs értékét (és a hozzájuk társított metaadatokat). A legtöbb ügyfélnek inkább a GetKeyValue metódust kell használnia. Ha a kulcs tulajdonságkiegészítő, a metódus meghívásával visszaadja az IModelObjectbe bekeretezett tulajdonságkiegészítőt (IModelPropertyAccessor interfészt). A GetKeyValue metódussal ellentétben ez a metódus nem oldja fel automatikusan a kulcs mögöttes értékét a GetValue metódus meghívásával. Ez a felelősség a hívóé.
A SetKey metódus az a metódus, amellyel az ügyfél kulcsokat hozhat létre egy objektumon (és metaadatokat társíthat a létrehozott kulccsal). Ha egy adott objektum már rendelkezik a megadott névvel rendelkező kulccsal, két viselkedés egyike következik be. Ha a kulcs az általa megadott példányon található, a rendszer úgy cseréli le a kulcs értékét, mintha az eredeti kulcs nem létezett volna. Ha viszont a kulcs az általa adott példány szülőadatmodelljeinek láncában van, akkor a megadott példányon létrejön egy új, a megadott névvel ellátott kulcs. Ez tulajdonképpen azt eredményezné, hogy az objektum két azonos nevű kulcssal rendelkezik (hasonló egy származtatott osztályhoz, amely az alaposztályhoz hasonló nevű tagot árnyékolt).
Az EnumerateKeys metódus az EnumerateKeyValues metódushoz hasonlóan viselkedik, azzal a kivételével, hogy nem oldja fel automatikusan az objektum tulajdonságtartozékait. Ez azt jelenti, hogy ha egy kulcs értéke tulajdonság-tartozék, az EnumerateKeys metódus a GetValue metódus automatikus meghívása helyett az IModelPropertyAccessorInterface tulajdonság-tartozékot (IModelPropertyAccessorInterface) adja vissza. Ez hasonló a GetKey és a GetKeyValue közötti különbséghez.
A ClearKeys metódus eltávolítja az összes kulcsot és azok társított értékeit és metaadatait az objektum ezen által megadott példányából. Ez a módszer nincs hatással az adott objektumpéldányhoz csatolt szülőmodellekre.
A GetKeyReference metódus megkeresi az objektumon (vagy annak szülőmodell-láncán) található adott név kulcsát, és egy IModelKeyReference felület által megadott, egy IModelObjectbe bekeretezett kulcsra mutató hivatkozást ad vissza. Ez a hivatkozás később használható a kulcs értékének lekérésére vagy beállítására.
Az EnumerateKeyReferences metódus az EnumerateKeyValues metódushoz hasonlóan viselkedik, azzal a kivételrel, hogy a kulcs értéke helyett az enumerált kulcsokra mutató hivatkozásokat ad vissza (egy IModelKeyReference-illesztő által egy IModelObject-be bekeretezve). Ezek a hivatkozások a kulcsok mögöttes értékének lekérésére vagy beállítására használhatók.
koncepciómanipulációs módszerek
Amellett, hogy a modellobjektum kulcs-/érték-/metaadatok szótára, fogalmak tárolója is. A fogalmak olyan absztraktak, amelyeket egy objektumon vagy egy objektumon lehet végrehajtani. A fogalmak lényegében az objektumok által támogatott interfészek dinamikus tárházai. Az adatmodell ma számos fogalmat határoz meg:
| Concept Interface | Leírás |
|---|---|
| IDataModelConcept | A koncepció egy szülőmodell. Ha ez a modell automatikusan csatlakozik egy natív típushoz egy regisztrált típuskódon keresztül, a rendszer automatikusan meghívja az InitializeObject metódust minden alkalommal, amikor egy ilyen típusú új objektumot példányosít. |
| IStringDisplayableConcept | Az objektum megjelenítendő sztringgé alakítható. |
| IIterableConcept | Az objektum egy tároló, és iterálható. |
| IIndexableConcept | Az objektum egy tároló, amely egy vagy több dimenzióban indexelhető (véletlenszerű hozzáféréssel érhető el). |
| IPreferredRuntimeTypeConcept | Az objektum többet tud az abból származtatott típusokról, mint amennyit az alapul szolgáló típusrendszer képes biztosítani, és szeretné kezelni a saját statikusról futásidejű típusra való konvertálását. |
| IDynamicKeyProviderConcept | Az objektum a kulcsok dinamikus szolgáltatója, és szeretné átvenni az összes kulcslekérdezéseket az alapvető adatmodellből. Ezt a felületet általában a dinamikus nyelvek, például a JavaScript hidaként használják. |
| IDynamicConceptProviderConcept | Az objektum a fogalmak dinamikus szolgáltatója, és szeretné átvenni az összes fogalom-lekérdezést az alapvető adatmodellből. Ezt a felületet általában a dinamikus nyelvek, például a JavaScript hidaként használják. |
Az IModelObject következő metódusai az objektumok által támogatott fogalmak kezelésére használhatók.
STDMETHOD(GetConcept)(_In_ REFIID conceptId, _COM_Outptr_ IUnknown** conceptInterface, _COM_Outptr_opt_result_maybenull_ IKeyStore** conceptMetadata) PURE;
STDMETHOD(SetConcept)(_In_ REFIID conceptId, _In_ IUnknown* conceptInterface, _In_opt_ IKeyStore* conceptMetadata) PURE;
STDMETHOD(ClearConcepts)() PURE;
A GetConcept metódus megkeres egy fogalmat az objektumon (vagy annak szülőmodell-láncán), és visszaad egy interfészmutatót a koncepció felületére. A koncepciófelület viselkedése és módszerei az egyes fogalmakra vonatkoznak. Fontos azonban megjegyezni, hogy a koncepciófelületek nagy része megköveteli, hogy a hívó explicit módon adja át a környezeti objektumot (vagy azt, amit hagyományosan ezt a mutatót nevezik). Fontos meggyőződni arról, hogy a megfelelő környezeti objektum minden koncepciófelületre át lesz adva.
A SetConcept metódus egy meghatározott fogalmat helyez el az egérmutató által megadott objektumpéldányon. Ha az általa megadott objektumpéldányhoz csatolt szülőmodell is támogatja a koncepciót, a példány implementációja felülbírálja a szülőmodellben lévőt.
A ClearConcepts metódus eltávolítja az összes fogalmat az általa megadott objektumpéldányból.
natív objektummetódusok
Bár számos modellobjektum belső konstrukciókra (például egész számokra, sztringekre) vagy szintetikus szerkezetekre (kulcs-/érték-/metaadatok és fogalmak szótára) hivatkozik, a modellobjektumok natív szerkezetre is hivatkozhatnak (például egy felhasználó által definiált típusra a hibakeresési cél címterében). Az IModelObject felület számos metódussal rendelkezik rajta, amelyek hozzáférnek az ilyen natív objektumok információihoz. Ezek a módszerek a következők:
STDMETHOD(GetRawValue)(_In_ SymbolKind kind, _In_ PCWSTR name, _In_ ULONG searchFlags, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(EnumerateRawValues)(_In_ SymbolKind kind, _In_ ULONG searchFlags, _COM_Outptr_ IRawEnumerator** enumerator) PURE;
STDMETHOD(TryCastToRuntimeType)(_COM_Errorptr_ IModelObject** runtimeTypedObject) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetTypeInfo)(_Out_ IDebugHostType** type) PURE;
STDMETHOD(GetTargetInfo)(_Out_ Location* location, _Out_ IDebugHostType** type) PURE;
STDMETHOD(GetRawReference)(_In_ SymbolKind kind, _In_ PCWSTR name, _In_ ULONG searchFlags, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(EnumerateRawReferences)(_In_ SymbolKind kind, _In_ ULONG searchFlags, _COM_Outptr_ IRawEnumerator** enumerator) PURE;
A GetRawValue metódus egy natív szerkezetet keres az adott objektumon belül. Ilyen szerkezet lehet mező, alaposztály, alaposztály mezője, tagfüggvény stb.
Az EnumerateRawValues metódus az adott objektum összes natív gyermekét (például mezőket, alaposztályokat stb.) sorolja fel.
A TryCastToRuntimeType metódus megkéri a hibakereső gazdagépet, hogy végezzen elemzést, és határozza meg az adott objektum tényleges futtatókörnyezettípusát (például a legtöbb származtatott osztályt). A használt pontos elemzés a hibakeresési gazdagépre vonatkozik, és tartalmazhat RTTI-t (C++ futási idő típusinformációkat), az objektum V-Table(virtuális függvénytáblázat) szerkezetének vizsgálatát, vagy bármely más eszközt, amellyel a gazdagép megbízhatóan meghatározhatja a dinamikus/futásidejű típust a statikus típusból. A futtatókörnyezet-típusra való konvertálás sikertelensége nem jelenti azt, hogy ez a metódushívás sikertelen lesz. Ilyen esetekben a metódus visszaadja az adott objektumot (a mutatót) a kimeneti argumentumban.
A GetLocation metódus visszaadja a natív objektum helyét. Bár egy ilyen hely általában egy virtuális cím a hibakeresési cél címterén belül, ez nem feltétlenül így van. A metódus által visszaadott hely egy absztrakt hely, amely lehet egy virtuális cím, jelezheti a regisztráción vagy alregisztráláson belüli elhelyezést, vagy jelezhet a hibakeresési gazdagép által meghatározott egyéb tetszőleges címteret. Ha az eredményül kapott Hely objektum HostDefined mezője 0, az azt jelzi, hogy a hely valójában egy virtuális cím. Az ilyen virtuális cím lekérhető az eredményként kapott hely Eltolás mezőjének vizsgálatával. A HostDefined mező nem nulla értéke egy másodlagos címteret jelöl, ahol az Eltolás mező az eltolás az adott címtéren belül. A nem nulla HostDefined értékek pontos jelentése itt privát a hibakeresési gazdagép számára.
A GetTypeInfo metódus az adott objektum natív típusát adja vissza. Ha az objektumhoz nincs natív típusú információ társítva (például: belső információ, stb.), a hívás továbbra is sikeres lesz, de null értéket ad vissza.
A GetTargetInfo metódus gyakorlatilag a GetLocation és a GetTypeInfo metódus kombinációja, amely az adott objektum absztrakt helyét és natív típusát is visszaadja.
A GetRawReference metódus megkeres egy natív szerkezetet az adott objektumon belül, és visszaad egy rá mutató hivatkozást. Ilyen szerkezet lehet mező, alaposztály, alaposztály mezője, tagfüggvény stb. Fontos megkülönböztetni az itt visszaadott hivatkozást (az ObjectTargetObjectReference típusú objektumot) egy nyelvi hivatkozástól (például egy C++ & vagy && stílushivatkozástól).
Az EnumerateRawReferences metódus az adott objektum összes natív gyermekére (például mezőkre, alaposztályokra stb.) hivatkozik.
bővíthetőségi módszerek
A korábban leírtak szerint a modellobjektumok nagyon hasonlóak egy JavaScript-objektumhoz és annak prototípusláncához. Az adott IModelObject felület által képviselt példányon kívül tetszőleges számú szülőmodell is csatolható az objektumhoz (amelyek mindegyike tetszőleges számú szülőmodellt csatolhat hozzájuk). Ez az adatmodellen belüli bővíthetőség elsődleges eszköze. Ha egy adott tulajdonság vagy fogalom nem található egy adott példányon belül, a rendszer a példányon gyökerező objektumfát (a szülőmodellek által definiált) részletes első keresést hajtja végre.
Az alábbi módszerek egy adott IModelObject-példányhoz társított szülőmodellek láncát módosítják:
STDMETHOD(GetNumberOfParentModels)(_Out_ ULONG64* numModels) PURE;
STDMETHOD(GetParentModel)(_In_ ULONG64 i, _COM_Outptr_ IModelObject **model, _COM_Outptr_result_maybenull_ IModelObject **contextObject) PURE;
STDMETHOD(AddParentModel)(_In_ IModelObject* model, _In_opt_ IModelObject* contextObject, _In_ bool override) PURE;
STDMETHOD(RemoveParentModel)(_In_ IModelObject* model) PURE;
STDMETHOD(SetContextForDataModel)(_In_ IModelObject* dataModelObject, _In_ IUnknown* context) PURE;
STDMETHOD(GetContextForDataModel)(_In_ IModelObject* dataModelObject, _Out_ IUnknown** context) PURE;
A GetNumberOfParentModels metódus az adott objektumpéldányhoz csatolt szülőmodellek számát adja vissza. A szülőmodellek a tulajdonságok mélységét keresik először a szülőmodelllánc lineáris sorrendjében.
A GetParentModel metódus az i-edik szülőmodellt adja vissza az adott objektum szülőmodell-láncában. A szülőmodellek lineáris sorrendben keresnek egy tulajdonságot vagy fogalmat. Az i indexet tartalmazó szülőmodellt a rendszer (hierarchikusan) az i + 1 indexű szülőmodell előtt keresi.
Az AddParentModel metódus új szülőmodellt ad hozzá az adott objektumhoz. Ilyen modell hozzáadható a keresési lánc végén (a felülbírálási argumentum hamisként van megadva), vagy a keresési lánc elején (a felülbírálási argumentum igazként van megadva). Emellett az egyes szülőmodellek igény szerint módosíthatják az adott szülő bármely tulajdonságának vagy koncepciójának (vagy a szülőhierarchiában lévő bárkinek) a környezetét (a szemantikai mutatót). A környezetbeállítást ritkán használják, de lehetővé teszi olyan hatékony fogalmak használatát, mint az objektumok beágyazása, a névterek létrehozása stb.
A RemoveParentModel eltávolít egy adott szülőmodellt az adott objektum szülő keresési láncából.
A SetContextForDataModel metódust egy adatmodell implementációja használja a megvalósítási adatok példányobjektumokon való elhelyezéséhez. Elméletileg minden IModelObject (ezt a példányt egyszerűség kedvéért nevezik) tartalmaz egy kivonatos állapottáblát. A kivonattáblát egy másik IModelObject indexeli (az egyszerűség kedvéért ezt nevezik adatmodellnek), amely a példány szülőmodell-hierarchiájában található. Az ebben a kivonatban található érték egy IUnknown-példány által képviselt hivatkozásszámozott állapotinformációk halmaza. Miután az adatmodell beállította ezt az állapotot a példányon, tetszőleges implementációs adatokat tárolhat, amelyek a tulajdonságlekérdezések során lekérhetők.
A GetContextForDataModel metódus a SetContextForDataModel korábbi hívásával beállított környezeti információk lekérésére szolgál. Ez lekéri azokat az állapotinformációkat, amelyeket egy adatmodell állított be a példányobjektum szülőmodell-hierarchiájában. Erről a környezetről/állapotról és jelentéséről további információt a SetContextForDataModel dokumentációjában talál.
hibakereső adatmodell alapvető objektumtípusai
Az adatmodell egy objektuma hasonló a .NET objektum fogalmához. Ez az az általános tároló, amelybe az adatmodell által megértett szerkezetet lehet bekereteztetni. A natív objektumok és a szintetikus (dinamikus) objektumok mellett több alapvető objektumtípus is létezik, amelyek az IModelObject tárolójába helyezhetők (vagy dobozosak). A tároló, amelyben a legtöbb érték elhelyezve van, egy szabványos COM/OLE VARIANT, amely számos további korlátozást tartalmaz arra, hogy a VARIANT mit tartalmazhat. Ezek legalapvetőbb típusai a következők:
- 8 bites aláíratlan és aláírt értékek (VT_UI1, VT_I1)
- 16 bites aláíratlan és aláírt értékek (VT_UI2, VT_UI2)
- 32 bites aláíratlan és aláírt értékek (VT_UI4, VT_I4)
- 64 bites aláíratlan és aláírt értékek (VT_UI8, VT_I8)
- Egy- és dupla pontosságú lebegőpontos értékek (VT_R4, VT_R8)
- Sztringek (VT_BSTR)
- Logikai értékek (VT_BOOL)
Ezeken az alaptípusokon kívül számos alapvető adatmodell-objektumot helyez el a VT_UNKNOWN által meghatározott IModelObjectbe, ahol a tárolt IUnknown garantáltan implementál egy adott felületet. Ezek a típusok a következők:
- Tulajdonságkiegészítők (IModelPropertyAccessor)
- Metódusobjektumok (IModelMethod)
- Kulcshivatkozási objektumok (IModelKeyReference vagy IModelKeyReference2)
- Környezeti objektumok (IDebugModelHostContext)
tulajdonságkiegészítők: IModelPropertyAccessor
Az adatmodell egyik tulajdonságeleme az IModelPropertyAccessor felület implementációja, amely egy IModelObjectbe van bekeretezve. A modellobjektum lekérdezéskor egyfajta ObjectPropertyAccessor típusú objektumot ad vissza, a belső érték pedig egy VT_UNKNOWN, amely garantáltan lekérdezhető az IModelPropertyAccessor esetében. A folyamat során az IModelPropertyAccessor számára garantáltan statikusan öntött.
A tulajdonságkiegészítők közvetett módon kaphatnak metódushívást az adatmodell kulcsértékének lekéréséhez és beállításához. Ha egy adott kulcs értéke tulajdonságtartománs, a GetKeyValue és a SetKeyValue metódus automatikusan észleli ezt, és szükség szerint meghívja a tulajdonság-tartozék mögöttes GetValue vagy SetValue metódusát.
Az IModelPropertyAccessor interfész a következőképpen van definiálva:
DECLARE_INTERFACE_(IModelPropertyAccessor, IUnknown)
{
STDMETHOD(GetValue)(_In_ PCWSTR key, _In_opt_ IModelObject* contextObject, _COM_Outptr_ IModelObject** value) PURE;
STDMETHOD(SetValue)(_In_ PCWSTR key, _In_opt_ IModelObject* contextObject, _In_ IModelObject* value) PURE;
}
A GetValue metódus a tulajdonság tartozékának lekérése. Ezt akkor hívják meg, ha egy ügyfél le szeretné kérni a tulajdonság mögöttes értékét. Vegye figyelembe, hogy minden olyan hívó, aki közvetlenül kap egy tulajdonság-tartozékot, felelős azért, hogy átadja a kulcsnevet és a pontos példányobjektumot (ez a mutató) a tulajdonság-tartozék GetValue metódusának.
A SetValue metódus a tulajdonság tartozékának beállítója. A rendszer akkor hívja meg, ha egy ügyfél értéket szeretne hozzárendelni a mögöttes tulajdonsághoz. Számos tulajdonság írásvédett. Ilyen esetekben a SetValue metódus meghívása E_NOTIMPL ad vissza. Vegye figyelembe, hogy minden olyan hívó, aki közvetlenül kap egy tulajdonság-tartozékot, felelős azért, hogy átadja a kulcsnevet és a pontos példányobjektumot (ez a mutató) a tulajdonság-tartozék SetValue metódusának.
metódusok: IModelMethod
Az adatmodell egyik metódusa az IModelMethod felület implementációja, amely egy IModelObjectbe van bekeretezve. A modellobjektum lekérdezéskor egyfajta ObjectMethod értéket ad vissza, a belső érték pedig egy VT_UNKNOWN, amely garantáltan lekérdezhető az IModelMethod esetében. A folyamat során garantáltan statikusan öntött az IModelMethod. Az adatmodell minden metódusa dinamikus jellegű. Bemenetként 0 vagy több argumentumot vesznek fel, és egyetlen kimeneti értéket adnak vissza. Nincs túlterhelésfeloldás, és nincsenek metaadatok a paraméterek nevével, típusával vagy elvárásaival kapcsolatban.
Az IModelMethod interfész a következőképpen van definiálva:
DECLARE_INTERFACE_(IModelMethod, IUnknown)
{
STDMETHOD(Call)(_In_opt_ IModelObject *pContextObject, _In_ ULONG64 argCount, _In_reads_(argCount) IModelObject **ppArguments, _COM_Errorptr_ IModelObject **ppResult, _COM_Outptr_opt_result_maybenull_ IKeyStore **ppMetadata) PURE;
}
A Hívás metódus az adatmodellben definiált metódus meghívásának módja. A hívó feladata egy pontos példányobjektum (ez a mutató) és egy tetszőleges argumentumkészlet átadása. A metódus eredménye és az eredményhez társított esetleges metaadatok lesznek visszaadva. Azok a metódusok, amelyek nem adnak vissza logikailag értéket, továbbra is érvényes IModelObject értéket kell visszaadni. Ilyen esetben az IModelObject egy dobozos nincs érték. Ha egy metódus meghibásodik, előfordulhat, hogy kiterjesztett hibainformációkat ad vissza a bemeneti argumentumban (még akkor is, ha a visszaadott HRESULT hiba). Fontos, hogy a hívók ezt ellenőrizzék.
kulcshivatkozások: IModelKeyReference vagy IModelKeyReference2
A kulcshivatkozás lényegében egy adott objektum kulcsára mutató fogópont. Az ügyfél lekérheti az ilyen leírót olyan metódusokkal, mint a GetKeyReference, és később a fogópont használatával lekérheti vagy beállíthatja a kulcs értékét anélkül, hogy az eredeti objektumhoz tartana. Ez az objektumtípus az IModelKeyReference vagy az IModelKeyReference2 felület implementációja, amely egy IModelObjectbe van bekeretezve. A modellobjektum egyfajta ObjectKeyReference-t ad vissza a lekérdezéskor, majd a belső érték egy VT_UNKNOWN, amely garantáltan lekérdezhető az IModelKeyReference esetében. A folyamat során az IModelKeyReference számára garantáltan statikusan öntött.
A fő referencia-felület a következőképpen van definiálva:
DECLARE_INTERFACE_(IModelKeyReference2, IModelKeyReference)
{
STDMETHOD(GetKeyName)(_Out_ BSTR* keyName) PURE;
STDMETHOD(GetOriginalObject)(_COM_Outptr_ IModelObject** originalObject) PURE;
STDMETHOD(GetContextObject)(_COM_Outptr_ IModelObject** containingObject) PURE;
STDMETHOD(GetKey)(_COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(GetKeyValue)(_COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ IModelObject* object) PURE;
STDMETHOD(OverrideContextObject)(_In_ IModelObject* newContextObject) PURE;
}
A GetKeyName metódus annak a kulcsnak a nevét adja vissza, amelyre ez a kulcshivatkozás egy leíró. A visszaadott sztring egy standard BSTR, amelyet a SysFreeString hívásával kell felszabadítani.
A GetOriginalObject metódus azt a példányobjektumot adja vissza, amelyből a kulcshivatkozás létrejött. Vegye figyelembe, hogy a kulcs maga is a példányobjektum szülőmodelljén lehet.
A GetContextObject metódus visszaadja a környezetet (ezt a mutatót), amelyet a rendszer átad egy tulajdonság-tartozék GetValue vagy SetValue metódusának, ha a kérdéses kulcs egy tulajdonság-tartozékra hivatkozik. Előfordulhat, hogy az itt visszaadott környezeti objektum megegyezik a GetOriginalObjectből lekért eredeti objektummal. Ha egy kulcs egy szülőmodellen van, és a szülőmodellhez van egy környezetbeállító társítva, az eredeti objektum az a példányobjektum, amelyen a GetKeyReference vagy az EnumerateKeyReferences meghívása történt. A környezeti objektum az lenne, ami az eredeti objektum és a szülőmodell közötti végső környezeti beállításból jön ki, amely tartalmazza azt a kulcsot, amelyre ez a kulcshivatkozás egy leíró. Ha nincsenek környezetigazítók, az eredeti objektum és a környezetobjektum azonos.
A kulcshivatkozások GetKey metódusa úgy viselkedik, mint az IModelObject GetKey metódusa. Visszaadja a mögöttes kulcs értékét és a kulcshoz társított metaadatokat. Ha a kulcs értéke egy tulajdonsághoz tartozó tartozék, akkor ez visszaadja az IModelObjectbe bekeretezett tulajdonság-tartozékot (IModelPropertyAccessor). Ez a metódus nem hívja meg a tulajdonság-tartozék mögöttes GetValue vagy SetValue metódusát.
Egy kulcshivatkozás GetKeyValue metódusa úgy viselkedik, mint az IModelObject GetKeyValue metódusa. Visszaadja a mögöttes kulcs értékét és a kulcshoz társított metaadatokat. Ha a kulcs értéke egy tulajdonság tartozéka, akkor ez automatikusan meghívja az alapul szolgáló GetValue metódust a tulajdonság-tartozékon.
A kulcshivatkozások SetKey metódusa úgy viselkedik, mint az IModelObject SetKey metódusa. Hozzárendeli a kulcs értékét. Ha az eredeti kulcs tulajdonságkiegészítő volt, akkor ez helyettesíti a tulajdonság tartozékát. Nem hívja meg a SetValue metódust a tulajdonság tartozékán.
Egy kulcshivatkozás SetKeyValue metódusa úgy viselkedik, mint az IModelObject SetKeyValue metódusa. Hozzárendeli a kulcs értékét. Ha az eredeti kulcs tulajdonságkiegészítő volt, akkor a tulajdonság tartozéka helyett a mögöttes SetValue metódust fogja meghívni.
A OverrideContextObject metódus (csak az IModelKeyReference2-en található) egy speciális módszer, amellyel véglegesen módosíthatja azt a környezeti objektumot, amelyet ez a kulcshivatkozás minden mögöttes tulajdonságelem GetValue vagy SetValue metódusainak átad. A metódusnak átadott objektumot a GetContextObject hívása is visszaadja. Ezt a metódust a szkriptszolgáltatók bizonyos dinamikus nyelvi viselkedések replikálására használhatják. A legtöbb ügyfél nem hívhatja ezt a metódust.
környezeti objektumok: IDebugHostContext
A környezeti objektumok átlátszatlan információblobok, amelyeket a hibakereső gazdagép (az adatmodellel együttműködve) társít minden objektumhoz. Tartalmazhat olyan dolgokat, mint a folyamatkörnyezet vagy a címtér, amelyből az információ származik, stb. A környezeti objektum az IDebugHostContext implementációja, amely egy IModelObjecten belül van bekeretezve. Vegye figyelembe, hogy az IDebugHostContext egy gazdagép által definiált felület. Az ügyfél soha nem fogja implementálni ezt a felületet.
A környezeti objektumokkal kapcsolatos további információkért lásd Hibakereső adatmodell C++ gazdagépfelületei a Hibakereső adatmodell C++ interfészeiben.
Data Model Manager
Az adatmodell-kezelő, az IDataModelManager2 (vagy a korábbi IDataModelManager) alapvető felülete a következőképpen van definiálva:
DECLARE_INTERFACE_(IDataModelManager2, IDataModelManager)
{
//
// IDataModelManager:
//
STDMETHOD(Close)() PURE;
STDMETHOD(CreateNoValue)(_Out_ IModelObject** object) PURE;
STDMETHOD(CreateErrorObject)(_In_ HRESULT hrError, _In_opt_ PCWSTR pwszMessage, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedObject)(_In_opt_ IDebugHostContext* context, _In_ Location objectLocation, _In_ IDebugHostType* objectType, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedObjectReference)(_In_opt_ IDebugHostContext* context, _In_ Location objectLocation, _In_ IDebugHostType* objectType, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(CreateSyntheticObject)(_In_opt_ IDebugHostContext* context, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateDataModelObject)(_In_ IDataModelConcept* dataModel, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateIntrinsicObject)(_In_ ModelObjectKind objectKind, _In_ VARIANT* intrinsicData, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedIntrinsicObject)(_In_ VARIANT* intrinsicData, _In_ IDebugHostType* type, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(GetModelForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _Out_ IModelObject** dataModel) PURE;
STDMETHOD(GetModelForType)(_In_ IDebugHostType* type, _COM_Outptr_ IModelObject** dataModel, _COM_Outptr_opt_ IDebugHostTypeSignature** typeSignature, _COM_Outptr_opt_ IDebugHostSymbolEnumerator** wildcardMatches) PURE;
STDMETHOD(RegisterModelForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _In_ IModelObject* dataModel) PURE;
STDMETHOD(UnregisterModelForTypeSignature)(_In_ IModelObject* dataModel, _In_opt_ IDebugHostTypeSignature* typeSignature) PURE;
STDMETHOD(RegisterExtensionForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _In_ IModelObject* dataModel) PURE;
STDMETHOD(UnregisterExtensionForTypeSignature)(_In_ IModelObject* dataModel, _In_opt_ IDebugHostTypeSignature* typeSignature) PURE;
STDMETHOD(CreateMetadataStore)(_In_opt_ IKeyStore* parentStore, _COM_Outptr_ IKeyStore** metadataStore) PURE;
STDMETHOD(GetRootNamespace)(_COM_Outptr_ IModelObject** rootNamespace) PURE;
STDMETHOD(RegisterNamedModel)(_In_ PCWSTR modelName, _In_ IModelObject *modeObject) PURE;
STDMETHOD(UnregisterNamedModel)(_In_ PCWSTR modelName) PURE;
STDMETHOD(AcquireNamedModel)(_In_ PCWSTR modelName, _COM_Outptr_ IModelObject **modelObject) PURE;
//
// IDataModelManager2:
//
STDMETHOD(AcquireSubNamespace)(_In_ PCWSTR modelName, _In_ PCWSTR subNamespaceModelName, _In_ PCWSTR accessName, _In_opt_ IKeyStore *metadata, _COM_Outptr_ IModelObject **namespaceModelObject) PURE;
STDMETHOD(CreateTypedIntrinsicObjectEx)(_In_opt_ IDebugHostContext* context, _In_ VARIANT* intrinsicData, _In_ IDebugHostType* type, _COM_Outptr_ IModelObject** object) PURE;
}
felügyeleti módszerek
Az adatmodellt üzemeltető alkalmazás (például hibakereső) a következő módszereket használja.
STDMETHOD(Close)() PURE;
A Bezárás metódust az adatmodell-kezelőt üzemeltető alkalmazás (például hibakereső) hívja meg az adatmodell-kezelő leállítási folyamatának elindításához. Az adatmodell olyan gazdagépe, amely nem a Close metódus, mielőtt végleges referenciát adna az adatmodell-kezelőre, meghatározatlan viselkedést okozhat, beleértve, de nem kizárólagosan az adatmodell felügyeleti infrastruktúrájának jelentős szivárgását.
objektumlétrehozási/boxelési módszerek
Az alábbi metóduskészlettel új objektumokat hozhat létre, vagy értékeket állíthat be egy IModelObjectbe – ez az adatmodell alapvető felülete.
STDMETHOD(CreateNoValue)(_Out_ IModelObject** object) PURE;
STDMETHOD(CreateErrorObject)(_In_ HRESULT hrError, _In_opt_ PCWSTR pwszMessage, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedObject)(_In_opt_ IDebugHostContext* context, _In_ Location objectLocation, _In_ IDebugHostType* objectType, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedObjectReference)(_In_opt_ IDebugHostContext* context, _In_ Location objectLocation, _In_ IDebugHostType* objectType, _COM_Errorptr_ IModelObject** object) PURE;
STDMETHOD(CreateSyntheticObject)(_In_opt_ IDebugHostContext* context, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateDataModelObject)(_In_ IDataModelConcept* dataModel, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateIntrinsicObject)(_In_ ModelObjectKind objectKind, _In_ VARIANT* intrinsicData, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateTypedIntrinsicObject)(_In_ VARIANT* intrinsicData, _In_ IDebugHostType* type, _COM_Outptr_ IModelObject** object) PURE;
STDMETHOD(CreateMetadataStore)(_In_opt_ IKeyStore* parentStore, _COM_Outptr_ IKeyStore** metadataStore) PURE;
STDMETHOD(CreateTypedIntrinsicObjectEx)(_In_opt_ IDebugHostContext* context, _In_ VARIANT* intrinsicData, _In_ IDebugHostType* type, _COM_Outptr_ IModelObject** object) PURE;
A CreateNoValue metódus létrehoz egy "nincs érték" objektumot, bedobozozza egy IModelObjectbe, és visszaadja. A visszaadott modellobjektum egyfajta ObjectNoValue típusú.
A "nincs érték" objektumnak számos szemantikai jelentése van:
- (Nyelvtől függően) a null, null vagy nem definiált érték szemantikai megfelelőjének tekinthető.
- Minden tulajdonság-tartozék GetValue metódusa, amely sikert ad vissza, és az eredményül kapott "nincs érték" objektum azt jelzi, hogy az adott tulajdonságnak nincs értéke az adott példányra vonatkozóan, és úgy kell kezelni, mintha a tulajdonság nem létezne az adott példányhoz.
- A szemantikailag nem visszatérési értékkel rendelkező adatmodell-metódusok ezt sentinelként használják az ilyen jelzéshez (mivel egy metódusnak érvényes IModelObject értéket kell visszaadnia).
A CreateErrorObject metódus létrehoz egy "hibaobjektumot". Az adatmodell nem rendelkezik a kivételek és a kivételfolyamat fogalmával. A hiba kétféleképpen jelenik meg egy tulajdonságból/metódusból:
- Egyetlen sikertelen HRESULT, kiterjesztett hibainformációk nélkül. Vagy nincs több információ, amely megadható a hibához, vagy maga a hiba magától értetődő a visszaadott HRESULT-tól.
- Egyetlen sikertelen HRESULT és kiterjesztett hibainformációk párosulnak. A kiterjesztett hibainformáció a tulajdonság/metódus kimeneti argumentumában visszaadott hibaobjektum.
A CreateTypedObject metódus az a metódus, amellyel az ügyfél létrehozhat egy natív/nyelvi objektumot a hibakeresési cél címterében. Ha az újonnan létrehozott objektum típusa (az objectType argumentum szerint) egy vagy több, az adatmodell-kezelőben canonical visualizersként vagy bővítményként regisztrált típusaa aláírással egyezik meg, az egyező adatmodellek automatikusan a létrehozott példányobjektumhoz lesznek csatolva, mielőtt visszakerülnek a hívónak.
A CreateTypedObjectReference metódus szemantikailag hasonló a CreateTypedObject metódushoz, azzal a kivételével, hogy az a mögöttes natív/nyelvi szerkezetre mutató hivatkozást hoz létre. A létrehozott hivatkozás egy objektum, amelynek objektumtípusa ObjectTargetObjectReference. Ez nem natív hivatkozás, mivel az alapul szolgáló nyelv támogathatja (például egy C++ & vagy &&). Teljes mértékben lehetséges, hogy egy ObjectTargetObjectReference egy C++ referencia. Az ObjectTargetObjectReference típusú objektumok az IModelObject Dereference metódusának használatával konvertálhatók a mögöttes értékre. A hivatkozás átadható a mögöttes gazdagép kifejezésértékelőjének is, hogy megfelelő nyelven rendelhesse vissza az értéket.
A CreateSyntheticObject metódus létrehoz egy üres adatmodell-objektumot – egy kulcs-/érték-/metaadat- és fogalomtárat. A létrehozáskor nincsenek kulcsok és fogalmak az objektumon. Ez egy tiszta pala a hívó használni.
A CreateDataModelObject metódus egy egyszerű segédburkoló, amely olyan objektumokat hoz létre, amelyek adatmodellek – vagyis olyan objektumok, amelyek szülőmodellként lesznek csatolva más objektumokhoz. Minden ilyen objektumnak támogatnia kell az adatmodell koncepcióját az IDataModelConcepten keresztül. Ez a metódus egy új, üres szintetikus objektumot hoz létre explicit környezet nélkül, és hozzáadja az áthatolt IDataModelConceptet az adatmodell-koncepció újonnan létrehozott objektum implementációjaként. Ez a CreateSyntheticObject és a SetConcept hívásaival is hasonlóképpen elvégezhető.
A CreateIntrinsicObject metódus az a metódus, amely belső értékeket ad meg az IModelObjectbe. A hívó egy COM VARIANT-ban helyezi el az értéket, és meghívja ezt a metódust. Az adatmodell-kezelő egy, az objektumot jelképező IModelObject-et ad vissza. Vegye figyelembe, hogy ez a módszer az alapvető IUnknown-alapú típusok bevitelére is használatos: tulajdonságkiegészítők, metódusok, környezetek stb. Ilyen esetekben az objectKind metódus azt jelzi, hogy az objektum milyen típusú IUnknown alapú szerkezetet jelöl, az átadott változat punkVal mezője pedig az IUnknown származtatott típus. A típusnak statikusan öntöttnek kell lennie a megfelelő modellfelületre (például: IModelPropertyAccessor, IModelMethod, IDebugHostContext stb.) folyamatban. Az e metódus által támogatott VARIANT-típusok a következők: VT_UI1, VT_I1, VT_UI2, VT_I2, VT_UI4, VT_I4, VT_UI8, VT_I8, VT_R4, VT_R8, VT_BOOL, VT_BSTR és VT_UNKNOWN (a ModelObjectKind enumerálás által jelzett speciális IUnknown származtatott típusok készletéhez).
A CreateTypedintrinsicObject metódus hasonló a CreateIntrinsicObject metódushoz, azzal a kivétellel, hogy lehetővé teszi egy natív/nyelvi típus társítását az adatokhoz, és a dobozos értékkel együtt hordozva. Ez lehetővé teszi, hogy az adatmodell olyan szerkezeteket képviseljen, mint a natív számbavételi típusok (amelyek egyszerűen VT_UI* vagy VT_I* értékek). Ezzel a módszerrel a mutatótípusok is létrejönnek. Az adatmodell natív mutatója egy nulla kiterjesztett 64 bites mennyiség, amely eltolást jelent a hibakeresési cél virtuális címterébe. Egy VT_UI8 belül van beállítva, és ezzel a módszerrel és egy natív/nyelvi mutatót jelző típussal jön létre.
A CreateMetadataStore metódus létrehoz egy kulcstárolót – egy egyszerűsített kulcs-/érték-/metaadat-tárolót –, amely a tulajdonságokhoz és számos más értékhez társítható metaadatok tárolására szolgál. A metaadattárak egyetlen szülővel rendelkezhetnek (ami viszont egyetlen szülővel is rendelkezhet). Ha egy adott metaadatkulcs nem egy adott áruházban található, a rendszer ellenőrzi a szüleit. A legtöbb metaadat-tárolóban nincsenek szülők. Ez azonban lehetővé teszi a közös metaadatok egyszerű megosztását.
A CreateTypedIntrinsicObjectEx metódus szemantikailag hasonlít a CreateTypedIntrinsicObject metódushoz. A kettő között az egyetlen különbség az, hogy ez a módszer lehetővé teszi a hívó számára, hogy meghatározza a belső adatok érvényességének kontextusát. Ha a rendszer nem ad át kontextust, az adatok érvényesnek minősülnek a típusargumentumtól (a CreateTypedIntrinsicObject viselkedésétől függően). Ez lehetővé teszi a hibakeresési célban szereplő, a típustól örökölhetőnél pontosabb kontextust igénylő, beírt mutatóértékek létrehozását.
Bővíthetőség / Regisztrációs módszerek Az alábbi metódusok kezelik az adatmodell bővíthetőségi mechanizmusát, lehetővé téve az ügyfél számára a meglévő modellek kiterjesztését vagy regisztrálását, vagy megkérheti az adatmodellt, hogy automatikusan csatoljon egy adott szülőmodellt az adott feltételnek megfelelő natív típusokhoz.
STDMETHOD(GetModelForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _Out_ IModelObject** dataModel) PURE;
STDMETHOD(GetModelForType)(_In_ IDebugHostType* type, _COM_Outptr_ IModelObject** dataModel, _COM_Outptr_opt_ IDebugHostTypeSignature** typeSignature, _COM_Outptr_opt_ IDebugHostSymbolEnumerator** wildcardMatches) PURE;
STDMETHOD(RegisterModelForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _In_ IModelObject* dataModel) PURE;
STDMETHOD(UnregisterModelForTypeSignature)(_In_ IModelObject* dataModel, _In_opt_ IDebugHostTypeSignature* typeSignature) PURE;
STDMETHOD(RegisterExtensionForTypeSignature)(_In_ IDebugHostTypeSignature* typeSignature, _In_ IModelObject* dataModel) PURE;
STDMETHOD(UnregisterExtensionForTypeSignature)(_In_ IModelObject* dataModel, _In_opt_ IDebugHostTypeSignature* typeSignature) PURE;
STDMETHOD(GetRootNamespace)(_COM_Outptr_ IModelObject** rootNamespace) PURE;
STDMETHOD(RegisterNamedModel)(_In_ PCWSTR modelName, _In_ IModelObject *modeObject) PURE;
STDMETHOD(UnregisterNamedModel)(_In_ PCWSTR modelName) PURE;
STDMETHOD(AcquireNamedModel)(_In_ PCWSTR modelName, _COM_Outptr_ IModelObject **modelObject) PURE;
A GetModelForTypeSignature metódus a RegisterModelForTypeSignature metódus előzetes hívásával visszaadja azt az adatmodellt, amelyet egy adott típusaláírással regisztráltak. Az ebből a módszerből visszaadott adatmodell minden olyan típus canonical visualizerének tekinthető, amely megfelel az átadott típusaaírásnak. Canonical visualizerként ez az adatmodell veszi át a típus megjelenítését. A megjelenítési motorok alapértelmezés szerint elrejtik az objektum natív/nyelvi szerkezeteit az adatmodell által bemutatott objektum nézete mellett.
A GetModelForType metódus azt az adatmodellt adja vissza, amely egy adott típusú példány canonical visualizere. Ez a módszer tulajdonképpen a RegisterModelForTypeSignature metódus előzetes hívásával regisztrált, legjobban megfelelő típusaláírást keresi meg, és visszaadja a társított adatmodellt.
A RegisterModelForTypeSignature metódus az elsődleges módszer, amelyet a hívó használ egy canonical visualizer regisztrálásához egy adott típushoz (vagy típuskészlethez). A canonical visualizer egy adatmodell, amely tulajdonképpen egy adott típus (vagy típuskészlet) megjelenítését veszi át. A hibakereső felhasználói felületén megjelenített típus natív/nyelvi nézete helyett megjelenik a regisztrált adatmodell által bemutatott típus nézete (valamint a kívánt felhasználó natív/nyelvi nézetére való visszalépés módja).
UnregisterModelForTypeSignature
A UnregisterModelForTypeSignature metódus visszavon egy korábbi hívást a RegisterModelForTypeSignature metódushoz. Ez a módszer eltávolíthat egy adott adatmodellt egy adott típuskódnak megfelelő típusok canonikus vizualizációs vizualizációjaként, vagy eltávolíthat egy adott adatmodellt minden olyan típus-aláíráshoz, amely alatt az adatmodell regisztrálva van.
RegisterExtensionForTypeSignature
A RegisterExtensionForTypeSignature metódus hasonló a RegisterModelForTypeSignature metódushoz egy kulcskülönbséggel. Az ehhez a metódushoz átadott adatmodell nem a canonical visualizer bármilyen típushoz, és nem veszi át az adott típus natív/nyelvi nézetének megjelenítését. A metódusnak átadott adatmodell automatikusan szülőként lesz hozzáadva minden olyan konkrét típushoz, amely megfelel a megadott típus-aláírásnak. A RegisterModelForTypeSignature metódustól eltérően nincs korlátozva, hogy az azonos vagy nem egyértelmű típusú aláírások egy adott típus (vagy típuskészlet) bővítményeként legyenek regisztrálva. Minden olyan bővítmény, amelynek típusaadéka egy adott konkrét típuspéldánynak felel meg, az ezen a metóduson keresztül regisztrált adatmodell automatikusan csatolva lesz az újonnan létrehozott objektumokhoz szülőmodellként. Ez tulajdonképpen lehetővé teszi, hogy tetszőleges számú ügyfél új mezőkkel vagy funkciókkal bővítsen ki egy típust (vagy típuskészletet).
UnregisterExtensionForTypeSignature
A UnregisterExtensionForTypeSignature metódus visszavonja a RegisterExtensionForTypeSignature korábbi hívását. Egy adott adatmodell regisztrációját egy adott típusaadék bővítményeként, vagy az adatmodell regisztrálásakor használt összes típusaadminisztrátor bővítményeként szünteti meg.
A GetRootNamespace metódus az adatmodell gyökérnévterét adja vissza. Ez egy olyan objektum, amelyet az adatmodell kezel, és amelybe a hibakeresési gazdagép bizonyos objektumokat helyez el.
A RegisterNamedModel metódus egy jól ismert név alatt regisztrál egy adott adatmodellt, hogy azok a kibővíteni kívánt ügyfelek számára is megtalálhatók legyenek. Az API elsődleges célja, hogy közzétegye az adatmodellt olyanként, amely kibővíthető az ezen jól ismert név alatt regisztrált modell lekérésével és egy szülőmodell hozzáadásával.
A UnregisterNamedModel metódus visszavonja a RegisterNamedModel korábbi hívását. Eltávolítja az adatmodell és a keresett név közötti társításokat.
Az a hívó, aki egy adott név alatt regisztrált adatmodellt kíván kibővíteni, meghívja az AcquireNamedModel metódust, hogy lekérje a kiterjeszteni kívánt adatmodell objektumát. Ez a metódus a RegisterNamedModel metódus előzetes hívásával visszaadja a regisztrált adatmodelleket. Mivel a AcquireNamedModel metódus elsődleges célja a modell kiterjesztése, ez a módszer különleges viselkedést vált ki, ha még nem regisztráltak modellt a megadott név alatt. Ha még nincs regisztrálva modell a megadott név alatt, létrejön egy csonkobjektum, amely ideiglenesen a megadott név alatt van regisztrálva, és visszakerül a hívónak. Ha a valós adatmodell regisztrálva van a RegisterNamedModel metódus hívásán keresztül, a csonkobjektumon végrehajtott módosítások gyakorlatilag a valós modellen történnek. Ez eltávolítja a terhelési sorrend számos függőségi problémáját az egymást kiterjesztő összetevőkből.
segítő módszerek
Az alábbi módszerek olyan általános segédmetódusok, amelyek az adatmodell objektumainak összetett műveleteit segítik elő. Bár ezeket a műveleteket más módszerekkel is végrehajthatja az adatmodellen vagy objektumán, ezek a kényelmi módszerek jelentősen megkönnyítik:
STDMETHOD(AcquireSubNamespace)(_In_ PCWSTR modelName, _In_ PCWSTR subNamespaceModelName, _In_ PCWSTR accessName, _In_opt_ IKeyStore *metadata, _COM_Outptr_ IModelObject **namespaceModelObject) PURE;
A AcquireSubNamespace metódus segít olyan dolog felépítésében, amely hagyományosan nyelvi névtérnek tűnhet, mint egy dinamikus nyelv új objektuma. Ha például egy hívó egy folyamatobjektum tulajdonságait kategorizálni szeretné, hogy a folyamatobjektum rendezettebb legyen, és a tulajdonságok könnyebben felderíthetők legyenek, ennek egyik módja az lenne, ha a folyamatobjektum minden kategóriájához létrehozna egy alobjektumot, és elhelyezné ezeket a tulajdonságokat az objektumon belül.
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++ interfészei
Hibakereső adatmodell C++ további felületei