Classe CComEnumImpl

Essa classe fornece a implementação de uma interface de enumerador do COM em que os itens que estão sendo enumerados são armazenados em uma matriz.

Sintaxe

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

Parâmetros

Base
Uma interface de enumerador do COM. Consulte IEnumString para obter um exemplo.

piid
Um ponteiro para a ID da interface do enumerador.

T
O tipo de item exposto pela interface do enumerador.

Copy
Uma classe de política de cópia homogênea.

Membros

Construtores públicos

Nome	Descrição
CComEnumImpl::CComEnumImpl	O construtor .
CComEnumImpl::~CComEnumImpl	O destruidor.

Métodos públicos

Nome	Descrição
CComEnumImpl::Clone	A implementação do método de interface de enumeração Clone.
CComEnumImpl::Init	Inicializa o enumerador.
CComEnumImpl::Next	A implementação de Next.
CComEnumImpl::Reset	A implementação de Reset.
CComEnumImpl::Skip	A implementação de Skip.

Membros de Dados Públicos

Nome	Descrição
CComEnumImpl::m_begin	Um ponteiro para o primeiro item da matriz.
CComEnumImpl::m_dwFlags	Copiar sinalizadores passados por Init.
CComEnumImpl::m_end	Um ponteiro para o local logo após o último item da matriz.
CComEnumImpl::m_iter	Um ponteiro para o item atual na matriz.
CComEnumImpl::m_spUnk	O ponteiro IUnknown do objeto que fornece a coleção que está sendo enumerada.

Comentários

Confira IEnumString para obter um exemplo das implementações do método. A CComEnumImpl fornece a implementação de uma interface de enumerador do COM em que os itens que estão sendo enumerados são armazenados em uma matriz. Essa classe é análoga à classe IEnumOnSTLImpl, que fornece uma implementação de uma interface de enumerador com base em um contêiner da Biblioteca Padrão do C++.

Observação

Para obter detalhes sobre outras diferenças entre CComEnumImpl e IEnumOnSTLImpl, confira CComEnumImpl::Init.

Normalmente, você não precisará criar sua própria classe de enumerador derivando dessa implementação de interface. Se você quiser usar um enumerador fornecido pela ATL com base em uma matriz, o mais comum será criar uma instância de CComEnum.

No entanto, se você precisar oferecer um enumerador personalizado (por exemplo, um que exponha interfaces além da interface do enumerador), poderá derivar dessa classe. Nessa situação, é provável que você precise substituir o método CComEnumImpl::Clone para fornecer sua própria implementação.

Para obter mais informações, confira Enumeradores e Coleções da ATL.

Hierarquia de herança

Base

CComEnumImpl

Requisitos

Cabeçalho: atlcom.h

CComEnumImpl::CComEnumImpl

O construtor .

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

O destruidor.

~CComEnumImpl();

CComEnumImpl::Init

Você precisa chamar esse método antes de passar um ponteiro para a interface do enumerador de volta para qualquer cliente.

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

Parâmetros

begin
Um ponteiro para o primeiro elemento da matriz que contém os itens a serem enumerados.

end
Um ponteiro para o local logo após o último elemento da matriz que contém os itens a serem enumerados.

pUnk
[entrada] O ponteiro IUnknown de um objeto que deve ser mantido ativo durante o tempo de vida do enumerador. Passe NULL se nenhum objeto desse tipo existir.

sinalizadores
Sinalizadores que especificam se o enumerador deve ou não assumir a propriedade da matriz ou fazer uma cópia dela. Os valores possíveis estão descritos abaixo.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Chame esse método apenas uma vez: inicialize o enumerador, use-o e, em seguida, descarte-o.

Se você passar ponteiros para itens em uma matriz mantida em outro objeto (e não pedir ao enumerador para copiar os dados), poderá usar o parâmetro pUnk para garantir que o objeto e a matriz que ele contém fiquem disponíveis enquanto o enumerador precisar deles. O enumerador simplesmente mantém uma referência do COM no objeto para mantê-lo ativo. A referência do COM é liberada automaticamente quando o enumerador é destruído.

O parâmetro flags permite especificar como o enumerador deve tratar os elementos da matriz passados para ele. o flags pode receber um dos valores da enumeração CComEnumFlags mostrada abaixo:

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

AtlFlagNoCopy significa que o tempo de vida da matriz não é controlado pelo enumerador. Nesse caso, a matriz será estática ou o objeto identificado pelo pUnk será responsável por liberar a matriz quando ela não for mais necessária.

AtlFlagTakeOwnership significa que a destruição da matriz não é controlada pelo enumerador. Nesse caso, a matriz deverá ter sido alocada dinamicamente usando new. O enumerador excluirá a matriz em seu destruidor. Normalmente, você passaria NULL para pUnk, embora ainda possa passar um ponteiro válido se precisar ser notificado sobre a destruição do enumerador por algum motivo.

AtlFlagCopy significa que uma nova matriz deve ser criada copiando a matriz passada para Init. O tempo de vida da nova matriz deve ser controlado pelo enumerador. O enumerador excluirá a matriz em seu destruidor. Normalmente, você passaria NULL para pUnk, embora ainda possa passar um ponteiro válido se precisar ser notificado sobre a destruição do enumerador por algum motivo.

Observação

O protótipo desse método especifica os elementos da matriz como sendo do tipo T, em que T foi definido como um parâmetro de modelo para a classe. Esse é o mesmo tipo que é exposto por meio do método de interface do COM CComEnumImpl::Next. A implicação disso é que, ao contrário da IEnumOnSTLImpl, essa classe não dá suporte a diferentes tipos de armazenamento e dados expostos. O tipo de dados de elementos na matriz deve ser o mesmo que o tipo de dados exposto por meio da interface do COM.

CComEnumImpl::Clone

Esse método fornece a implementação do método Clone criando um objeto de tipo CComEnum, inicializando-o com a mesma matriz e iterador usados pelo objeto atual e retornando a interface no objeto recém-criado.

STDMETHOD(Clone)(Base** ppEnum);

Parâmetros

ppEnum
[saída] A interface do enumerador em um objeto recém-criado clonado do enumerador atual.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Observe que os enumeradores clonados nunca fazem sua própria cópia (nem assumem a propriedade) dos dados usados pelo enumerador original. Se necessário, os enumeradores clonados manterão o enumerador original ativo (usando uma referência do COM) para garantir que os dados fiquem disponíveis enquanto forem necessários.

CComEnumImpl::m_spUnk

Esse ponteiro inteligente mantém uma referência no objeto passado para CComEnumImpl::Init, garantindo que ele permaneça ativo durante o tempo de vida do enumerador.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Um ponteiro para o local logo após o último elemento da matriz que contém os itens a serem enumerados.

T* m_begin;

CComEnumImpl::m_end

Um ponteiro para o primeiro elemento da matriz que contém os itens a serem enumerados.

T* m_end;

CComEnumImpl::m_iter

Um ponteiro para o elemento atual da matriz que contém os itens a serem enumerados.

T* m_iter;

CComEnumImpl::m_dwFlags

Os sinalizadores passados para CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

Esse método fornece a implementação do método Next.

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

Parâmetros

celt
[entrada] O número de elementos solicitados.

rgelt
[saída] A matriz a ser preenchida com os elementos.

pceltBuscado
[saída] O número de elementos realmente retornados no rgelt. Este poderá ser menor que celt se menos elementos de celt permanecerem na lista.

Valor de retorno

Um valor HRESULT padrão.

CComEnumImpl::Reset

Esse método fornece a implementação do método Reset.

STDMETHOD(Reset)(void);

Valor de retorno

Um valor HRESULT padrão.

CComEnumImpl::Skip

Esse método fornece a implementação do método Skip.

STDMETHOD(Skip)(ULONG celt);

Parâmetros

celt
[entrada] O número de elementos a serem ignorados.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Retorna E_INVALIDARG se celt for zero, retornará S_FALSE se menos de elementos de celt forem retornados; caso contrário, retornará S_OK.

Confira também

Classe IEnumOnSTLImpl
Classe CComEnum
Visão geral da aula