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.