CComEnumImpl 类

此类提供 COM 枚举器接口的实现，其中枚举的项存储在数组中。

语法

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

参数

Base
COM 枚举器接口。 有关示例，请参阅 IEnumString。

piid
指向枚举器接口的接口 ID 的指针。

T
枚举器接口公开的项的类型。

复制
同质复制策略类。

成员

公共构造函数

名称	描述
CComEnumImpl::CComEnumImpl	构造函数。
CComEnumImpl::~CComEnumImpl	析构函数。

公共方法

名称	描述
CComEnumImpl::Clone	Clone 枚举接口方法的实现。
CComEnumImpl::Init	初始化枚举器。
CComEnumImpl::Next	Next 的实现。
CComEnumImpl::Reset	Reset 的实现。
CComEnumImpl::Skip	Skip 的实现。

公共数据成员

“属性”	描述
CComEnumImpl::m_begin	指向数组中第一个项的指针。
CComEnumImpl::m_dwFlags	复制通过 Init 传递的标志。
CComEnumImpl::m_end	指向位置的指针，该位置刚好超过数组中的最后一项。
CComEnumImpl::m_iter	指向数组中当前项的指针。
CComEnumImpl::m_spUnk	提供被枚举集合的对象的 IUnknown 指针。

备注

有关方法实现的示例，请参阅 IEnumString。 CComEnumImpl 提供 COM 枚举器接口的实现，其中枚举的项存储在数组中。 此类类似于 IEnumOnSTLImpl 类，后者基于 C++ 标准库容器提供枚举器接口的实现。

注意

有关 CComEnumImpl 和 IEnumOnSTLImpl 之间的其他差别的详细信息，请参阅 CComEnumImpl::Init。

通常，你不需要通过从此接口实现派生来创建自己的枚举器类。 如果你想要使用 ATL 提供的基于数组的枚举器，更常见的做法是创建 CComEnum 的实例。

但是，如果你确实需要提供自定义枚举器（例如，除了公开枚举器接口之外还公开其他接口的枚举器），可以从此类进行派生。 在这种情况下，你可能需要重写 CComEnumImpl::Clone 方法以提供自己的实现。

有关详细信息，请参阅 ATL 集合和枚举器。

继承层次结构

Base

CComEnumImpl

要求

标头：atlcom.h

CComEnumImpl::CComEnumImpl

构造函数。

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

析构函数。

~CComEnumImpl();

CComEnumImpl::Init

在将指向枚举器接口的指针传回任何客户端之前必须调用此方法。

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

参数

begin
指向包含所要枚举项的数组的第一个元素的指针。

end
指向位置的指针，该位置刚好超过包含所要枚举项的数组的最后一个元素。

pUnk
[in] 在枚举器的生存期内必须保持活动状态的对象的 IUnknown 指针。 如果不存在此类对象，则传递 NULL。

flags
指定枚举器是否应取得数组的所有权或复制该数组的标志。 可能的值如下所述。

返回值

标准 HRESULT 值。

注解

仅调用此方法一次 – 初始化枚举器，使用它，然后将它丢弃。

如果将指针传递给另一个对象中包含的数组中的项（并且不要求枚举器复制数据），则可以使用 pUnk 参数来确保随时可根据枚举器的需要提供该对象及其包含的数组。 枚举器只需在对象上包含一个 COM 引用即可使该对象保持活动状态。 销毁枚举器时，COM 引用会自动释放。

flags 参数可用于指定枚举器应如何处理传递给它的数组元素。flags 可以采用 CComEnumFlags 枚举中如下所示的值之一：

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

AtlFlagNoCopy 表示数组的生存期不受枚举器控制。 在这种情况下，该数组是静态的，或者由 pUnk 标识的对象将负责在不再需要该数组时将其释放。

AtlFlagTakeOwnership 表示数组的销毁由枚举器控制。 在这种情况下，必须使用 new 动态分配该数组。 枚举器将删除其析构函数中的数组。 通常，你会为 pUnk 传递 NULL，但如果出于某种原因需要通知销毁枚举器，仍可以传递一个有效指针。

AtlFlagCopy 表示通过复制传递给 Init 的数组来创建一个新数组。 新数组的生存期由枚举器控制。 枚举器将删除其析构函数中的数组。 通常，你会为 pUnk 传递 NULL，但如果出于某种原因需要通知销毁枚举器，仍可以传递一个有效指针。

注意

此方法的原型将数组元素指定为 T 类型，其中的 T 定义为类的模板参数。 这与通过 COM 接口方法 CComEnumImpl::Next 公开的类型相同。 这意味着，与 IEnumOnSTLImpl 不同，此类不支持不同的存储和公开的数据类型。 数组中元素的数据类型必须与通过 COM 接口公开的数据类型相同。

CComEnumImpl::Clone

此方法通过创建 CComEnum 类型的对象，以当前对象使用的同一数组和迭代器初始化该对象，并返回新建对象上的接口，来提供 Clone 方法的实现。

STDMETHOD(Clone)(Base** ppEnum);

参数

ppEnum
[out] 从当前枚举器克隆的新建对象上的枚举器接口。

返回值

标准 HRESULT 值。

备注

请注意，克隆的枚举器永远不会为原始枚举器使用的数据创建其自身的副本（或取得所有权）。 如果需要，克隆的枚举器将使原始枚举器保持活动状态（使用 COM 引用），以确保随时可按需提供数据。

CComEnumImpl::m_spUnk

此智能指针保留传递给 CComEnumImpl::Init 的对象的引用，确保该对象在枚举器的生存期内保持活动状态。

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

指向位置的指针，该位置刚好超过包含所要枚举项的数组的最后一个元素。

T* m_begin;

CComEnumImpl::m_end

指向包含所要枚举项的数组的第一个元素的指针。

T* m_end;

CComEnumImpl::m_iter

指向包含所要枚举项的数组的当前元素的指针。

T* m_iter;

CComEnumImpl::m_dwFlags

传递给 CComEnumImpl::Init 的标志。

DWORD m_dwFlags;

CComEnumImpl::Next

此方法提供 Next 方法的实现。

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

参数

celt
[in] 请求的元素数。

rgelt
[out] 要用元素填充的数组。

pceltFetched
[out] rgelt 中实际返回的元素数。 如果列表中剩余的元素数小于 celt，则此参数可以小于 celt。

返回值

标准 HRESULT 值。

CComEnumImpl::Reset

此方法提供 Reset 方法的实现。

STDMETHOD(Reset)(void);

返回值

标准 HRESULT 值。

CComEnumImpl::Skip

此方法提供 Skip 方法的实现。

STDMETHOD(Skip)(ULONG celt);

参数

celt
[in] 要跳过的元素数目。

返回值

标准 HRESULT 值。

注解

如果 celt 为零，则返回 E_INVALIDARG；如果返回的元素数小于 celt，则返回 S_FALSE；否则返回 S_OK。

另请参阅

IEnumOnSTLImpl 类
CComEnum 类
类概述