Megosztás a következőn keresztül:

CComObjectRootEx osztály

Megjegyzés:

Az aktív sablontár (ATL) továbbra is támogatott. A továbbiakban azonban nem adunk hozzá funkciókat, és nem frissítjük a dokumentációt.

Ez az osztály metódusokat biztosít a nem összesített és összesített objektumok objektumhivatkozás-számának kezelésére.

Szemantika

template<class ThreadModel>
class CComObjectRootEx : public CComObjectRootBase

Paraméterek

ThreadModel
Az osztály, amelynek metódusai implementálják a kívánt szálmodellt. A szálmodellt explicit módon úgy választhatja ki, hogy a ThreadModeltCComSingleThreadModel, CComMultiThreadModel vagy CComMultiThreadModelNoCS értékre állítja. A kiszolgáló alapértelmezett szálmodelljét a ThreadModelCComObjectThreadModel vagy CComGlobalsThreadModel értékre állításával fogadhatja el.

Tagok

Metódusok

Funkció Description
CComObjectRootEx Konstruktor.
InternalAddRef Növeli a nem összesített objektumok hivatkozásainak számát.
InternalRelease A nem összesített objektumok hivatkozásainak száma csökken.
Zár Ha a szálmodell többszálas, szerezze be egy kritikus szakaszobjektum tulajdonjogát.
Kinyit Ha a szálmodell többszálas, kiadja egy kritikus szakaszobjektum tulajdonjogát.

CComObjectRootBase metódusok

Funkció Description
FinalConstruct Felülbírálás az osztályban az objektum által igényelt inicializálás végrehajtásához.
FinalRelease Felülbírálás az osztályban az objektum által igényelt törlés végrehajtásához.
OuterAddRef Növeli az összesített objektumok referenciaszámát.
OuterQueryInterface Delegáltak egy összesített objektum külső IUnknown részére.
OuterRelease Egy összesített objektum hivatkozásainak száma csökken.

Statikus függvények

Funkció Description
InternalQueryInterface Delegáltak IUnknown egy nem összesített objektumhoz.
ObjectMain Az objektumtérképen felsorolt származtatott osztályok modul inicializálása és leállítása során hívható meg.

Adattagok

Adattag Description
m_dwRef Egy m_pOuterUnknownszakszervezettel. Akkor használatos, ha az objektum nincs összesítve az és Releasea hivatkozási szám AddRef tárolására.
m_pOuterUnknown Egy m_dwRefszakszervezettel. Az objektum összesítésekor a külső ismeretlenre mutató mutató tárolására szolgál.

Megjegyzések

CComObjectRootEx kezeli a nem összesített és összesített objektumok objektumhivatkozásainak számát. Megtartja az objektumhivatkozások számát, ha az objektum nincs összesítve, és az objektum összesítésekor a külső ismeretlenre mutató mutatót tartja. Az összesített objektumok esetében metódusok CComObjectRootEx használhatók a belső objektum szerkezethibájának kezelésére, valamint a külső objektum törlésének védelmére a belső felületek felszabadításakor vagy a belső objektum törlésekor.

A COM-kiszolgálót megvalósító osztálynak a CComObjectRoottól vagy a CComObjectRoottólCComObjectRootEx kell örökölnie.

Ha az osztálydefiníció megadja a DECLARE_POLY_AGGREGATABLE makrót, az ATL létrehoz egy példányt CComPolyObject<CYourClass> , amelynek IClassFactory::CreateInstance a neve meghívva van. A létrehozás során a rendszer ellenőrzi a külső ismeretlen értékét. Ha null értékű, IUnknown akkor egy nem összesített objektumhoz van implementálva. Ha a külső ismeretlen nem NULL értékű, IUnknown akkor egy összesített objektumhoz lesz implementálva.

Ha az osztály nem adja meg a DECLARE_POLY_AGGREGATABLE makrót, az ATL létrehoz egy példányt CAggComObject<CYourClass> az összesített objektumokhoz vagy a nem összesített objektumok példányához CComObject<CYourClass> .

A használat CComPolyObject előnye, hogy elkerülheti, hogy mind a modulban, mind CComAggObjectCComObject a modulban kezelje az összesített és a nem összesített eseteket. Egyetlen CComPolyObject objektum mindkét esetet kezeli. Ezért a modulban csak a virtuális tábla egy példánya és a függvények egy példánya létezik. Ha a virtuális tábla nagy, ez jelentősen csökkentheti a modul méretét. Ha azonban a virtuális tábla kicsi, a használat CComPolyObject valamivel nagyobb modulméretet eredményezhet, mivel nem összesített vagy nem összesített objektumhoz van optimalizálva, ahogyan az is és CComAggObjectCComObject.

Ha az objektum összesítve van, az IUnknown implementálása CComAggObject vagy CComPolyObjecta . Ezek az osztályok delegálnak QueryInterface, AddRefés Release meghívják őketCComObjectRootExOuterQueryInterface, OuterAddRefés OuterRelease továbbítják a külső ismeretlennek. Az osztályban általában felülbírálhatja CComObjectRootEx::FinalConstruct az összes összesített objektum létrehozását, és felülbírálhatja CComObjectRootEx::FinalRelease az összes összesített objektum felszabadításához.

Ha az objektum nincs összesítve, IUnknown akkor azt a program implementálja vagy CComPolyObjectvégrehajtjaCComObject. Ebben az esetben a rendszer meghívja QueryInterfaceReleaseAddRefés delegálja az CComObjectRootEx"sInternalQueryInterface" parancsot, InternalAddRefés InternalRelease végrehajtja a tényleges műveleteket.

Requirements

Fejléc: atlcom.h

CComObjectRootEx::CComObjectRootEx

A konstruktor 0-ra inicializálja a referenciaszámot.

CComObjectRootEx();

CComObjectRootEx::FinalConstruct

Ezt a metódust felülbírálhatja a származtatott osztályban az objektumhoz szükséges inicializálás végrehajtásához.

HRESULT FinalConstruct();

Visszaadott érték

A sikeres S_OK vagy a HRESULT standard hibaértékek egyikét adja vissza.

Megjegyzések

Alapértelmezés szerint CComObjectRootEx::FinalConstruct egyszerűen S_OK ad vissza.

Az inicializálás FinalConstruct az osztály konstruktorának helyett a következő előnyökkel jár:

  • Konstruktorból nem tud állapotkódot visszaadni, de a HRESULT értékét a visszatérési FinalConstructérték alapján is visszaadhatja. Ha az osztály objektumai az ATL által biztosított standard osztály-előállítóval jönnek létre, a rendszer ezt a visszatérési értéket a COM-ügyfélre propagálja, így részletes hibainformációkat adhat meg nekik.

  • A virtuális függvényeket nem hívhatja meg a virtuális függvény mechanizmusán keresztül egy osztály konstruktorától. Ha egy virtuális függvényt egy osztály konstruktorától hív meg, az a függvény statikusan feloldott hívását eredményezi, mivel az az öröklési hierarchia ezen pontján van definiálva. A tiszta virtuális függvényekre irányuló hívások hivatkozási hibákat eredményeznek.

    Az osztály nem a leg származtatottabb osztály az öröklési hierarchiában – az ATL által biztosított származtatott osztályra támaszkodik, amely biztosítja bizonyos funkcióit. Jó esély van arra, hogy az inicializálásnak az adott osztály által biztosított funkciókat kell használnia (ez minden bizonnyal igaz, ha az osztály objektumainak más objektumokat kell összesíteniük), de az osztály konstruktorának nincs módja ezeknek a funkcióknak a elérésére. Az osztály építési kódja a legelfejezettebb osztály teljes létrehozása előtt lesz végrehajtva.

    A rendszer azonban közvetlenül a levezetett osztály teljes felépítése után hívja meg, FinalConstruct így virtuális függvényeket hívhat meg, és használhatja az ATL által biztosított hivatkozásszámláló implementációt.

Example

Ezt a metódust általában felülbírálhatja a származtatott osztályban CComObjectRootEx az összes összesített objektum létrehozásához. Például:

class ATL_NO_VTABLE CMyAggObject :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyAggObject, &CLSID_MyAggObject>,
   public IDispatchImpl<IMyAggObject, &IID_IMyAggObject, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
public:
   DECLARE_GET_CONTROLLING_UNKNOWN()
   HRESULT FinalConstruct()
   {
      return CoCreateInstance(CLSID_MyCustomClass, GetControllingUnknown(), 
         CLSCTX_ALL, IID_IUnknown, (void**)&m_pMyCustomClass);
   }

   IMyCustomClass* m_pMyCustomClass;

   // Remainder of class declaration omitted.

Ha az építés sikertelen, hibát adhat vissza. A makróval DECLARE_PROTECT_FINAL_CONSTRUCT is megvédheti a külső objektumot a törléstől, ha a belső összesített objektum a létrehozás során növeli a hivatkozás számát, majd 0-ra csökken.

Az aggregátumok létrehozásának tipikus módja az alábbiak:

  • Adjon hozzá egy mutatót IUnknown az osztályobjektumhoz, és inicializálja NULL értékre a konstruktorban.

  • Felülbírálás FinalConstruct az összesítés létrehozásához.

  • Használja a IUnknown paraméterként definiált mutatót a COM_INTERFACE_ENTRY_AGGREGATE makróhoz.

  • Felülbírálás FinalRelease a mutató felengedéséhez IUnknown .

CComObjectRootEx::FinalRelease

Ezt a metódust felülbírálhatja a származtatott osztályban az objektumhoz szükséges összes törlés végrehajtásához.

void FinalRelease();

Megjegyzések

Alapértelmezés szerint CComObjectRootEx::FinalRelease semmit sem tesz.

A törlést FinalRelease célszerűebb kódot hozzáadni az osztály destruktorához, mivel az objektum még mindig teljesen ki van építve a meghívási FinalRelease ponton. Ez lehetővé teszi, hogy biztonságosan hozzáférjen a legelvezetettebb osztály által biztosított módszerekhez. Ez különösen fontos az összesítő objektumok törlés előtti felszabadításához.

CComObjectRootEx::InternalAddRef

Egy nem összesített objektum hivatkozási számát 1-zel növeli.

ULONG InternalAddRef();

Visszaadott érték

A diagnosztikához és teszteléshez hasznos érték.

Megjegyzések

Ha a szálmodell többszálas, akkor a rendszer megakadályozza, InterlockedIncrement hogy egynél több szál egyszerre módosítsa a referenciaszámot.

CComObjectRootEx::InternalQueryInterface

A kért felületre mutató mutatót kér le.

static HRESULT InternalQueryInterface(
    void* pThis,
    const _ATL_INTMAP_ENTRY* pEntries,
    REFIID iid,
    void** ppvObject);

Paraméterek

pThis
[in] Mutató arra az objektumra, amely tartalmazza a COM-térképet, amelyen a felületek láthatók QueryInterface.

PEntries
[in] Az elérhető felületek térképéhez hozzáférő struktúra mutatója _ATL_INTMAP_ENTRY .

iid
[in] A kért felület GUID azonosítója.

ppvObject
[kifelé] Az iid-ben megadott illesztőmutatóra mutató mutató, vagy null értékű, ha az illesztő nem található.

Visszaadott érték

Az egyik standard HRESULT érték.

Megjegyzések

InternalQueryInterface csak a COM-térképtáblában lévő felületeket kezeli. Ha az objektum összesítve van, InternalQueryInterface nem delegálható a külső ismeretlenbe. A COM-térképtáblába a makróval COM_INTERFACE_ENTRY vagy annak egyik változatával illesztőket adhat meg.

CComObjectRootEx::InternalRelease

A nem összesített objektumok hivatkozási számát 1-gyel csökkenti.

ULONG InternalRelease();

Visszaadott érték

A nem hibakeresési és hibakeresési buildekben ez a függvény egy olyan értéket ad vissza, amely hasznos lehet a diagnosztika vagy a tesztelés során. A visszaadott pontos érték számos tényezőtől függ, például a használt operációs rendszertől, és lehet, hogy nem a hivatkozási szám.

Megjegyzések

Ha a szálmodell többszálas, akkor a rendszer megakadályozza, InterlockedDecrement hogy egynél több szál egyszerre módosítsa a referenciaszámot.

CComObjectRootEx::Lock

Ha a szálmodell többszálas, ez a metódus meghívja a Win32 API EnterCriticalSection függvényt, amely megvárja, amíg a szál átveszi a privát adattagon keresztül beszerzett kritikus szakaszobjektum tulajdonjogát.

void Lock();

Megjegyzések

Amikor a védett kód befejeződik, a szálnak meg kell hívnia Unlock a kritikus szakasz tulajdonjogának kiadását.

Ha a szálmodell egyszálas, ez a metódus nem tesz semmit.

CComObjectRootEx::m_dwRef

Egy egyesítés része, amely négy bájtnyi memóriát ér el.

long m_dwRef;

Megjegyzések

A m_pOuterUnknownegyesítés részeként:

union {
    long m_dwRef;
    IUnknown* m_pOuterUnknown;
};

Ha az objektum nincs összesítve, a hivatkozási számot a rendszer a AddRefRelease következő helyen m_dwReftárolja: . Ha az objektum összesítve van, a külső ismeretlenre mutató mutatót a rendszer m_pOuterUnknown tárolja.

CComObjectRootEx::m_pOuterUnknown

Egy egyesítés része, amely négy bájtnyi memóriát ér el.

IUnknown*
    m_pOuterUnknown;

Megjegyzések

A m_dwRefegyesítés részeként:

union {
    long m_dwRef;
    IUnknown* m_pOuterUnknown;
};

Ha az objektum összesítve van, a külső ismeretlenre mutató mutatót a rendszer a következő helyen m_pOuterUnknowntárolja: . Ha az objektum nincs összesítve, a hivatkozási számot a rendszer m_dwRefAddRefRelease tárolja.

CComObjectRootEx::ObjectMain

Az objektumtérképen felsorolt összes osztály esetében ezt a függvényt a rendszer egyszer hívja meg a modul inicializálásakor, majd a modul leállásakor.

static void WINAPI ObjectMain(bool bStarting);

Paraméterek

bStarting
[kifelé] Az érték IGAZ, ha az osztály inicializálva van; egyéb esetben HAMIS.

Megjegyzések

A bStarting paraméter értéke azt jelzi, hogy a modul inicializálása vagy leállása folyamatban van-e. Az alapértelmezett implementáció ObjectMain nem tesz semmit, de felülbírálhatja ezt a függvényt az osztályban az osztályhoz lefoglalni kívánt erőforrások inicializálásához vagy törléséhez. Vegye figyelembe, hogy ObjectMain az osztály bármely példányának kérése előtt van meghívva.

ObjectMain meghívása a DLL belépési pontjáról történik, így a belépési pont függvény által végrehajtható művelet típusa korlátozott. Ezekről a korlátozásokról további információt a DLL-ek és a Visual C++ futásidejű kódtár viselkedése és a DllMain című témakörben talál.

Example

class ATL_NO_VTABLE CMyApp :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyApp, &CLSID_MyApp>,
   public IMyApp
{
public:
   CMyApp()
   {
   }

   static void WINAPI ObjectMain(bool bStarting)
   {
      if (bStarting)
         ;// Perform custom initialization routines
      else
         ;// Perform custom termination routines
   }

   // Remainder of class declaration omitted.

CComObjectRootEx::OuterAddRef

Növeli az összesítés külső ismeretlen részének hivatkozási számát.

ULONG OuterAddRef();

Visszaadott érték

A diagnosztikához és teszteléshez hasznos érték.

CComObjectRootEx::OuterQueryInterface

Indirekt mutatót kér le a kért felületre.

HRESULT OuterQueryInterface(REFIID iid, void** ppvObject);

Paraméterek

iid
[in] A kért felület GUID azonosítója.

ppvObject
[kifelé] Ha az összesítés nem támogatja a felületet, az iid-ben megadott illesztőmutatóra mutató mutató vagy NULL.

Visszaadott érték

Az egyik standard HRESULT érték.

CComObjectRootEx::OuterRelease

Az összesítés külső ismeretlen részének hivatkozási számát mérsékeli.

ULONG OuterRelease();

Visszaadott érték

A nem hibakeresési buildekben mindig 0 értéket ad vissza. A hibakeresési buildekben olyan értéket ad vissza, amely hasznos lehet a diagnosztika vagy a tesztelés során.

CComObjectRootEx::Unlock

Ha a szálmodell többszálas, ez a metódus meghívja a Win32 API-függvényt, a LeaveCriticalSection függvényt, amely felszabadítja a privát adattagon keresztül beszerzett kritikus szakaszobjektum tulajdonjogát.

void Unlock();

Megjegyzések

A tulajdonjog megszerzéséhez a szálnak meg kell hívnia Lock. Minden híváshoz Lock szükség van egy megfelelő hívásra a Unlock kritikus szakasz tulajdonjogának felszabadításához.

Ha a szálmodell egyszálas, ez a metódus nem tesz semmit.

Lásd még

CComAggObject osztály
CComObject osztály
CComPolyObject osztály
osztály áttekintése

  • Last updated on