Classe CComEnumImpl

Observação

A Active Template Library (ATL) continua a ser suportada. No entanto, já não estamos a adicionar funcionalidades nem a atualizar a documentação.

Esta classe fornece a implementação para uma interface de enumerador COM, onde os itens a enumerar são armazenados num array.

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 COM. Veja IEnumString para um exemplo.

Piid
Um apontador para o 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	Description
CComEnumImpl::CComEnumImpl	O construtor.
CComEnumImpl::~CComEnumImpl	O destruidor.

Métodos Públicos

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

Membros de Dados Públicos

Nome	Description
CComEnumImpl::m_begin	Um apontador para o primeiro item do array.
CComEnumImpl::m_dwFlags	Os flags de cópia passaram por Init.
CComEnumImpl::m_end	Um apontador para o local logo após o último item do array.
CComEnumImpl::m_iter	Um apontador para o item atual no array.
CComEnumImpl::m_spUnk	O IUnknown ponteiro do objeto que fornece a coleção a ser enumerado.

Observações

Veja IEnumString para um exemplo de implementações de métodos. CComEnumImpl fornece a implementação de uma interface de enumerador COM, onde os itens a enumerar são armazenados num array. Esta classe é análoga à IEnumOnSTLImpl classe, que fornece uma implementação de uma interface enumeradora baseada num contentor de Biblioteca Padrão em C++.

Observação

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

Normalmente, não será necessário criar a sua própria classe de enumerador ao derivar desta implementação de interface. Se quiser usar um enumerador fornecido por ATL baseado num array, é mais comum criar uma instância de CComEnum.

No entanto, se precisar de fornecer um enumerador personalizado (por exemplo, um que exponha interfaces além da interface do enumerador), pode derivar desta classe. Nesta situação, é provável que precise de sobrescrever o método CComEnumImpl::Clone para fornecer a sua própria implementação.

Para mais informações, consulte Coleções e Enumeradores ATL.

Hierarquia de herança

Base

CComEnumImpl

Requerimentos

Cabeçalho: atlcom.h

CComEnumImpl::CComEnumImpl

O construtor.

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

O destruidor.

~CComEnumImpl();

CComEnumImpl::Init

Deve chamar este método antes de passar um ponteiro para a interface do enumerador de volta a qualquer cliente.

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

Parâmetros

começar
Um apontador para o primeiro elemento do array que contém os itens a enumerar.

fim
Um ponteiro para a localização logo após o último elemento do array que contém os itens a enumerar.

pUnk
[dentro] O IUnknown indicador de um objeto que deve ser mantido vivo durante a vida do enumerador. Passe NULL se tal objeto não existir.

flags
Flags que especificam se o enumerador deve assumir a propriedade do array ou fazer uma cópia dele. Os valores possíveis são descritos abaixo.

Valor de retorno

Um valor HRESULT padrão.

Observações

Chama este método apenas uma vez — inicializa o enumerador, usa-o e depois deita-o fora.

Se passar ponteiros para itens num array guardado noutro objeto (e não pedir ao enumerador para copiar os dados), pode usar o parâmetro pUnk para garantir que o objeto e o array que ele contém estão disponíveis pelo tempo que o enumerador precisar. O enumerador simplesmente mantém uma referência COM no objeto para o manter vivo. A referência COM é automaticamente libertada quando o enumerador é destruído.

O parâmetro flags permite-lhe especificar como o enumerador deve tratar os elementos do array que lhe são passados. Os flags podem assumir um dos valores da CComEnumFlags enumeração mostrada abaixo:

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

AtlFlagNoCopy significa que a vida útil do array não é controlada pelo enumerador. Neste caso, ou o array será estático ou o objeto identificado pelo pUnk será responsável por libertar o array quando já não for necessário.

AtlFlagTakeOwnership significa que a destruição do array será controlada pelo enumerador. Neste caso, o array deve ter sido alocado dinamicamente usando new. O enumerador elimina o array no seu destruidor. Normalmente, passarias NULL para pUnk, embora ainda possas passar um ponteiro válido se precisares de ser notificado da destruição do enumerador por algum motivo.

AtlFlagCopy significa que um novo array deve ser criado copiando o array passado para Init. A vida útil da nova matriz será controlada pelo recenseador. O enumerador elimina o array no seu destruidor. Normalmente, passarias NULL para pUnk, embora ainda possas passar um ponteiro válido se precisares de ser notificado da destruição do enumerador por algum motivo.

Observação

O protótipo deste método especifica os elementos do array como sendo do tipo T, onde T foi definido como parâmetro modelo para a classe. Este é o mesmo tipo que é exposto através do método de interface COM CComEnumImpl::Next. A implicação disto é que, ao contrário do IEnumOnSTLImpl, esta classe não suporta diferentes tipos de armazenamento e dados expostos. O tipo de dados dos elementos no array deve ser o mesmo do tipo de dado exposto através da interface COM.

CComEnumImpl::Clone

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

STDMETHOD(Clone)(Base** ppEnum);

Parâmetros

ppEnum
[fora] A interface do enumerador num objeto recém-criado clonado a partir do enumerador atual.

Valor de retorno

Um valor HRESULT padrão.

Observações

Note que os enumeradores clonados nunca fazem a sua própria cópia (nem assumem a propriedade) dos dados usados pelo enumerador original. Se necessário, os enumeradores clonados manterão o recenseador original ativo (usando uma referência COM) para garantir que os dados estejam disponíveis durante o tempo que precisarem.

CComEnumImpl::m_spUnk

Este ponteiro inteligente mantém uma referência no objeto passado para CComEnumImpl::Init, garantindo que este permanece vivo durante a vida útil do enumerador.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Um ponteiro para a localização logo após o último elemento do array que contém os itens a enumerar.

T* m_begin;

CComEnumImpl::m_end

Um apontador para o primeiro elemento do array que contém os itens a enumerar.

T* m_end;

CComEnumImpl::m_iter

Um apontador para o elemento atual do array que contém os itens a enumerar.

T* m_iter;

CComEnumImpl::m_dwFlags

As bandeiras passaram para CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

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

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

Parâmetros

Celta
[dentro] O número de elementos pedidos.

rgelt
[fora] A matriz será preenchida com os elementos.

pceltFetched
[fora] O número de elementos realmente retornava em rgelt. Isto pode ser menor do que celta se menos elementos celtas permanecerem na lista.

Valor de retorno

Um valor HRESULT padrão.

CComEnumImpl::Reset

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

STDMETHOD(Reset)(void);

Valor de retorno

Um valor HRESULT padrão.

CComEnumImpl::Saltar

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

STDMETHOD(Skip)(ULONG celt);

Parâmetros

Celta
[dentro] O número de elementos a ignorar.

Valor de retorno

Um valor HRESULT padrão.

Observações

Retorna E_INVALIDARG se celta for zero, devolve S_FALSE se forem retornados menos elementos celtos , retorna S_OK caso contrário.

Consulte também

Classe IEnumOnSTLImpl
Classe CComEnum
Visão geral da classe