CComEnum Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CComEnum Class.

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 ( IEnumXXXX) interface.

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 an STL 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 template function 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.

Share via