Share via

CComObjectRootEx-klasse

Opmerking

De ATL (Active Template Library) wordt nog steeds ondersteund. We voegen echter geen functies meer toe of werken de documentatie bij.

Deze klasse biedt methoden voor het afhandelen van beheer van het aantal objectverwijzingen voor niet-geaggregeerde en geaggregeerde objecten.

Syntaxis

template<class ThreadModel>
class CComObjectRootEx : public CComObjectRootBase

Parameterwaarden

ThreadModel
De klasse waarvan de methoden het gewenste threadingmodel implementeren. U kunt het threadingmodel expliciet kiezen door ThreadModel in te stellen op CComSingleThreadModel, CComMultiThreadModel of CComMultiThreadModelNoCS. U kunt het standaardthreadmodel van de server accepteren door ThreadModel in te stellen op CComObjectThreadModel of CComGlobalsThreadModel.

Leden

Methods

Functie Description
CComObjectRootEx Bouwer.
InternalAddRef Hiermee wordt het aantal verwijzingen voor een niet-samengevoegd object verhoogd.
InternalRelease Hiermee wordt het aantal verwijzingen voor een niet-samengevoegd object afgetrokken.
Vergrendeling Als het threadmodel multithreaded is, krijgt u het eigendom van een kritiek sectieobject.
Ontgrendelen Als het threadmodel multithreaded is, wordt het eigendom van een kritiek sectieobject vrijgegeven.

CComObjectRootBase-methoden

Functie Description
FinalConstruct Overschrijven in uw klasse om alle initialisaties uit te voeren die vereist zijn voor uw object.
FinalRelease Overschrijven in uw klasse om opschoning uit te voeren die vereist is voor uw object.
OuterAddRef Hiermee wordt het aantal verwijzingen voor een geaggregeerd object verhoogd.
OuterQueryInterface Gedelegeerden aan de buitenkant IUnknown van een geaggregeerd object.
OuterRelease Hiermee wordt het aantal verwijzingen voor een geaggregeerd object afgetrokken.

Statische functies

Functie Description
InternalQueryInterface Gedelegeerden aan een IUnknown niet-samengevoegd object.
ObjectMain Aangeroepen tijdens de initialisatie en beëindiging van de module voor afgeleide klassen die worden vermeld in de objecttoewijzing.

Gegevensleden

Gegevenslid Description
m_dwRef Met m_pOuterUnknown, deel van een vereniging. Wordt gebruikt wanneer het object niet wordt samengevoegd om het aantal verwijzingen van AddRef en Release.
m_pOuterUnknown Met m_dwRef, deel van een vereniging. Wordt gebruikt wanneer het object wordt samengevoegd om een aanwijzer op de buitenste onbekende plaats te houden.

Opmerkingen

CComObjectRootEx verwerkt beheer van het aantal objecten voor niet-geaggregeerde en geaggregeerde objecten. Het bevat het aantal objectverwijzingen als uw object niet wordt samengevoegd en de aanwijzer op de buitenste onbekende plaats houdt als uw object wordt samengevoegd. Voor geaggregeerde objecten CComObjectRootEx kunnen methoden worden gebruikt om de fout van het binnenste object te verwerken dat moet worden gemaakt en om het buitenste object te beschermen tegen verwijdering wanneer interne interfaces worden vrijgegeven of het binnenste object wordt verwijderd.

Een klasse die een COM-server implementeert, moet overnemen van CComObjectRootEx of CComObjectRoot.

Als de klassedefinitie de DECLARE_POLY_AGGREGATABLE macro opgeeft, maakt ATL een instantie van CComPolyObject<CYourClass> wanneer IClassFactory::CreateInstance deze wordt aangeroepen. Tijdens het maken wordt de waarde van het buitenste onbekende gecontroleerd. Als het NULL is, IUnknown wordt deze geïmplementeerd voor een niet-samengevoegd object. Als de buitenste onbekende waarde niet NULL is, IUnknown wordt deze geïmplementeerd voor een geaggregeerd object.

Als uw klasse de DECLARE_POLY_AGGREGATABLE macro niet opgeeft, maakt ATL een exemplaar van CAggComObject<CYourClass> voor geaggregeerde objecten of een exemplaar van CComObject<CYourClass> niet-geaggregeerde objecten.

Het voordeel van het gebruik CComPolyObject is dat u vermijdt dat u zowel CComAggObject als CComObject in uw module de samengevoegde en niet-samengevoegde gevallen verwerkt. Een enkel CComPolyObject object verwerkt beide gevallen. Daarom bestaat er slechts één kopie van de vtable en één kopie van de functies in uw module. Als uw vtable groot is, kan dit de modulegrootte aanzienlijk verkleinen. Als uw vtable echter klein is, kan het gebruik CComPolyObject resulteren in een iets grotere module omdat deze niet is geoptimaliseerd voor een geaggregeerd of niet-samengevoegd object, zoals dat CComAggObject wel en CComObject.

Als uw object is samengevoegd, wordt IUnknown geïmplementeerd door CComAggObject of CComPolyObject. Deze klassen delegeren QueryInterface, AddRefen Release aanroepen naar CComObjectRootEx'sOuterAddRefOuterQueryInterface, en OuterRelease om door te sturen naar de buitenste onbekende. Normaal gesproken overschrijft CComObjectRootEx::FinalConstruct u in uw klasse om geaggregeerde objecten te maken en overschrijven CComObjectRootEx::FinalRelease om eventuele geaggregeerde objecten vrij te maken.

Als uw object niet is samengevoegd, IUnknown wordt dit geïmplementeerd door CComObject of CComPolyObject. In dit geval worden aanroepen aan QueryInterface, AddRefen Release gedelegeerd aan CComObjectRootEx's InternalQueryInterface, InternalAddRefen InternalRelease om de werkelijke bewerkingen uit te voeren.

Requirements

Koptekst: atlcom.h

CComObjectRootEx::CComObjectRootEx

De constructor initialiseert het aantal verwijzingen naar 0.

CComObjectRootEx();

CComObjectRootEx::FinalConstruct

U kunt deze methode in uw afgeleide klasse overschrijven om elke initialisatie uit te voeren die vereist is voor uw object.

HRESULT FinalConstruct();

Retourwaarde

Retourneer S_OK bij succes of een van de standaardfout HRESULT-waarden.

Opmerkingen

CComObjectRootEx::FinalConstruct Standaard wordt S_OK geretourneerd.

Er zijn voordelen bij het uitvoeren van initialisatie in FinalConstruct plaats van de constructor van uw klasse:

  • U kunt geen statuscode van een constructor retourneren, maar u kunt een HRESULT retourneren met behulp van FinalConstructde retourwaarde. Wanneer objecten van uw klasse worden gemaakt met behulp van de standaardklassefactory van ATL, wordt deze retourwaarde doorgegeven aan de COM-client, zodat u ze gedetailleerde foutinformatie kunt verstrekken.

  • U kunt geen virtuele functies aanroepen via het mechanisme voor virtuele functies van de constructor van een klasse. Het aanroepen van een virtuele functie vanuit de constructor van een klasse resulteert in een statisch opgeloste aanroep van de functie, omdat deze op dat punt in de overnamehiërarchie is gedefinieerd. Aanroepen naar pure virtuele functies resulteren in linkerfouten.

    Uw klasse is niet de meest afgeleide klasse in de overnamehiërarchie. Deze klasse is afhankelijk van een afgeleide klasse die door ATL wordt geleverd om een deel van de functionaliteit ervan te bieden. Er is een goede kans dat uw initialisatie de functies van die klasse moet gebruiken (dit is zeker waar wanneer objecten van uw klasse andere objecten moeten aggregeren), maar de constructor in uw klasse heeft geen toegang tot deze functies. De bouwcode voor uw klasse wordt uitgevoerd voordat de meest afgeleide klasse volledig is samengesteld.

    Wordt FinalConstruct echter onmiddellijk aangeroepen nadat de meest afgeleide klasse volledig is samengesteld, zodat u virtuele functies kunt aanroepen en de implementatie van verwijzingstellingen kunt gebruiken die door ATL wordt geleverd.

Example

Overschrijf deze methode doorgaans in de klasse die is afgeleid van CComObjectRootEx het maken van geaggregeerde objecten. Voorbeeld:

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.

Als de constructie mislukt, kunt u een fout retourneren. U kunt ook de macro DECLARE_PROTECT_FINAL_CONSTRUCT gebruiken om uw buitenste object te beschermen tegen verwijderen als tijdens het maken het interne geaggregeerde object het aantal verwijzingen vergroot en vervolgens het aantal verlagen tot 0.

Hier volgt een typische manier om een aggregaties te maken:

  • Voeg een IUnknown aanwijzer toe aan uw klasseobject en initialiseer het naar NULL in de constructor.

  • Overschrijven FinalConstruct om de aggregaties te maken.

  • Gebruik de IUnknown aanwijzer die u hebt gedefinieerd als de parameter voor de COM_INTERFACE_ENTRY_AGGREGATE macro.

  • Overschrijven FinalRelease om de IUnknown aanwijzer vrij te geven.

CComObjectRootEx::FinalRelease

U kunt deze methode in uw afgeleide klasse overschrijven om alle opschoningsbewerkingen uit te voeren die vereist zijn voor uw object.

void FinalRelease();

Opmerkingen

Doet standaard CComObjectRootEx::FinalRelease niets.

Het uitvoeren van opschonen FinalRelease verdient de voorkeur om code toe te voegen aan de destructor van uw klasse, omdat het object nog steeds volledig is samengesteld op het punt dat FinalRelease wordt aangeroepen. Hiermee kunt u veilig toegang krijgen tot de methoden die worden geleverd door de meest afgeleide klasse. Dit is met name belangrijk voor het vrijmaken van geaggregeerde objecten voordat ze worden verwijderd.

CComObjectRootEx::InternalAddRef

Hiermee wordt het aantal verwijzingen van een niet-samengevoegd object verhoogd met 1.

ULONG InternalAddRef();

Retourwaarde

Een waarde die nuttig kan zijn voor diagnostische gegevens en tests.

Opmerkingen

Als het threadmodel multithreaded is, InterlockedIncrement wordt dit gebruikt om te voorkomen dat meerdere threads tegelijkertijd het aantal verwijzingen wijzigen.

CComObjectRootEx::InternalQueryInterface

Hiermee wordt een aanwijzer naar de aangevraagde interface opgehaald.

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

Parameterwaarden

pThis
[in] Een aanwijzer naar het object dat de COM-kaart bevat van interfaces die beschikbaar zijn voor QueryInterface.

pEntries
[in] Een aanwijzer naar de _ATL_INTMAP_ENTRY structuur die toegang heeft tot een kaart met beschikbare interfaces.

iid
[in] De GUID van de interface die wordt aangevraagd.

ppvObject
[uit] Een aanwijzer naar de interfacepointer die is opgegeven in iid of NULL als de interface niet wordt gevonden.

Retourwaarde

Een van de standaard HRESULT-waarden.

Opmerkingen

InternalQueryInterface verwerkt alleen interfaces in de COM-kaarttabel. Als uw object is samengevoegd, InternalQueryInterface wordt deze niet gedelegeerd aan het buitenste onbekende object. U kunt interfaces invoeren in de COM-kaarttabel met de macro COM_INTERFACE_ENTRY of een van de varianten.

CComObjectRootEx::InternalRelease

Hiermee wordt het aantal verwijzingen van een niet-samengevoegd object met 1 verminderd.

ULONG InternalRelease();

Retourwaarde

In builds zonder foutopsporing en foutopsporing retourneert deze functie een waarde die nuttig kan zijn voor diagnostische gegevens of tests. De exacte waarde die wordt geretourneerd, is afhankelijk van veel factoren, zoals het gebruikte besturingssysteem, en kan, of niet, het referentieaantal zijn.

Opmerkingen

Als het threadmodel multithreaded is, InterlockedDecrement wordt dit gebruikt om te voorkomen dat meerdere threads tegelijkertijd het aantal verwijzingen wijzigen.

CComObjectRootEx::Lock

Als het threadmodel multithreaded is, roept deze methode de Win32 API-functie EnterCriticalSection aan, die wacht totdat de thread eigenaar kan worden van het kritieke sectieobject dat is verkregen via een lid van een persoonlijke gegevens.

void Lock();

Opmerkingen

Wanneer de beveiligde code is uitgevoerd, moet Unlock de thread het eigendom van de kritieke sectie vrijgeven.

Als het threadmodel één thread is, doet deze methode niets.

CComObjectRootEx::m_dwRef

Onderdeel van een samenvoeging die toegang heeft tot vier bytes geheugen.

long m_dwRef;

Opmerkingen

Met m_pOuterUnknown, deel van een samenvoeging:

union {
    long m_dwRef;
    IUnknown* m_pOuterUnknown;
};

Als het object niet is samengevoegd, wordt het aantal verwijzingen geopend door AddRef en Release opgeslagen in m_dwRef. Als het object wordt samengevoegd, wordt de aanwijzer naar de buitenste onbekende opgeslagen in m_pOuterUnknown.

CComObjectRootEx::m_pOuterUnknown

Onderdeel van een samenvoeging die toegang heeft tot vier bytes geheugen.

IUnknown*
    m_pOuterUnknown;

Opmerkingen

Met m_dwRef, deel van een samenvoeging:

union {
    long m_dwRef;
    IUnknown* m_pOuterUnknown;
};

Als het object wordt samengevoegd, wordt de aanwijzer naar de buitenste onbekende opgeslagen in m_pOuterUnknown. Als het object niet is samengevoegd, wordt het aantal verwijzingen geopend door AddRef en Release opgeslagen in m_dwRef.

CComObjectRootEx::ObjectMain

Voor elke klasse die wordt vermeld in de objecttoewijzing, wordt deze functie eenmaal aangeroepen wanneer de module wordt geïnitialiseerd en opnieuw wanneer deze wordt beëindigd.

static void WINAPI ObjectMain(bool bStarting);

Parameterwaarden

bStarting
[uit] De waarde is WAAR als de klasse wordt geïnitialiseerd; anders ONWAAR.

Opmerkingen

De waarde van de parameter bStarting geeft aan of de module wordt geïnitialiseerd of beëindigd. De standaard implementatie van ObjectMain doet niets, maar u kunt deze functie in uw klasse overschrijven om resources te initialiseren of op te schonen die u wilt toewijzen voor de klasse. Houd er rekening mee dat ObjectMain wordt aangeroepen voordat er exemplaren van de klasse worden aangevraagd.

ObjectMain wordt aangeroepen vanaf het toegangspunt van het DLL-bestand, dus het type bewerking dat de invoerpuntfunctie kan uitvoeren, is beperkt. Zie DLL's en visual C++ runtime-bibliotheekgedrag enDllMain voor meer informatie over deze beperkingen.

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

Hiermee wordt het verwijzingsaantal verhoogd van het buitenste onbekende van een aggregatie.

ULONG OuterAddRef();

Retourwaarde

Een waarde die nuttig kan zijn voor diagnostische gegevens en tests.

CComObjectRootEx::OuterQueryInterface

Hiermee wordt een indirecte aanwijzer opgehaald naar de aangevraagde interface.

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

Parameterwaarden

iid
[in] De GUID van de interface die wordt aangevraagd.

ppvObject
[uit] Een aanwijzer naar de interfacepointer die is opgegeven in iid of NULL als de aggregatie de interface niet ondersteunt.

Retourwaarde

Een van de standaard HRESULT-waarden.

CComObjectRootEx::OuterRelease

Hiermee wordt het verwijzingsaantal van het buitenste onbekende van een aggregatie afgeschroefd.

ULONG OuterRelease();

Retourwaarde

In builds zonder foutopsporing retourneert altijd 0. In builds voor foutopsporing wordt een waarde geretourneerd die nuttig kan zijn voor diagnostische gegevens of tests.

CComObjectRootEx::Unlock

Als het threadmodel multithreaded is, roept deze methode de Win32 API-functie LeaveCriticalSection aan, waardoor het eigendom wordt vrijgegeven van het kritieke sectieobject dat is verkregen via een lid van een persoonlijke gegevens.

void Unlock();

Opmerkingen

Als u het eigendom wilt verkrijgen, moet de thread worden aangeroepen Lock. Voor elke aanroep is Lock een bijbehorende aanroep vereist om het eigendom van de kritieke sectie vrij te Unlock geven.

Als het threadmodel één thread is, doet deze methode niets.

Zie ook

CComAggObject-klasse
CComObject-klasse
Klasse CComPolyObject
Overzicht van klassen

  • Last updated on