Clase CComEnumImpl

Esta clase proporciona la implementación de una interfaz de enumerador COM donde los elementos que se enumeran se almacenan en una matriz.

Sintaxis

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

Parámetros

Base
Una interfaz de enumerador COM. Consulte IEnumString para ver un ejemplo.

piid
Puntero al Id. de interfaz de la interfaz del enumerador.

T
El tipo de elemento expuesto por la interfaz del enumerador.

Copiar
Una clase de directiva de copia homogénea.

Miembros

Constructores públicos

Nombre	Descripción
CComEnumImpl::CComEnumImpl	Constructor .
CComEnumImpl::~CComEnumImpl	El destructor .

Métodos públicos

Nombre	Descripción
CComEnumImpl::Clone	La implementación del método de interfaz de enumeración Clone.
CComEnumImpl::Init	Inicializa el enumerador.
CComEnumImpl::Next	La implementación de Next.
CComEnumImpl::Reset	La implementación de Reset.
CComEnumImpl::Skip	La implementación de Skip.

Miembros de datos públicos

Nombre	Descripción
CComEnumImpl::m_begin	Puntero al primer elemento de la matriz.
CComEnumImpl::m_dwFlags	Copiar marcas pasadas a través de Init.
CComEnumImpl::m_end	Puntero a la ubicación justo después del último elemento de la matriz.
CComEnumImpl::m_iter	Puntero al elemento actual de la matriz.
CComEnumImpl::m_spUnk	Puntero IUnknown del objeto que proporciona la colección que se está enumerando.

Comentarios

Consulte IEnumString para obtener un ejemplo de implementaciones de método. CComEnumImpl proporciona la implementación de una interfaz de enumerador COM, donde los elementos que se enumeran se almacenan en una matriz. Esta clase es análoga a la clase IEnumOnSTLImpl, que proporciona una implementación de una interfaz de enumerador basada en un contenedor de la biblioteca estándar de C++.

Nota:

Para más información sobre las diferencias adicionales entre CComEnumImpl y IEnumOnSTLImpl, consulte CComEnumImpl::Init.

Normalmente, no es necesario crear su propia clase de enumerador derivando de esta implementación de interfaz. Si desea usar un enumerador proporcionado por ATL y basado en una matriz, es más habitual crear una instancia de CComEnum.

Sin embargo, si necesita proporcionar un enumerador personalizado (por ejemplo, uno que expone interfaces, además de la interfaz del enumerador), puede derivar a partir de esta clase. En esta situación, es probable que tenga que invalidar el método CComEnumImpl::Clone para proporcionar su propia implementación.

Para más información, consulte Colecciones y enumeradores de ATL.

Jerarquía de herencia

Base

CComEnumImpl

Requisitos

Encabezado: atlcom.h

CComEnumImpl::CComEnumImpl

Constructor .

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

El destructor .

~CComEnumImpl();

CComEnumImpl::Init

Debe llamar a este método antes de volver a pasar a los clientes un puntero dirigido a la interfaz del enumerador.

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

Parámetros

begin
Puntero al primer elemento de la matriz que contiene los elementos que se van a enumerar.

end
Puntero a la ubicación justo después del último elemento de la matriz que contiene los elementos que se van a enumerar.

pUnk
[in] Puntero IUnknown de un objeto que se debe mantener activo durante la vigencia del enumerador. Pase un valor NULL si no existe este objeto.

flags
Marcas que especifican si el enumerador debe convertirse en propietario de la matriz o copiarla. Los valores que pueden tener se describen más adelante.

Valor devuelto

Valor HRESULT estándar.

Comentarios

Llame a este método solo una vez. Inicialice el enumerador, úselo y después deséchelo.

Si pasa punteros a elementos de una matriz contenida en otro objeto (y no pide al enumerador que copie los datos), puede usar el parámetro pUnk para asegurarse de que el objeto y la matriz que contiene están disponibles siempre que el enumerador los necesite. El enumerador simplemente tiene una referencia COM en el objeto para mantenerla activa. La referencia COM se libera automáticamente cuando se destruye el enumerador.

El parámetro flags permite especificar cómo debe tratar el enumerador los elementos que le ha pasado la matriz. Las flags (marcas) pueden asumir uno de los valores de la enumeración CComEnumFlags que se muestran a continuación:

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

AtlFlagNoCopy significa que el enumerador no controla la duración de la matriz. En este caso, la matriz será estática o el objeto identificado por pUnk será responsable de liberar la matriz cuando ya no sea necesaria.

AtlFlagTakeOwnership significa que el enumerador controlará la destrucción de la matriz. En este caso, la matriz debe haberse asignado dinámicamente mediante new. El enumerador eliminará la matriz en su destructor. Normalmente, pasaría un valor NULL para pUnk, aunque todavía puede pasar un puntero válido si, por algún motivo, necesita recibir una notificación de la destrucción del enumerador.

AtlFlagCopy significa que se va a crear una nueva matriz mediante la copia de la matriz pasada a Init. El enumerador controlará la duración de la nueva matriz. El enumerador eliminará la matriz en su destructor. Normalmente, pasaría un valor NULL para pUnk, aunque todavía puede pasar un puntero válido si, por algún motivo, necesita recibir una notificación de la destrucción del enumerador.

Nota:

El prototipo de este método especifica los elementos de matriz como elementos de tipo T, donde T se definió como un parámetro de plantilla para la clase. Este es el mismo tipo que se expone mediante el método de interfaz COM CComEnumImpl::Next. La implicación de esto es que, a diferencia de IEnumOnSTLImpl, esta clase no admite distintos tipos de datos expuestos y de almacenamiento. El tipo de datos de los elementos de la matriz debe ser el mismo que el tipo de datos expuesto mediante la interfaz COM.

CComEnumImpl::Clone

Este método proporciona la implementación del método Clone mediante la creación de un objeto de tipo CComEnum, inicializándolo con la misma matriz e iterador usado por el objeto actual y devolviendo la interfaz en el objeto recién creado.

STDMETHOD(Clone)(Base** ppEnum);

Parámetros

ppEnum
[out] Interfaz del enumerador en un objeto recién creado y clonado desde el enumerador actual.

Valor devuelto

Valor HRESULT estándar.

Comentarios

Tenga en cuenta que los enumeradores clonados nunca realizan su propia copia (ni se convierten en propietarios) de los datos utilizados por el enumerador original. Si es necesario, los enumeradores clonados mantendrán activo el enumerador original (mediante una referencia COM) para garantizar que los datos estén disponibles siempre que los necesiten.

CComEnumImpl::m_spUnk

Este puntero inteligente mantiene una referencia en el objeto pasado a CComEnumImpl::Init para garantizar que permanece activo durante la vigencia del enumerador.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Puntero a la ubicación justo después del último elemento de la matriz que contiene los elementos que se van a enumerar.

T* m_begin;

CComEnumImpl::m_end

Puntero al primer elemento de la matriz que contiene los elementos que se van a enumerar.

T* m_end;

CComEnumImpl::m_iter

Puntero al elemento actual de la matriz que contiene los elementos que se van a enumerar.

T* m_iter;

CComEnumImpl::m_dwFlags

Las marcas pasadas a CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

Este método proporciona la implementación del método Next.

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

Parámetros

celta
[in] Número de elementos solicitados.

rgelt
[out] Matriz que se va a rellenar con los elementos.

pceltFetched
[out] Número de elementos realmente devueltos en rgelt. Puede ser menor que celt si los que permanecieron en la lista son menos que los elementos indicados en celt.

Valor devuelto

Valor HRESULT estándar.

CComEnumImpl::Reset

Este método proporciona la implementación del método Reset.

STDMETHOD(Reset)(void);

Valor devuelto

Valor HRESULT estándar.

CComEnumImpl::Skip

Este método proporciona la implementación del método Skip.

STDMETHOD(Skip)(ULONG celt);

Parámetros

celta
[in] Número de elementos que se van a omitir.

Valor devuelto

Valor HRESULT estándar.

Comentarios

Devuelve E_INVALIDARG si celt es cero, devuelve S_FALSE si se devuelven menos elementos que los indicados en celt; de lo contrario, devuelve S_OK.

Consulte también

IEnumOnSTLImpl (clase)
CComEnum (clase)
Información general sobre la clase