IEnumOnSTLImpl Class
The latest version of this topic can be found at IEnumOnSTLImpl Class.
This class defines an enumerator interface based on an STL collection.
Syntax
template <class Base,
const IID* piid, class T, class Copy, class CollType>
class ATL_NO_VTABLE IEnumOnSTLImpl : public Base
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 copy policy class.
CollType
An STL container class.
Members
Public Methods
| Name | Description |
|---|---|
| IEnumOnSTLImpl::Clone | The implementation of IEnumXXXX::Clone. |
| IEnumOnSTLImpl::Init | Initializes the enumerator. |
| IEnumOnSTLImpl::Next | The implementation of IEnumXXXX::Next. |
| IEnumOnSTLImpl::Reset | The implementation of IEnumXXXX::Reset. |
| IEnumOnSTLImpl::Skip | The implementation of IEnumXXXX::Skip. |
Public Data Members
| Name | Description |
|---|---|
| IEnumOnSTLImpl::m_iter | The iterator that represents the enumerator's current position within the collection. |
| IEnumOnSTLImpl::m_pcollection | A pointer to the STL container holding the items to be enumerated. |
| IEnumOnSTLImpl::m_spUnk | The IUnknown pointer of the object supplying the collection. |
Remarks
IEnumOnSTLImpl provides the implementation for a COM enumerator interface where the items being enumerated are stored in an STL-compatible container. This class is analogous to the CComEnumImpl class, which provides an implementation for an enumerator interface based on an array.
Note
See CComEnumImpl::Init for details on further differences between CComEnumImpl and IEnumOnSTLImpl.
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 STL container, it is more common to create an instance of CComEnumOnSTL, or to create a collection class that returns an enumerator by deriving from ICollectionOnSTLImpl.
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 Clone method to provide your own implementation.
Inheritance Hierarchy
Base
IEnumOnSTLImpl
Requirements
Header: atlcom.h
IEnumOnSTLImpl::Init
Initializes the enumerator.
HRESULT Init(
IUnknown* pUnkForRelease,
CollType& collection);
Parameters
pUnkForRelease
[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.
collection
A reference to the STL container that holds the items to be enumerated.
Return Value
A standard HRESULT value.
Remarks
If you pass Init a reference to a collection held in another object, you can use the pUnkForRelease parameter to ensure that the object, and the collection it holds, is available for as long as the enumerator needs it.
You must call this method before passing a pointer to the enumerator interface back to any clients.
IEnumOnSTLImpl::Clone
This method provides the implementation of the IEnumXXXX::Clone method by creating an object of type CComEnumOnSTL, initializing it with the same collection 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.
IEnumOnSTLImpl::m_spUnk
The IUnknown pointer of the object supplying the collection.
CComPtr<IUnknown> m_spUnk;
Remarks
This smart pointer maintains a reference on the object passed to IEnumOnSTLImpl::Init, ensuring that it remains alive during the lifetime of the enumerator.
IEnumOnSTLImpl::m_pcollection
This member points to the collection that provides the data driving the implementation of the enumerator interface.
CollType* m_pcollection;
Remarks
This member is initialized by a call to IEnumOnSTLImpl::Init.
IEnumOnSTLImpl::m_iter
This member holds the iterator used to mark the current position within the collection and navigate to subsequent elements.
CollType::iterator m_iter;
IEnumOnSTLImpl::Next
This method provides the implementation of the IEnumXXXX::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 in with the elements.
pceltFetched
[out] The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remain in the list.
Return Value
A standard HRESULT value.
IEnumOnSTLImpl::Reset
This method provides the implementation of the IEnumXXXX::Reset method.
STDMETHOD(Reset)(void);
Return Value
A standard HRESULT value.
IEnumOnSTLImpl::Skip
This method provides the implementation of the IEnumXXXX::Skip method.
STDMETHOD(Skip)(ULONG celt);
Parameters
celt
[in] The number of elements to skip.
Return Value
A standard HRESULT value.