CComEnumImpl-Klasse

Diese Klasse stellt die Implementierung für eine COM-Enumeratorschnittstelle bereit, in der die aufgezählten Elemente in einem Array gespeichert werden.

Syntax

template <class Base,
    const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base

Parameter

Bemessungsgrundlage
Eine COM-Enumerationsschnittstelle. Ein Beispiel finden Sie unter "IEnumString ".

piid
Ein Zeiger auf die Schnittstellen-ID der Enumeratorschnittstelle.

T
Der Typ des Elements, der von der Enumerationsschnittstelle verfügbar gemacht wird.

Kopieren
Eine homogene Kopierrichtlinienklasse.

Member

Öffentliche Konstruktoren

Name	Beschreibung
CComEnumImpl::CComEnumImpl	Der Konstruktor.
CComEnumImpl::~CComEnumImpl	Der Destruktor.

Öffentliche Methoden

Name	Beschreibung
CComEnumImpl::Clone	Die Implementierung der Clone-Enumerationsschnittstellenmethode .
CComEnumImpl::Init	Initialisiert den Enumerator.
CComEnumImpl::Next	Die Implementierung von Next.
CComEnumImpl::Reset	Die Implementierung von Reset.
CComEnumImpl::Skip	Die Implementierung von Skip.

Öffentliche Datenmember

Name	Beschreibung
CComEnumImpl::m_begin	Ein Zeiger auf das erste Element im Array.
CComEnumImpl::m_dwFlags	Kopieren von Flags, die durchgestrichen Initwerden.
CComEnumImpl::m_end	Ein Zeiger auf die Position direkt über das letzte Element im Array hinaus.
CComEnumImpl::m_iter	Ein Zeiger auf das aktuelle Element im Array.
CComEnumImpl::m_spUnk	Der IUnknown Zeiger des Objekts, das die Auflistung aufzählt.

Hinweise

Ein Beispiel für Methodenimplementierungen finden Sie unter IEnumString . CComEnumImpl stellt die Implementierung für eine COM-Enumeratorschnittstelle bereit, bei der die aufgezählten Elemente in einem Array gespeichert werden. Diese Klasse entspricht der IEnumOnSTLImpl Klasse, die eine Implementierung einer Enumeratorschnittstelle basierend auf einem C++-Standardbibliothekscontainer bereitstellt.

Hinweis

Ausführliche Informationen zu weiteren Unterschieden zwischen CComEnumImpl und IEnumOnSTLImpl, finden Sie unter CComEnumImpl::Init.

In der Regel müssen Sie keine eigene Enumerationsklasse erstellen, indem Sie von dieser Schnittstellenimplementierung abgeleitet werden. Wenn Sie einen ATL-bereitgestellten Enumerator verwenden möchten, der auf einem Array basiert, ist es häufiger, eine Instanz von CComEnum zu erstellen.

Wenn Sie jedoch einen benutzerdefinierten Enumerator bereitstellen müssen (z. B. eine, die Schnittstellen zusätzlich zur Enumeratorschnittstelle verfügbar macht), können Sie von dieser Klasse abgeleitet werden. In dieser Situation ist es wahrscheinlich, dass Sie die CComEnumImpl::Clone-Methode überschreiben müssen, um Ihre eigene Implementierung bereitzustellen.

Weitere Informationen finden Sie unter ATL-Auflistungen und Enumerationen.

Vererbungshierarchie

Base

CComEnumImpl

Anforderungen

Kopfzeile: atlcom.h

CComEnumImpl::CComEnumImpl

Der Konstruktor.

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

Der Destruktor.

~CComEnumImpl();

CComEnumImpl::Init

Sie müssen diese Methode aufrufen, bevor Sie einen Zeiger an die Enumeratorschnittstelle an alle Clients übergeben.

HRESULT Init(
    T* begin,
    T* end,
    IUnknown* pUnk,
    CComEnumFlags flags = AtlFlagNoCopy);

Parameter

begin
Ein Zeiger auf das erste Element des Arrays, das die elemente enthält, die aufgezählt werden sollen.

end
Ein Zeiger auf die Position direkt über das letzte Element des Arrays, das die elemente enthält, die aufgezählt werden sollen.

Punk
[in] Der IUnknown Zeiger eines Objekts, das während der Lebensdauer des Enumerators lebendig gehalten werden muss. Übergeben Sie NULL, wenn kein solches Objekt vorhanden ist.

flags
Flags, die angeben, ob der Enumerator den Besitz des Arrays übernehmen oder eine Kopie davon erstellen soll. Mögliche Werte werden unten beschrieben.

Rückgabewert

Ein HRESULT-Standardwert.

Hinweise

Rufen Sie diese Methode nur einmal auf – initialisieren Sie den Enumerator, verwenden Sie sie, und lösen Sie sie dann weg.

Wenn Sie Zeiger an Elemente in einem Array übergeben, das in einem anderen Objekt enthalten ist (und Sie den Enumerator nicht auffordern, die Daten zu kopieren), können Sie den pUnk-Parameter verwenden, um sicherzustellen, dass das Objekt und das Array, das es enthält, verfügbar sind, solange der Enumerator sie benötigt. Der Enumerator enthält einfach einen COM-Verweis auf das Objekt, um ihn lebendig zu halten. Der COM-Verweis wird automatisch freigegeben, wenn der Enumerator zerstört wird.

Mit dem Flags-Parameter können Sie angeben, wie der Enumerator die an sie übergebenen Arrayelemente behandeln soll. Flags können einen der Werte aus der CComEnumFlags unten gezeigten Aufzählung annehmen:

enum CComEnumFlags
   {
   AtlFlagNoCopy = 0,
   AtlFlagTakeOwnership = 2, // BitOwn
   AtlFlagCopy = 3           // BitOwn | BitCopy
   };

AtlFlagNoCopy bedeutet, dass die Lebensdauer des Arrays nicht vom Enumerator gesteuert wird. In diesem Fall ist entweder das Array statisch, oder das von pUnk identifizierte Objekt ist dafür verantwortlich, das Array freizuweisen, wenn es nicht mehr benötigt wird.

AtlFlagTakeOwnership bedeutet, dass die Zerstörung des Arrays durch den Enumerator gesteuert werden soll. In diesem Fall muss das Array dynamisch mit newzugewiesen worden sein. Der Enumerator löscht das Array in seinem Destruktor. In der Regel übergeben Sie NULL für pUnk, obwohl Sie einen gültigen Zeiger weiterhin übergeben können, wenn Sie aus irgendeinem Grund über die Vernichtung des Enumerators benachrichtigt werden müssen.

AtlFlagCopy bedeutet, dass ein neues Array erstellt werden soll, indem das array kopiert wird, an Initdas übergeben wird. Die Lebensdauer des neuen Arrays soll vom Enumerator gesteuert werden. Der Enumerator löscht das Array in seinem Destruktor. In der Regel übergeben Sie NULL für pUnk, obwohl Sie einen gültigen Zeiger weiterhin übergeben können, wenn Sie aus irgendeinem Grund über die Vernichtung des Enumerators benachrichtigt werden müssen.

Hinweis

Der Prototyp dieser Methode gibt die Arrayelemente als Typ Tan, wobei T sie als Vorlagenparameter für die Klasse definiert wurde. Dies ist derselbe Typ, der mithilfe der COM-Schnittstellenmethode CComEnumImpl::Next verfügbar gemacht wird. Im Gegensatz zu IEnumOnSTLImpl unterstützt diese Klasse keine unterschiedlichen Speicher- und verfügbar gemachten Datentypen. Der Datentyp der Elemente im Array muss mit dem Datentyp übereinstimmen, der über die COM-Schnittstelle verfügbar gemacht wird.

CComEnumImpl::Clone

Diese Methode stellt die Implementierung der Clone-Methode bereit, indem ein Objekt vom Typ CComEnumerstellt wird, initialisiert es mit demselben Array und iterator, das vom aktuellen Objekt verwendet wird, und die Schnittstelle für das neu erstellte Objekt zurückgegeben wird.

STDMETHOD(Clone)(Base** ppEnum);

Parameter

ppEnum
[out] Die Enumerationsschnittstelle für ein neu erstelltes Objekt, das vom aktuellen Enumerator geklont wurde.

Rückgabewert

Ein HRESULT-Standardwert.

Hinweise

Beachten Sie, dass geklonte Enumeratoren niemals ihre eigene Kopie (oder den Besitz übernehmen) der Daten erstellen, die vom ursprünglichen Enumerator verwendet werden. Bei Bedarf behalten geklonte Enumeratoren den ursprünglichen Enumerator am Leben (unter Verwendung eines COM-Verweises), um sicherzustellen, dass die Daten so lange verfügbar sind, wie sie sie benötigen.

CComEnumImpl::m_spUnk

Dieser intelligente Zeiger verwaltet einen Verweis auf das objekt, das an CComEnumImpl::Init übergeben wird, um sicherzustellen, dass es während der Lebensdauer des Enumerators lebendig bleibt.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Ein Zeiger auf die Position direkt über das letzte Element des Arrays, das die elemente enthält, die aufgezählt werden sollen.

T* m_begin;

CComEnumImpl::m_end

Ein Zeiger auf das erste Element des Arrays, das die elemente enthält, die aufgezählt werden sollen.

T* m_end;

CComEnumImpl::m_iter

Ein Zeiger auf das aktuelle Element des Arrays, das die elemente enthält, die aufgezählt werden sollen.

T* m_iter;

CComEnumImpl::m_dwFlags

Die an CComEnumImpl::Init übergebenen Flags.

DWORD m_dwFlags;

CComEnumImpl::Next

Diese Methode stellt die Implementierung der Next-Methode bereit.

STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);

Parameter

celt
[in] Die Anzahl der angeforderten Elemente.

rgelt
[out] Das Array, das mit den Elementen gefüllt werden soll.

pceltFetched
[out] Die Anzahl der Elemente, die tatsächlich in rgelt zurückgegeben wurden. Dies kann kleiner als Zölte sein, wenn weniger als Keltenelemente in der Liste verblieben sind.

Rückgabewert

Ein HRESULT-Standardwert.

CComEnumImpl::Reset

Diese Methode stellt die Implementierung der Reset-Methode bereit.

STDMETHOD(Reset)(void);

Rückgabewert

Ein HRESULT-Standardwert.

CComEnumImpl::Skip

Diese Methode stellt die Implementierung der Skip-Methode bereit.

STDMETHOD(Skip)(ULONG celt);

Parameter

celt
[in]: Die Anzahl der zu überspringenden Elemente.

Rückgabewert

Ein HRESULT-Standardwert.

Hinweise

Gibt E_INVALIDARG zurück, wenn Celt null ist, gibt S_FALSE zurück, wenn weniger als Keltenelemente zurückgegeben werden, andernfalls S_OK zurück.

Siehe auch

IEnumOnSTLImpl-Klasse
CComEnum-Klasse
Klassenübersicht