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.

Requirements

Header: atlcom.h

See Also

Reference

CComEnumImpl Class

IEnumOnSTLImpl::Init