CComObjectRootEx Class

 

Veröffentlicht: Juli 2016

Die neueste Dokumentation zu Visual Studio 2017 finden Sie unter Dokumentation zu Visual Studio 2017.

Diese Klasse stellt Methoden zur Verwaltung von Objekten Verweis Anzahl für aggregierte und aggregierten Objekte Behandlung.

template<class ThreadModel>  
class CComObjectRootEx : public CComObjectRootBase

Parameter

ThreadModel
Die Klasse, deren Methoden das gewünschte Threadingmodell implementieren. Sie können das Threadingmodell explizit auswählen, indem ThreadModel auf CComSingleThreadModel, CComMultiThreadModel, oder CComMultiThreadModelNoCS. Sie können die Thread-Standardmodell des Servers übernehmen, durch Festlegen ThreadModel auf CComObjectThreadModel oder CComGlobalsThreadModel.

Methoden

CComObjectRootExKonstruktor.
InternalAddRefInkrementiert den Verweiszähler für ein nicht zusammengesetztes Objekt.
InternalReleaseDekrementiert den Verweiszähler für ein nicht zusammengesetztes Objekt.
SperrenWenn das Threadmodell multithreaded ist, erhält an einem kritischen Abschnittsobjekt.
EntsperrenWenn das Threadmodell multithreaded ist, gibt Besitz ein kritisches Abschnittsobjekt frei.

CComObjectRootBase-Methoden

FinalConstructIn der Klasse des Objekts erforderlichen Initialisierungen überschreiben.
FinalReleaseÜberschreiben Sie in der Klasse, um alle vom Objekt erforderliche Bereinigung durchzuführen.
OuterAddRefInkrementiert den Verweiszähler für ein zusammengesetztes Objekt.
OuterQueryInterfaceDelegaten des äußeren IUnknown eines zusammengesetzten Objekts.
OuterReleaseDekrementiert den Verweiszähler für ein zusammengesetztes Objekt.

Statische Funktionen

InternalQueryInterfaceDelegiert an die IUnknown eines zusammengesetzten Objekts.
ObjectMainWährend der Initialisierung des Moduls und Beendigung für die abgeleiteten Klassen aufgeführt, die in der objektzuordnung bezeichnet.

Datenmember

m_dwRefMit m_pOuterUnknown, Teil einer Union. Verwendet, wenn das Objekt nicht aggregiert werden, um den Verweiszähler des halten AddRef und Version.
m_pOuterUnknownMit m_dwRef, Teil einer Union. Wird verwendet, wenn das Objekt aggregiert wird, um einen Zeiger auf die äußere unbekannte aufzunehmen.

CComObjectRootExObjekt Verweis Anzahl Management für aggregierte und aggregierten Objekte verarbeitet werden. Sie enthält den Verweiszähler des Objekts, wenn das Objekt wird nicht aggregiert, und den Zeiger auf die äußere unbekannte enthält, wenn das Objekt gerade zusammengesetzt wird. Für aggregierte Objekte CComObjectRootEx Methoden können zum Behandeln des Fehlers des inneren Objekts zu erstellen und zu schützen, das äußere Objekt löschen Wenn innere Schnittstellen freigegeben werden oder das innere Objekt werden gelöscht.

Eine Klasse, die einen COM-Server implementiert Vererben muss CComObjectRootEx oder CComObjectRoot.

Wenn in die Klassendefinition angegeben der DECLARE_POLY_AGGREGATABLE -Makro, ATL erstellt eine Instanz des **CComPolyObject<> </> > ** bei IClassFactory:: CreateInstance aufgerufen wird. Während der Erstellung wird der Wert der äußeren unbekannten überprüft. Ist dies NULL, IUnknown ist für ein nicht zusammengesetztes Objekt implementiert. Wenn die äußere unbekannte nicht NULL, IUnknown für ein zusammengesetztes Objekt implementiert wird.

Wenn die Klasse keine der DECLARE_POLY_AGGREGATABLE -Makro, ATL erstellt eine Instanz des **CAggComObject<> </> > ** für aggregierte Objekte oder eine Instanz von **CComObject<> </> > ** für zusammengesetzten Objekte.

Der Vorteil der Verwendung CComPolyObject besteht darin, dass Sie vermeiden, dass beide CComAggObject und CComObject in Ihrem Modul zusammengefasste und aggregierte behandelt. Ein einzelnes CComPolyObject -Objekt verarbeitet beide Fälle. Aus diesem Grund nur eine Kopie der Vtable und eine Kopie der Funktionen im Modul vorhanden sein. Wenn die Vtable umfangreich ist, kann dies Modulgröße erheblich beeinträchtigen. Wenn die Vtable klein ist, jedoch mithilfe CComPolyObject kann in einem etwas größeren Modul führen, da er nicht für ein Objekt aggregierten oder aggregierte optimiert ist wie CComAggObject und CComObject.

Wenn das Objekt aggregiert wird, IUnknown wird implementiert, indem CComAggObject oder CComPolyObject. Diese Klassen delegieren QueryInterface, AddRef, und Version Aufrufe von CComObjectRootExdes OuterQueryInterface, OuterAddRef, und OuterRelease an die äußere unbekannte weiterleiten. Überschreiben Sie in der Regel CComObjectRootEx::FinalConstruct in Ihrer Klasse keine aggregierten Objekte erstellen, und überschreiben Sie CComObjectRootEx::FinalRelease zusammengefasst Objekte freizugeben.

Wenn das Objekt nicht zusammengesetzt ist, IUnknown wird implementiert, indem CComObject oder CComPolyObject. In diesem Fall die Aufrufe von QueryInterface, AddRef, und Version an delegiert werden CComObjectRootExdes InternalQueryInterface, InternalAddRef, und InternalRelease die tatsächlichen Vorgänge aus.

Header: Standardschnittstellen

Der Konstruktor initialisiert den Verweiszähler auf 0.

CComObjectRootEx();

Sie können diese Methode überschreiben, in der abgeleiteten Klasse ggf. für Ihr Objekt erforderliche Initialisierung ausführen.

HRESULT FinalConstruct();

Rückgabewert

Zurückgeben S_OK auf Erfolg oder ein Standard-Fehler HRESULT Werte.

Hinweise

In der Standardeinstellung CComObjectRootEx::FinalConstruct gibt einfach S_OK.

Es gibt Vorteile bei der Initialisierung in FinalConstruct statt der Konstruktor der Klasse:

  • Sie können nicht von einem Konstruktor gibt einen Statuscode zurück, jedoch kann man eine HRESULT von FinalConstructRückgabewert. Wenn Objekte der Klasse mithilfe der standardmäßigen Klassenfactory von ATL bereitgestellten erstellt werden, wird dieser Rückgabewert zurück an den COM-Client können Sie detaillierte Fehlerinformationen geben weitergegeben.

  • Sie können nicht über den Mechanismus der virtuellen Funktion vom Konstruktor der Klasse virtuelle Funktionen aufrufen. Aufruf einer virtuellen Funktion vom Konstruktor einer Klasse führt einen statisch aufgelösten Aufruf der Funktion, wie sie an diesem Punkt in der Vererbungshierarchie definiert ist. Aufrufe von reinen virtuellen Funktionen Linkerfehler auftreten.

    Die Klasse ist nicht am stärksten abgeleitete Klasse in der Vererbungshierarchie – beruht auf einer abgeleiteten Klasse, die vom ATL, einen Teil der Funktionen bereitzustellen. Besteht eine hohe Wahrscheinlichkeit, die die Initialisierung mithilfe der Funktionen von dieser Klasse (Dies trifft sicherlich Objekte der Klasse müssen zum Aggregieren von anderen Objekten) muss, aber der Konstruktor der Klasse hat keine Möglichkeit, diese Funktionen zugreifen. Der Code zur Erstellung für die Klasse wird ausgeführt, bevor vollständig am stärksten abgeleitete Klasse erstellt wird.

    Allerdings FinalConstruct wird aufgerufen, unmittelbar nach dem am meisten abgeleitete Klasse vollständig und Sie erstellt wird können virtuelle Funktionen aufrufen und die verweiszählung Implementierung ATL

Beispiel

Überschreiben Sie diese Methode in der abgeleiteten Klasse in der Regel CComObjectRootEx erstellen Objekte zusammengefasst. Zum Beispiel:

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.

Wenn es sich bei die Erstellung ein Fehler auftritt, können Sie einen Fehler zurück. Sie können auch das Makro DECLARE_PROTECT_FINAL_CONSTRUCT zu verhindern, dass das äußere Objekt wird gelöscht, wenn während der Erstellung der internen aggregierte-Objekt den Verweiszähler und verringert die Anzahl auf 0 erhöht.

Hier ist üblicherweise ein Aggregat zu erstellen:

  • Hinzufügen einer IUnknown Zeiger auf die Klasse Objekt, und initialisieren Sie es mit NULL im Konstruktor.

  • Überschreiben Sie FinalConstruct das Aggregat zu erstellen.

  • Verwenden der IUnknown Zeiger, die Sie als Parameter definiert die COM_INTERFACE_ENTRY_AGGREGATE Makro.

  • Überschreiben Sie FinalRelease Freigeben der IUnknown Zeiger.

Sie können diese Methode überschreiben, in der abgeleiteten Klasse ggf. für Ihr Objekt erforderliche Bereinigung ausführen.

void FinalRelease();

Hinweise

In der Standardeinstellung CComObjectRootEx::FinalRelease wird keine Aktion ausgeführt.

Ausführen der Bereinigung in FinalRelease empfiehlt sich, den Destruktor der Klasse Code hinzugefügt, da das Objekt weiterhin vollständig an die Stelle, an der erstellt wird FinalRelease aufgerufen wird. Dadurch können Sie problemlos von am stärksten abgeleitete Klasse bereitgestellten Methoden zugreifen. Dies ist besonders wichtig für die Freigabe von aggregierten Objekte vor dem Löschen.

Der Verweiszähler eines zusammengesetzten Objekts erhöht um 1.

ULONG InternalAddRef();

Rückgabewert

Ein Wert, der möglicherweise hilfreich für die Diagnose und testen.

Hinweise

Wenn Sie das Threadmodell Multithreadanwendung, InterlockedIncrement wird verwendet, um zu verhindern, dass mehrere Threads den Verweiszähler gleichzeitig ändern.

Ruft einen Zeiger auf die angeforderte Schnittstelle ab.

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

Parameter

pThis
[in] Ein Zeiger auf das Objekt mit der COM-Zuordnung von Schnittstellen verfügbar gemacht werden, um QueryInterface.

pEntries
[in] Ein Zeiger auf die _ATL_INTMAP_ENTRY -Struktur, die eine Übersicht über die verfügbaren Schnittstellen zugreift.

iid
[in] Die GUID der angeforderten Schnittstelle.

ppvObject
[out] Ein Zeiger auf den Schnittstellenzeiger, der im angegebenen iid, oder NULL Wenn die Schnittstelle nicht gefunden wird.

Rückgabewert

Zu den standardmäßigen HRESULT Werte.

Hinweise

InternalQueryInterfacebehandelt nur Schnittstellen im COM-Zuordnungstabelle. Wenn das Objekt aggregiert wird, InternalQueryInterface wird nicht an die äußere unbekannte delegieren. Sie können die Schnittstellen in der COM-Zuordnungstabelle mit dem Makro eingeben COM_INTERFACE_ENTRY oder einer seiner Varianten.

Dekrementiert den Verweiszähler eines zusammengesetzten Objekts um 1.

ULONG InternalRelease();

Rückgabewert

In beiden nicht-Debugversion und Debugbuilds, diese Funktion gibt einen Wert, der möglicherweise hilfreich für die Diagnose oder testen. Der genaue Wert zurückgegeben wird, hängt von vielen Faktoren ab, wie das Betriebssystem verwendet, und eventuell oder auch nicht, werden die Anzahl der Verweise.

Hinweise

Wenn Sie das Threadmodell Multithreadanwendung, InterlockedDecrement wird verwendet, um zu verhindern, dass mehrere Threads den Verweiszähler gleichzeitig ändern.

Wenn das Threadmodell multithreaded ist, ruft diese Methode die Win32-API-Funktion EnterCriticalSection, welche wartet, bis der Thread den kritischen Abschnittsobjekt Besitz kann über einen privaten Datenmember abgerufen.

void Lock();

Hinweise

Wenn der geschützte Code die Ausführung beendet hat, muss der Thread Aufrufen Unlock den Besitz der den kritischen Abschnitt freigibt.

Wenn das Threadmodell Singlethread ist, bewirkt diese Methode nichts.

Teil einer Union, die vier Byte des Speichers zugreift.

long m_dwRef;

Hinweise

Mit m_pOuterUnknown, Teil einer Union:

union

{

long m_dwRef;

IUnknown* m_pOuterUnknown;

};

Wenn das Objekt nicht zusammengesetzt ist wird, der Verweiszähler zugegriffen AddRef und Version befindet sich in m_dwRef. Wenn das Objekt aggregiert wird, befindet sich der Zeiger auf die äußere unbekannte in M_pOuterUnknown.

Teil einer Union, die vier Byte des Speichers zugreift.

IUnknown*
    m_pOuterUnknown;

Hinweise

Mit m_dwRef, Teil einer Union:

union

{

long m_dwRef;

IUnknown* m_pOuterUnknown;

};

Wenn das Objekt aggregiert wird, befindet sich der Zeiger auf die äußere unbekannte in m_pOuterUnknown. Wenn das Objekt nicht zusammengesetzt ist wird, der Verweiszähler zugegriffen AddRef und Version befindet sich in M_dwRef.

Für jede Klasse aufgelistet, die der objektzuordnung, diese Funktion wird aufgerufen, wenn bei der Initialisierung des Moduls, und erneut beim wird beendet.

static void WINAPI ObjectMain(bool bStarting);

Parameter

bStarting
[out] Der Wert ist true die Klasse initialisiert wird; andernfalls wird false.

Hinweise

Der Wert der bStarting Parameter angibt, ob das Modul initialisiert oder beendet. Die standardmäßige Implementierung des ObjectMain wird keine Aktion ausgeführt, aber Sie können diese Funktion überschreiben, in der Klasse initialisieren oder Bereinigen von Ressourcen, die für die Klasse zugeordnet werden soll. Beachten Sie, dass ObjectMain wird aufgerufen, bevor alle Instanzen der Klasse angefordert werden.

ObjectMainwird von den Einstiegspunkt der DLL aufgerufen damit der Typ der Operation, die die Einstiegspunktfunktion ausführen können, eingeschränkt wird. Weitere Informationen zu diesen Einschränkungen finden Sie unter Verhalten der Laufzeitbibliothek und DllMain.

Beispiel

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.

Inkrementiert den Verweiszähler für die äußere unbekannte einer Aggregation.

ULONG OuterAddRef();

Rückgabewert

Ein Wert, der möglicherweise hilfreich für die Diagnose und testen.

Ruft einen indirekten Zeiger auf die angeforderte Schnittstelle ab.

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

Parameter

iid
[in] Die GUID der angeforderten Schnittstelle.

ppvObject
[out] Ein Zeiger auf den Schnittstellenzeiger, der im angegebenen iid, oder NULL Wenn die Aggregation die Schnittstelle nicht unterstützt.

Rückgabewert

Zu den standardmäßigen HRESULT Werte.

Dekrementiert den Verweiszähler für die äußere unbekannte einer Aggregation.

ULONG OuterRelease();

Rückgabewert

In nicht-Debugbuilds gibt immer 0 zurück. In Debugbuilds gibt einen Wert, der möglicherweise hilfreich für die Diagnose oder testen.

Wenn das Threadmodell multithreaded ist, ruft diese Methode die Win32-API-Funktion LeaveCriticalSection, welche Versionen Besitzrechte Objekt des kritischen Abschnitts über einen privaten Datenmember abgerufen.

void Unlock();

Hinweise

Um den Besitz zu erhalten, muss der Thread Aufrufen Lock. Jeder Aufruf von Lock erfordert einen entsprechenden Aufruf Unlock den Besitz der den kritischen Abschnitt freigibt.

Wenn das Threadmodell Singlethread ist, bewirkt diese Methode nichts.

CComAggObject-Klasse
CComObject-Klasse
CComPolyObject-Klasse
Übersicht über die Klasse

Anzeigen: