CComEnumImpl – třída
Tato třída poskytuje implementaci pro rozhraní enumerátoru COM, kde jsou položky výčtu uloženy v poli.
Syntaxe
template <class Base,
const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base
Parametry
Základna
Rozhraní enumerátoru COM. Příklad najdete v souboru IEnumString .
piid
Ukazatel na ID rozhraní enumerátoru.
T
Typ položky vystavené rozhraním enumerátoru.
Kopírování
Homogenní třída zásad kopírování.
Členové
Veřejné konstruktory
| Název | Popis |
|---|---|
| CComEnumImpl::CComEnumImpl | Konstruktor |
| CComEnumImpl::~CComEnumImpl | Destruktor. |
Veřejné metody
| Název | Popis |
|---|---|
| CComEnumImpl::Clone | Implementace klonovací metody rozhraní výčtu. |
| CComEnumImpl::Init | Inicializuje enumerátor. |
| CComEnumImpl::Next | Implementace dalšího. |
| CComEnumImpl::Reset | Implementace resetování. |
| CComEnumImpl::Skip | Implementace skipu. |
Veřejné datové členy
| Název | Popis |
|---|---|
| CComEnumImpl::m_begin | Ukazatel na první položku v poli. |
| CComEnumImpl::m_dwFlags | Zkopírujte příznaky předané .Init |
| CComEnumImpl::m_end | Ukazatel na umístění za poslední položkou v poli. |
| CComEnumImpl::m_iter | Ukazatel na aktuální položku v poli. |
| CComEnumImpl::m_spUnk | Ukazatel IUnknown objektu poskytujícího kolekci výčtu. |
Poznámky
Příklad implementace metod najdete v souboru IEnumString . CComEnumImpl poskytuje implementaci pro enumerátor com rozhraní, kde jsou položky výčtu uloženy v poli. Tato třída je analogická ke IEnumOnSTLImpl třídě, která poskytuje implementaci rozhraní enumerátoru založeného na kontejneru standardní knihovny jazyka C++.
Poznámka:
Podrobnosti o dalších rozdílech mezi CComEnumImpl a IEnumOnSTLImpl, viz CComEnumImpl::Init.
Obvykle nebudete muset vytvořit vlastní enumerator třídy odvozené z této implementace rozhraní. Pokud chcete použít enumerátor atL zadaný na základě pole, je častější vytvořit instanci CComEnum.
Pokud však potřebujete poskytnout vlastní enumerátor (například ten, který zveřejňuje rozhraní kromě rozhraní enumerátoru), můžete odvodit z této třídy. V této situaci je pravděpodobné, že budete muset přepsat CComEnumImpl::Clone metoda poskytnout vlastní implementaci.
Další informace naleznete v tématu ATL Collections and Enumerators.
Hierarchie dědičnosti
Base
CComEnumImpl
Požadavky
Hlavička: atlcom.h
CComEnumImpl::CComEnumImpl
Konstruktor
CComEnumImpl();
CComEnumImpl::~CComEnumImpl
Destruktor.
~CComEnumImpl();
CComEnumImpl::Init
Před předáním ukazatele na rozhraní enumerátoru zpět všem klientům musíte tuto metodu volat.
HRESULT Init(
T* begin,
T* end,
IUnknown* pUnk,
CComEnumFlags flags = AtlFlagNoCopy);
Parametry
začít
Ukazatel na první prvek pole obsahující položky, které mají být výčty.
konec
Ukazatel na umístění těsně za posledním prvkem pole obsahujícího položky, které mají být výčty.
punk
[v] Ukazatel IUnknown objektu, který musí být udržován naživu během životnosti enumerátoru. Pokud takový objekt neexistuje, předejte hodnotu NULL.
vlajky
Příznaky určující, zda má enumerátor převzít vlastnictví pole nebo vytvořit jeho kopii. Možné hodnoty jsou popsány níže.
Návratová hodnota
Standardní hodnota HRESULT.
Poznámky
Tuto metodu zavolejte pouze jednou – inicializujete enumerátor, použijete ji a pak ji vyhodíte.
Pokud předáte ukazatele na položky v poli uchovávaném v jiném objektu (a neptáte se enumerátoru, aby zkopíroval data), můžete pomocí parametru pUnk zajistit, aby objekt a pole, které obsahuje, byly k dispozici tak dlouho, dokud je enumerátor potřebuje. Enumerátor jednoduše uchovává odkaz MODELU COM na objekt, aby byl aktivní. Odkaz modelu COM se automaticky uvolní při zničení enumerátoru.
Parametr flags umožňuje určit, jak má enumerátor zacházet s prvky pole předanými do něj. Příznaky můžou mít jednu z hodnot z výčtu CComEnumFlags uvedeného níže:
enum CComEnumFlags
{
AtlFlagNoCopy = 0,
AtlFlagTakeOwnership = 2, // BitOwn
AtlFlagCopy = 3 // BitOwn | BitCopy
};
AtlFlagNoCopy znamená, že životnost pole není řízena enumerátorem. V tomto případě bude pole statické nebo objekt identifikovaný pomocí pUnk bude zodpovědný za uvolnění pole, když už není potřeba.
AtlFlagTakeOwnership znamená, že zničení pole je řízeno enumerátorem. V tomto případě musí být pole dynamicky přiděleno pomocí new. Enumerátor odstraní pole v jeho destruktoru. Obvykle byste předali hodnotu NULL pro pUnk, i když stále můžete předat platný ukazatel, pokud potřebujete být upozorněni na zničení enumerátoru z nějakého důvodu.
AtlFlagCopy znamená, že se vytvoří nové pole zkopírováním pole předaného do Init. Životnost nového pole je řízena enumerátorem. Enumerátor odstraní pole v jeho destruktoru. Obvykle byste předali hodnotu NULL pro pUnk, i když stále můžete předat platný ukazatel, pokud potřebujete být upozorněni na zničení enumerátoru z nějakého důvodu.
Poznámka:
Prototyp této metody určuje prvky pole jako typ T, kde T byl definován jako parametr šablony třídy. Jedná se o stejný typ, který je vystaven prostřednictvím metody rozhraní COM CComEnumImpl::Next. Implikací tohoto je, že na rozdíl od IEnumOnSTLImpl tato třída nepodporuje různé typy úložiště a vystavené datové typy. Datový typ prvků v poli musí být stejný jako datový typ vystavený prostřednictvím rozhraní MODELU COM.
CComEnumImpl::Clone
Tato metoda poskytuje implementaci Clone metoda vytvořením objektu typu CComEnum, inicializace pomocí stejného pole a iterátoru používaného aktuálním objektem a vrácení rozhraní na nově vytvořeném objektu.
STDMETHOD(Clone)(Base** ppEnum);
Parametry
ppEnum
[ven] Rozhraní enumerátoru na nově vytvořeném objektu klonovaném z aktuálního enumerátoru.
Návratová hodnota
Standardní hodnota HRESULT.
Poznámky
Všimněte si, že klonované enumerátory nikdy netvořily vlastní kopii (nebo převzít vlastnictví) dat používaných původním enumerátorem. V případě potřeby budou klonované enumerátory udržovat původní enumerátor aktivní (pomocí odkazu modelu COM), aby bylo zajištěno, že data budou k dispozici, dokud je potřebují.
CComEnumImpl::m_spUnk
Tento inteligentní ukazatel udržuje odkaz na objekt předaný CComEnumImpl::Init a zajišťuje, aby zůstal aktivní během životnosti enumerátoru.
CComPtr<IUnknown> m_spUnk;
CComEnumImpl::m_begin
Ukazatel na umístění těsně za posledním prvkem pole obsahujícího položky, které mají být výčty.
T* m_begin;
CComEnumImpl::m_end
Ukazatel na první prvek pole obsahující položky, které mají být výčty.
T* m_end;
CComEnumImpl::m_iter
Ukazatel na aktuální prvek pole obsahující položky, které mají být výčty.
T* m_iter;
CComEnumImpl::m_dwFlags
Příznaky předané CComEnumImpl::Init.
DWORD m_dwFlags;
CComEnumImpl::Next
Tato metoda poskytuje implementaci další metody.
STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);
Parametry
Kelt
[v] Požadovaný počet prvků.
rgelt
[ven] Pole, které má být vyplněno prvky.
pceltFetched
[ven] Počet prvků vrácených v rgeltu. To může být menší než celt , pokud méně než celt prvky zůstaly v seznamu.
Návratová hodnota
Standardní hodnota HRESULT.
CComEnumImpl::Reset
Tato metoda poskytuje implementaci metody Reset .
STDMETHOD(Reset)(void);
Návratová hodnota
Standardní hodnota HRESULT.
CComEnumImpl::Skip
Tato metoda poskytuje implementaci metody Skip .
STDMETHOD(Skip)(ULONG celt);
Parametry
Kelt
[v] Počet prvků, které se mají přeskočit.
Návratová hodnota
Standardní hodnota HRESULT.
Poznámky
Vrátí E_INVALIDARG pokud je celt nula, vrátí S_FALSE pokud jsou vráceny menší než celt prvky, vrátí S_OK jinak.