HRESULT Init( T* begin, T* end, IUnknown* pUnk, CComEnumFlags flags = AtlFlagNoCopy );
Return Value
A standard HRESULT value.
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.
Remarks
You must call this method before passing a pointer to the enumerator interface back to any clients. 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.
Note The prototype of this method specifies the array elements as being of type T, where T was defined as a template parameter to the class. This is the same type that is exposed via the COM interface method CComEnumImpl::Next. The implication of this is that, unlike IEnumOnSTLImpl, this class does not support different storage and exposed data types. The data type of elements in the array must be the same as the data type exposed via the COM interface.
CComEnumImpl Overview | Class Members
See Also