CComEnum Class

Article
09/28/2022

This class defines a COM enumerator object based on an array.

Syntax

template <class Base,
    const IID* piid, class T, class Copy, class ThreadModel = CcomObjectThreadModel>
class ATL_NO_VTABLE CComEnum : public CComEnumImpl<Base, piid,
T,
    Copy>,
public CComObjectRootEx<ThreadModel>

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.

ThreadModel
The threading model of the class. This parameter defaults to the global object thread model used in your project.

Remarks

CComEnum defines a COM enumerator object based on an array. This class is analogous to CComEnumOnSTL which implements an enumerator based on a C++ Standard Library container. Typical steps for using this class are outlined below. For more information, see ATL Collections and Enumerators.

To use this class:

typedef a specialization of this class.
Use the typedef as the template argument in a specialization of CComObject.
Create an instance of the CComObject specialization.
Initialize the enumerator object by calling CComEnumImpl::Init.
Return the enumerator interface to the client.

Inheritance Hierarchy

CComObjectRootBase

Base

CComObjectRootEx

CComEnumImpl

CComEnum

Requirements

Header: atlcom.h

Example

The code shown below provides a reusable function for creating and initializing an enumerator object.

template <class EnumType, class ElementType>
HRESULT CreateEnumerator(IUnknown** ppUnk, ElementType* begin, ElementType* end,
   IUnknown* pUnk, CComEnumFlags flags)
{
   if (ppUnk == NULL)
      return E_POINTER;
   *ppUnk = NULL;

   CComObject<EnumType>* pEnum = NULL;
   HRESULT hr = CComObject<EnumType>::CreateInstance(&pEnum);

   if (FAILED(hr))
      return hr;

   hr = pEnum->Init(begin, end, pUnk, flags);

   if (SUCCEEDED(hr))
      hr = pEnum->QueryInterface(ppUnk);

   if (FAILED(hr))
      delete pEnum;

   return hr;
} // CreateEnumerator

This function template can be used to implement the _NewEnum property of a collection interface as shown below:

typedef CComEnum<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT, _Copy<VARIANT> > VarArrEnum;

class ATL_NO_VTABLE CVariantArrayCollection :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CVariantArrayCollection, &CLSID_VariantArrayCollection>,
   public IDispatchImpl<IVariantArrayCollection, &IID_IVariantArrayCollection, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
VARIANT m_arr[3];
public:
    STDMETHOD(get__NewEnum)(IUnknown** ppUnk)
    {
        return CreateEnumerator<VarArrEnum>(ppUnk, &m_arr[0], &m_arr[3], this, 
           AtlFlagNoCopy);
    }

    // Remainder of class declaration omitted.

This code creates a typedef for CComEnum that exposes a vector of VARIANTs through the IEnumVariant interface. The CVariantArrayCollection class simply specializes CreateEnumerator to work with enumerator objects of this type and passes the necessary arguments.