Udostępnij za pośrednictwem

Klasa CComEnumImpl

  • Artykuł

Ta klasa udostępnia implementację interfejsu modułu wyliczającego COM, w którym elementy wyliczane są przechowywane w tablicy.

Składnia

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

Parametry

Podstawowej
Interfejs modułu wyliczającego COM. Zobacz przykład IEnumString .

piid
Wskaźnik do identyfikatora interfejsu interfejsu modułu wyliczającego.

T
Typ elementu uwidocznionego przez interfejs modułu wyliczającego.

kopia
Homogeniczną klasę zasad kopiowania.

Członkowie

Konstruktory publiczne

Nazwa/nazwisko opis
CComEnumImpl::CComEnumImpl Konstruktor.
CComEnumImpl::~CComEnumImpl Destruktora.

Metody publiczne

Nazwa/nazwisko opis
CComEnumImpl::Clone Implementacja metody interfejsu Clone enumeration.
CComEnumImpl::Init Inicjuje moduł wyliczający.
CComEnumImpl::Next Implementacja pozycji Dalej.
CComEnumImpl::Reset Implementacja funkcji Reset.
CComEnumImpl::Skip Implementacja pomiń.

Publiczne elementy członkowskie danych

Nazwa/nazwisko opis
CComEnumImpl::m_begin Wskaźnik do pierwszego elementu w tablicy.
CComEnumImpl::m_dwFlags Skopiuj flagi przekazywane za pośrednictwem elementu Init.
CComEnumImpl::m_end Wskaźnik do lokalizacji tuż poza ostatnim elementem w tablicy.
CComEnumImpl::m_iter Wskaźnik do bieżącego elementu w tablicy.
CComEnumImpl::m_spUnk Wskaźnik IUnknown obiektu dostarczającego wyliczenie kolekcji.

Uwagi

Zobacz IEnumString , aby zapoznać się z przykładem implementacji metod. CComEnumImpl Udostępnia implementację interfejsu modułu wyliczającego COM, w którym elementy wyliczane są przechowywane w tablicy. Ta klasa jest analogiczna do IEnumOnSTLImpl klasy, która zapewnia implementację interfejsu modułu wyliczającego opartego na kontenerze biblioteki standardowej języka C++.

Uwaga

Aby uzyskać szczegółowe informacje na temat dalszych różnic między elementami CComEnumImpl i IEnumOnSTLImpl, zobacz CComEnumImpl::Init.

Zazwyczaj nie trzeba tworzyć własnej klasy modułu wyliczającego, wyprowadzając je z tej implementacji interfejsu. Jeśli chcesz użyć modułu wyliczającego dostarczonego przez ATL na podstawie tablicy, częściej tworzy się wystąpienie CComEnum.

Jeśli jednak musisz podać niestandardowy moduł wyliczający (na przykład taki, który uwidacznia interfejsy oprócz interfejsu modułu wyliczającego), możesz pochodzić z tej klasy. W takiej sytuacji prawdopodobnie konieczne będzie zastąpienie metody CComEnumImpl::Clone , aby zapewnić własną implementację.

Aby uzyskać więcej informacji, zobacz Kolekcje i moduły wyliczania ATL.

Hierarchia dziedziczenia

Base

CComEnumImpl

Wymagania

Nagłówek: atlcom.h

CComEnumImpl::CComEnumImpl

Konstruktor.

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

Destruktora.

~CComEnumImpl();

CComEnumImpl::Init

Tę metodę należy wywołać przed przekazaniem wskaźnika do interfejsu modułu wyliczającego z powrotem do wszystkich klientów.

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

Parametry

Rozpocząć
Wskaźnik do pierwszego elementu tablicy zawierającej elementy do wyliczenia.

Końcu
Wskaźnik do lokalizacji tuż poza ostatnim elementem tablicy zawierającej elementy do wyliczenia.

Punk
[in] Wskaźnik IUnknown obiektu, który musi być utrzymywany przy życiu w okresie istnienia modułu wyliczającego. Przekaż wartość NULL, jeśli taki obiekt nie istnieje.

Flagi
Flagi określające, czy moduł wyliczający powinien przejąć własność tablicy, czy utworzyć jego kopię. Poniżej opisano możliwe wartości.

Wartość zwracana

Standardowa wartość HRESULT.

Uwagi

Wywołaj tę metodę tylko raz — zainicjuj moduł wyliczający, użyj go, a następnie odrzuć.

Jeśli przekazujesz wskaźniki do elementów w tablicy przechowywanej w innym obiekcie (i nie pytasz modułu wyliczającego o skopiowanie danych), możesz użyć parametru pUnk , aby upewnić się, że obiekt i tablica, która jest przechowywana, są dostępne tak długo, jak moduł wyliczający ich potrzebuje. Moduł wyliczający po prostu przechowuje odwołanie COM do obiektu, aby zachować jego życie. Odwołanie COM jest automatycznie zwalniane, gdy moduł wyliczający zostanie zniszczony.

Parametr flags umożliwia określenie sposobu, w jaki moduł wyliczający powinien traktować przekazane do niego elementy tablicy. flagi mogą przyjmować jedną z wartości z CComEnumFlags wyliczenia pokazanego poniżej:

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

AtlFlagNoCopy oznacza, że okres istnienia tablicy nie jest kontrolowany przez moduł wyliczający. W takim przypadku tablica będzie statyczna lub obiekt zidentyfikowany przez pUnk będzie odpowiedzialny za zwolnienie tablicy, gdy nie jest już potrzebny.

AtlFlagTakeOwnership oznacza, że zniszczenie tablicy ma być kontrolowane przez moduł wyliczający. W takim przypadku tablica musi zostać dynamicznie przydzielona przy użyciu polecenia new. Moduł wyliczający usunie tablicę w jej destruktorze. Zazwyczaj należy przekazać wartość NULL dla elementu pUnk, chociaż nadal można przekazać prawidłowy wskaźnik, jeśli z jakiegoś powodu musisz otrzymywać powiadomienia o zniszczeniu modułu wyliczającego.

AtlFlagCopy oznacza, że nowa tablica ma zostać utworzona przez skopiowanie tablicy przekazanej do Initklasy . Okres istnienia nowej tablicy ma być kontrolowany przez moduł wyliczający. Moduł wyliczający usunie tablicę w jej destruktorze. Zazwyczaj należy przekazać wartość NULL dla elementu pUnk, chociaż nadal można przekazać prawidłowy wskaźnik, jeśli z jakiegoś powodu musisz otrzymywać powiadomienia o zniszczeniu modułu wyliczającego.

Uwaga

Prototyp tej metody określa elementy tablicy jako typ T, gdzie T został zdefiniowany jako parametr szablonu do klasy. Jest to ten sam typ, który jest udostępniany za pomocą metody interfejsu COM CComEnumImpl::Next. Implikacją tego jest to, że w przeciwieństwie do IEnumOnSTLImpl ta klasa nie obsługuje innego magazynu i uwidocznionych typów danych. Typ danych elementów w tablicy musi być taki sam jak typ danych udostępniany za pomocą interfejsu COM.

CComEnumImpl::Clone

Ta metoda zapewnia implementację metody Clone przez utworzenie obiektu typu CComEnum, zainicjowanie go za pomocą tej samej tablicy i iteratora używanego przez bieżący obiekt oraz zwrócenie interfejsu na nowo utworzonym obiekcie.

STDMETHOD(Clone)(Base** ppEnum);

Parametry

ppEnum
[out] Interfejs modułu wyliczającego na nowo utworzonym obiekcie sklonowanym z bieżącego modułu wyliczającego.

Wartość zwracana

Standardowa wartość HRESULT.

Uwagi

Należy pamiętać, że sklonowane moduły wyliczające nigdy nie tworzą własnej kopii (lub przejęcia własności) danych używanych przez oryginalny moduł wyliczający. W razie potrzeby sklonowane moduły wyliczające zachowają oryginalny moduł wyliczający przy użyciu odwołania COM, aby upewnić się, że dane są dostępne tak długo, jak ich potrzebują.

CComEnumImpl::m_spUnk

Ten inteligentny wskaźnik utrzymuje odwołanie do obiektu przekazanego do obiektu CComEnumImpl::Init, zapewniając, że pozostaje żywy w okresie istnienia modułu wyliczającego.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Wskaźnik do lokalizacji tuż poza ostatnim elementem tablicy zawierającej elementy do wyliczenia.

T* m_begin;

CComEnumImpl::m_end

Wskaźnik do pierwszego elementu tablicy zawierającej elementy do wyliczenia.

T* m_end;

CComEnumImpl::m_iter

Wskaźnik do bieżącego elementu tablicy zawierającej elementy do wyliczenia.

T* m_iter;

CComEnumImpl::m_dwFlags

Flagi przekazane do CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

Ta metoda zapewnia implementację metody Next .

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

Parametry

Celt
[in] Liczba żądanych elementów.

rgelt
[out] Tablica do wypełnienia elementami.

pceltFetched
[out] Liczba elementów rzeczywiście zwróconych w rgelt. Może to być mniej niż celt, jeśli na liście pozostało mniej niż elementy celt.

Wartość zwracana

Standardowa wartość HRESULT.

CComEnumImpl::Reset

Ta metoda zapewnia implementację metody Reset .

STDMETHOD(Reset)(void);

Wartość zwracana

Standardowa wartość HRESULT.

CComEnumImpl::Skip

Ta metoda zapewnia implementację metody Skip .

STDMETHOD(Skip)(ULONG celt);

Parametry

Celt
[in] Liczba elementów do pominięcia.

Wartość zwracana

Standardowa wartość HRESULT.

Uwagi

Zwraca wartość E_INVALIDARG, jeśli celt ma wartość zero, zwraca wartość S_FALSE, jeśli zwracane są elementy celt , zwraca wartość S_OK w przeciwnym razie.

Zobacz też

Klasa IEnumOnSTLImpl
Klasa CComEnum
Omówienie klasy