Collections

ICollectionOnSTLImpl

In addition to parameterized implementations of enumeration interfaces, ATL provides parameterized implementations of collection interfaces, assuming that you're willing to keep your data in a standard C++-like container. The implementation is provided by the ICollectionOnSTLImpl class:

template <class T, class CollType, class ItemType,
          class CopyItem, class EnumType>         
class ICollectionOnSTLImpl : public T {           
public:                                           
  STDMETHOD(get_Count)(long* pcount);             
  STDMETHOD(get_Item)(long Index, ItemType* pvar);
  STDMETHOD(get__NewEnum)(IUnknown** ppUnk);      
                                                  
  CollType m_coll;                                
};

The ICollectionOnSTLImpl class provides an implementation of the three standard collection properties much like what I showed you earlier. The chief difference is that the container is managed for you in the m_coll member data of the ICollectionOnSTLImpl class. That means that you can't provide a copy of the data to the enumerators, but you can still use a collection that calculates on demand and you can still convert from a convenient type to the type required by the enumerator exposed from get__NewEnum. This is because, although you get to decide the type of the container in a template parameter, you're no longer implementing get__NewEnum.

The template parameters of ICollectionOnSTLImpl are as follows:

The T parameter indicates the base classFor example, IDispatchImpl-<IPrimeNumbers and &IID_IPrimeNumbers>. ICollectionOnSTLImpl provides the implementation of the standard three properties of this base class, but the deriving class is responsible for the rest.
The CollType parameter indicates the type of container to keepfor example, vector<long> or PrimesContainer.
The ItemType parameter indicates the type of data exposed from the iterator of the collectionfor example, long.
The CopyItem parameter indicates the type of the copy policy class. This copy policy is used only in the implementation of the get_Item method. The copy policy should be capable of copying from a container that holds items of type ItemType to a single [out] parameter of type ItemType. If you were managing a container of long numbers, the CopyItem type would be _Copy<long>.
The EnumType parameter indicates the type of the enumeration-implementation class. This enumeration must be capable of enumerating over a container just like CComEnumOnSTL. An example EnumType parameter is CCom-Enum-OnSTLImpl<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT, _Copy<VARIANT>, vector<VARIANT> >.

ICollectionOnSTLImpl Usage

The best way to understand the ICollectionOnSTLImpl class is to see it in action. The first C++based implementation of the IPrimesCollection standard collection interface assumed that we wanted to manage a precalculated container of VARIANTs. This can be done using ICollectionOnSTLImpl:

// Needed for implementation of get_Item.
// Converts the storage type (VARIANT) to the item type (long).
struct _CopyLongFromVariant {
  static HRESULT copy(long* p1, VARIANT* p2) {
    if (p2->vt == VT_I4) {
      *p1 = p2->lVal;
      return S_OK;
    }
    else {
      VARIANT var;
      HRESULT hr = VariantChangeType(&var, p2, 0, VT_I4);
      if (SUCCEEDED(hr)) *p1 = var.lVal;
      return hr;
    }
  }

  static void init(long* p) { }
  static void destroy(long* p) { }
};

// Needed for implementation of IDispatch methods
typedef IDispatchImpl<IPrimeNumbers, &IID_IPrimeNumbers>
  IPrimeNumbersDualImpl;

// Needed for implementation of get__NewEnum method
typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
  _Copy<VARIANT>, vector<VARIANT> > ComEnumVariantOnVector;

// Needed for implementation of standard collection methods
typedef ICollectionOnSTLImpl<IPrimeNumbersDualImpl,
  vector<VARIANT>, long, _CopyLongFromVariant,
    CComEnumVariantOnVector>
    IPrimeNumbersCollImpl;

class ATL_NO_VTABLE CPrimeNumbers :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CPrimeNumbers, &CLSID_PrimeNumbers>,
  public IPrimeNumbersCollImpl
{
public:
...
// IPrimeNumbers
public:
  STDMETHODIMP CalcPrimes(long min, long max) {
  m_coll.clear();
  for (long n = min; n <= max; ++n) {
    if (IsPrime(n)) {
      VARIANT var = {VT_I4};
      var.lVal = n;
      m_coll.push_back(var);
    }
  }

  return S_OK;
 }
};

If we wanted to precalculate the prime numbers but keep them as a vector of long numbers, this is how we'd use ICollectionOnSTLImpl:

// Needed for implementation of get__NewEnum.
// Converts the storage type (long) to the
// enumeration type (VARIANT).
struct _CopyVariantFromLong {
    static HRESULT copy(VARIANT* p1, long* p2) {
    if (p1->vt == VT_I4) {
      *p2 = p1->lVal;
      return S_OK;
    }
    else {
      VARIANT var;
      HRESULT hr = VariantChangeType(&var, p1, 0, VT_I4);
      if( SUCCEEDED(hr) ) *p2 = var.lVal;
      return hr;
    }
  }

  static void init(VARAINT* p) { ::VariantInit(p); }
  static void destroy(VARIANT* p) { ::VariantClear(p); }
};

// Needed for implementation of IDispatch methods
typedef IDispatchImpl<IPrimeNumbers, &IID_IPrimeNumbers>
  IPrimeNumbersDualImpl;

// Needed for implementation of get__NewEnum method
typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
  _CopyLongFromVariant, vector<VARIANT> >
  CComEnumVariantOnVectorOfLongs;

// Needed for implementation of standard collection methods
typedef ICollectionOnSTLImpl<IPrimeNumbersDualImpl,
  vector<long>, long, _Copy<long>,
  CComEnumVariantOnVectorOfLongs>
  IPrimeNumbersCollImpl;

class ATL_NO_VTABLE CPrimeNumbers :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CPrimeNumbers, &CLSID_PrimeNumbers>,
  public IPrimeNumbersCollImpl {
public:
...
// IPrimeNumbers
public:
  STDMETHODIMP CalcPrimes(long min, long max) {
    m_coll.clear();
    for (long n = min; n <= max; ++n) {
      if (IsPrime(n)) {
        m_coll.push_back(n);
      }
    }

    return S_OK;
  }
};

Finally, if we wanted to have the prime numbers calculated on demand and exposed as long numbers, we'd use ICollectionOnSTLImpl:

// Calculates prime numbers on demand
class PrimesContainer;

// Needed for implementation of get_Item.
// Converts the storage type (VARIANT) to the item type (long).
struct _CopyVariantFromLong;

// Needed for implementation of IDispatch methods
typedef IDispatchImpl<IPrimeNumbers, &IID_IPrimeNumbers>
  IPrimeNumbersDualImpl;

// Needed for implementation of get__NewEnum method
typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
  _CopyVariantFromLong, PrimesContainer >
  CComEnumVariantOnPrimesContainer;

// Needed for implementation of standard collection methods
typedef ICollectionOnSTLImpl<IPrimeNumbersDualImpl,
  PrimesContainer, long, _Copy<long>,
  CComEnumVariantOnPrimesContainer>
  IPrimeNumbersCollImpl;

class ATL_NO_VTABLE CPrimeNumbers :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CPrimeNumbers, &CLSID_PrimeNumbers>,
  public IPrimeNumbersCollImpl {
public:
...
// IPrimeNumbers
public:
  STDMETHODIMP CalcPrimes(long min, long max)
  { m_coll.SetRange(min, max); }
};

Jim Springfield, the father of ATL, says "ICollectionOnSTLImpl is not for the faint of heart." He's absolutely right. It provides a lot of flexibility, but at the expense of complexity. Still, when you've mastered the complexity, as with any good class library, you can get a lot done with very little code.