IEnumVARIANT::Clone

HRESULT Clone( 
  IEnumVARIANT FAR* FAR*  ppEnum  
);
 

Creates a copy of the current state of enumeration.

Parameter

ppEnum

On return, pointer to the location of the clone enumerator.

Return Value

The return value obtained from the returned HRESULT is one of the following:

Comments

Using this function, a particular point in the enumeration sequence can be recorded, and then returned to at a later time. The returned enumerator is of the same actual interface as the one that is being cloned.

There is no guarantee that exactly the same set of variants will be enumerated the second time as was enumerated the first. Although an exact duplicate is desirable, the outcome depends on the collection being enumerated. You may find that it is impractical for some collections to maintain this condition (for example, an enumeration of the files in a directory).

Example

The following code implements IEnumVariant::Clone for collections in the Lines sample file Enumvar.cpp.

STDMETHODIMP
CEnumVariant::Clone(IEnumVARIANT FAR* FAR* ppEnum)
{
    CEnumVariant FAR* penum = NULL;
    HRESULT hr;

    *ppenum = NULL;

    hr = CEnumVariant::Create(m_psa, m_cElements, &penum);
    if (FAILED(hr))
        goto error;
    penum->AddRef();
    penum->m_lCurrent = m_lCurrent;

    *ppenum = penum;
    return NOERROR;

error:
    if (penum)
        penum->Release();
    return hr;
}