CComEnumImpl Class

This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array.

Syntax

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

Parameters

Base
A COM enumerator interface. See IEnumString for an example.

piid
A pointer to the interface ID of the enumerator interface.

T
The type of item exposed by the enumerator interface.

Copy
A homogeneous copy policy class.

Members

Public Constructors

Name	Description
CComEnumImpl::CComEnumImpl	The constructor.
CComEnumImpl::~CComEnumImpl	The destructor.

Public Methods

Name	Description
CComEnumImpl::Clone	The implementation of the Clone enumeration interface method.
CComEnumImpl::Init	Initializes the enumerator.
CComEnumImpl::Next	The implementation of Next.
CComEnumImpl::Reset	The implementation of Reset.
CComEnumImpl::Skip	The implementation of Skip.

Public Data Members

Name	Description
CComEnumImpl::m_begin	A pointer to the first item in the array.
CComEnumImpl::m_dwFlags	Copy flags passed through Init.
CComEnumImpl::m_end	A pointer to the location just beyond the last item in the array.
CComEnumImpl::m_iter	A pointer to the current item in the array.
CComEnumImpl::m_spUnk	The IUnknown pointer of the object supplying the collection being enumerated.

Remarks

See IEnumString for an example of method implementations. CComEnumImpl provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array. This class is analogous to the IEnumOnSTLImpl class, which provides an implementation of an enumerator interface based on a C++ Standard Library container.

Note

For details on further differences between CComEnumImpl and IEnumOnSTLImpl, see CComEnumImpl::Init.

Typically, you will not need to create your own enumerator class by deriving from this interface implementation. If you want to use an ATL-supplied enumerator based on an array, it is more common to create an instance of CComEnum.

However, if you do need to provide a custom enumerator (for example, one that exposes interfaces in addition to the enumerator interface), you can derive from this class. In this situation, it is likely that you'll need to override the CComEnumImpl::Clone method to provide your own implementation.

For more information, see ATL Collections and Enumerators.

Inheritance Hierarchy

Base

CComEnumImpl

Requirements

Header: atlcom.h

CComEnumImpl::CComEnumImpl

The constructor.

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

The destructor.

~CComEnumImpl();

CComEnumImpl::Init

You must call this method before passing a pointer to the enumerator interface back to any clients.

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

Parameters

begin
A pointer to the first element of the array containing the items to be enumerated.

end
A pointer to the location just beyond the last element of the array containing the items to be enumerated.

pUnk
[in] The IUnknown pointer of an object that must be kept alive during the lifetime of the enumerator. Pass NULL if no such object exists.

flags
Flags specifying whether or not the enumerator should take ownership of the array or make a copy of it. Possible values are described below.

Return Value

A standard HRESULT value.

Remarks

Only call this method once — initialize the enumerator, use it, then throw it away.

If you pass pointers to items in an array held in another object (and you don't ask the enumerator to copy the data), you can use the pUnk parameter to ensure that the object and the array it holds are available for as long as the enumerator needs them. The enumerator simply holds a COM reference on the object to keep it alive. The COM reference is automatically released when the enumerator is destroyed.

The flags parameter allows you to specify how the enumerator should treat the array elements passed to it. flags can take one of the values from the CComEnumFlags enumeration shown below:

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

AtlFlagNoCopy means that the array's lifetime is not controlled by the enumerator. In this case, either the array will be static or the object identified by pUnk will be responsible for freeing the array when it's no longer needed.

AtlFlagTakeOwnership means that the destruction of the array is to be controlled by the enumerator. In this case, the array must have been dynamically allocated using new. The enumerator will delete the array in its destructor. Typically, you would pass NULL for pUnk, although you can still pass a valid pointer if you need to be notified of the destruction of the enumerator for some reason.

AtlFlagCopy means that a new array is to be created by copying the array passed to Init. The new array's lifetime is to be controlled by the enumerator. The enumerator will delete the array in its destructor. Typically, you would pass NULL for pUnk, although you can still pass a valid pointer if you need to be notified of the destruction of the enumerator for some reason.

Note

The prototype of this method specifies the array elements as being of type T, where T was defined as a template parameter to the class. This is the same type that is exposed by means of the COM interface method CComEnumImpl::Next. The implication of this is that, unlike IEnumOnSTLImpl, this class does not support different storage and exposed data types. The data type of elements in the array must be the same as the data type exposed by means of the COM interface.

CComEnumImpl::Clone

This method provides the implementation of the Clone method by creating an object of type CComEnum, initializing it with the same array and iterator used by the current object, and returning the interface on the newly created object.

STDMETHOD(Clone)(Base** ppEnum);

Parameters

ppEnum
[out] The enumerator interface on a newly created object cloned from the current enumerator.

Return Value

A standard HRESULT value.

Remarks

Note that cloned enumerators never make their own copy (or take ownership) of the data used by the original enumerator. If necessary, cloned enumerators will keep the original enumerator alive (using a COM reference) to ensure that the data is available for as long as they need it.

CComEnumImpl::m_spUnk

This smart pointer maintains a reference on the object passed to CComEnumImpl::Init, ensuring that it remains alive during the lifetime of the enumerator.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

A pointer to the location just beyond the last element of the array containing the items to be enumerated.

T* m_begin;

CComEnumImpl::m_end

A pointer to the first element of the array containing the items to be enumerated.

T* m_end;

CComEnumImpl::m_iter

A pointer to the current element of the array containing the items to be enumerated.

T* m_iter;

CComEnumImpl::m_dwFlags

The flags passed to CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

This method provides the implementation of the Next method.

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

Parameters

celt
[in] The number of elements requested.

rgelt
[out] The array to be filled with the elements.

pceltFetched
[out] The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.

Return Value

A standard HRESULT value.

CComEnumImpl::Reset

This method provides the implementation of the Reset method.

STDMETHOD(Reset)(void);

Return Value

A standard HRESULT value.

CComEnumImpl::Skip

This method provides the implementation of the Skip method.

STDMETHOD(Skip)(ULONG celt);

Parameters

celt
[in] The number of elements to skip.

Return Value

A standard HRESULT value.

Remarks

Returns E_INVALIDARG if celt is zero, returns S_FALSE if less than celt elements are returned, returns S_OK otherwise.

See also

IEnumOnSTLImpl Class
CComEnum Class
Class Overview