Chapter 8. Collections and Enumerators

Many COM libraries are exposed as sets of objects known as object models. A COM object model is a parent object that holds a set of child objects. COM collections and enumerators are the glue that holds the parent and the children together. This chapter examines COM collections and enumerators and how they work together to build object models.

COM Collection and Enumeration Interfaces

Standard C++ Containers and Iterators

C++ programmers long ago learned to separate their collections into three pieces: the data itself, the container of the data, and an iterator for accessing the data. This separation is useful for building pieces separately from each other. The container’s job is to enable the user to affect the contents of the collection. The iterator’s job is to enable the user to access the contents of the container. And although the iterator implementation depends on how the container stores the data, the implementation details are hidden from the client of the container and the iterator. For example, imagine the following code for populating a container and then accessing it via an iterator:

void main() {
  // Populate the collection
  vector<long> rgPrimes;
  for (long n = 0; n != 1000; ++n) {
    if (IsPrime(n)) rgPrimes.push_back(n);
  }

  // Count the number of items in the collection
  cout << "Primes: " << rgPrimes.size() << endl;

  // Iterate over the collection using sequential access
  vector<long>::iterator begin = rgPrimes.begin();
  vector<long>::iterator end = rgPrimes.end();
  for (vector<long>::iterator it = begin; it != end; ++it) {
    cout << *it << " ";
  }
  cout << endl;
}

Because the container provides a well-known C++ interface, the client does not need to know the implementation details. In fact, C++ container classes are so uniform that this simple example would work just as well with a list or a deque as it does with a vector. Likewise, because the iterators that the container provides are uniform, the client doesn’t need to know the implementation details of the iterator.

For the client to enjoy these benefits, the container and the iterator have certain responsibilities. The responsibilities of the container include the following:

• Can allow the user to manipulate the data. Most containers are of variable size and are populated by the client. However, some containers represent a fixed data set or a set of data that is calculated instead of stored.

• Can allow the user to obtain the count of items. Containers have a size method for this purpose.

• Can allow random access. The std::vector class allows this using operator[], whereas the std::list class does not.

• Must allow the user to access the data at least sequentially, if not randomly. C++ containers provide this facility by exposing iterators.

Likewise, the responsibilities of the iterator entail the following:

• Must be capable of accessing the container’s data. That data might be in some shared spot (such as memory, file, or database) where the collection and iterator can both access the data. Alternatively, the iterator might have its own copy of the data. This would allow one client to access a snapshot of the data while another client modified the data using the container. Finally, the iterator could generate the data on demand – for example, by generating the next prime number.

• The iterator must keep track of its current position in the collection of data. Every call to the iterator’s operator++ means to advance that position. Every call to the iterator’s operator* means to hand out the data at the current position.

• The iterator must be capable of indicating the end of the data to the client.

Although C++ containers and iterators are handy in your C++ code, neither is useful as a way of communicating data via a COM interface. Instead, we turn to the COM equivalent of containers and iterators: COM collections and enumerators.

COM Collections and Enumerators

A COM collection is a COM object that holds a set of data and allows the client to manipulate its contents via a COM interface. In many ways, a COM collection is similar to a C++ container. Unfortunately, IDL doesn’t support templates, so it’s impossible to define a generic ICollection interface. Instead, COM defines collections through coding conventions.

By convention, a COM collection interface takes a minimum form. This form is shown here, pretending that IDL supported templates:

[ object, dual ]
template <typename T>
interface ICollection : IDispatch {
  [propget]
  HRESULT Count([out, retval] long* pnCount);

  [id(DISPID_VALUE), propget]
  HRESULT Item([in] long n, [out, retval] T* pnItem);

  [id(DISPID_NEWENUM), propget]
  HRESULT _NewEnum([out, retval] IUnknown** ppEnum);
};

Several features about this interface are worth noting:

• Although this minimal collection interface doesn’t show any methods for adding or removing elements from the collection, most collections include such methods.

• Most collection interfaces are dual interfaces. An IDispatch-based interface is required for some convenient language-mapping features that I discuss later.

• Most collection interfaces have a read-only Count property that provides a count of the current elements in the collection. Not all collections can calculate a reliable count, however. Examples include a collection of all prime numbers and a collection of rows from a database query that hasn’t yet been completed.

• Most collection interfaces have a read-only Item property for random access to a specific element. The first parameter is the index of the element to access, which I’ve shown as a long. It’s also common for this to be a VARIANT so that a number index or a string name can be used. If the index is a number, it is often 1-based, but the creator of the container can choose any indexing scheme desired. Furthermore, the Item property should be given the standard DISPID DISPID_VALUE. This marks the property as the “default” property, which certain language mappings use to provide more convenient access. I show you how this works later.

• An interface is a collection interface when it exposes an enumerator via the read-only property _NewEnum, which must be assigned the standard DISPID DISPID_NEWENUM. Visual Basic uses this DISPID to implement its For-Each syntax, as I show you soon.

None of the methods specified earlier is actually required; you need to add only the methods you expect to support. However, it’s highly recommended to have all three. Without them, you’ve got a container with inaccessible contents, and you can’t even tell how many things are trapped in there.

A COM enumerator is to a COM collection as an iterator is to a container. The collection holds the data and allows the client to manipulate it, and the enumerator allows the client sequential access. However, instead of providing sequential access one element at a time, as with an iterator, an enumerator allows the client to decide how many elements it wants. This enables the client to balance the cost of round-trips with the memory requirements to handle more elements at once. A COM enumerator interface takes the following form (again, pretending that IDL supported templates):

template <typename T>
interface IEnum : IUnknown {
  [local]
  HRESULT Next([in] ULONG celt,
               [out] T* rgelt,
               [out] ULONG *pceltFetched);

  [call_as(Next)] // Discussed later...
  HRESULT RemoteNext([in] ULONG celt,
                     [out, size_is(celt),
                      length_is(*pceltFetched)] T* rgelt,
                     [out] ULONG *pceltFetched);

  HRESULT Skip([in] ULONG celt);
  HRESULT Reset();
  HRESULT Clone([out] IEnum<T> **ppenum);
}

A COM enumerator interface has the following properties:

• The enumerator must be capable of accessing the data of the collection and maintaining a logical pointer to the next element to retrieve. All operations on an enumerator manage this logical pointer in some manner.

• The Next method allows the client to decide how many elements to retrieve in a single round-trip. A result of S_OK indicates that the exact number of elements requested by the celt parameter has been returned in the rgelt array. A result of S_FALSE indicates that the end of the collection has been reached and that the pceltFetched argument holds the number of elements actually retrieved. In addition to retrieving the elements, the Next method implementation must advance the logical pointer internally so that subsequent calls to Next retrieve additional data.

• The Skip method moves the logical pointer but retrieves no data. Notice that celt is an unsigned long, so there is no skipping backward. You can think of an enumerator as modeling a single-linked list, although, of course, it can be implemented any number of ways.

• The Reset method moves the logical pointer back to the beginning of the collection.

• The Clone method returns a copy of the enumerator object. The copy refers to the same data (although it can have its own copy) and points to the same logical position in the collection. The combination of Skip, Reset, and Clone makes up for the lack of a Back method.

Custom Collection and Enumerator Example

For example, let’s model a collection of prime numbers as a COM collection:

[dual]
interface IPrimeNumbers : IDispatch {
  HRESULT CalcPrimes([in] long min, [in] long max);

  [propget]
  HRESULT Count([out, retval] long* pnCount);

  [propget, id(DISPID_VALUE)]
  HRESULT Item([in] long n, [out, retval] long* pnPrime);

  [propget, id(DISPID_NEWENUM)] // Not quite right...
  HRESULT _NewEnum([out, retval] IEnumPrimes** ppEnumPrimes);
};

The corresponding enumerator looks like this:

interface IEnumPrimes : IUnknown {
  [local]
  HRESULT Next([in] ULONG celt,
               [out] long* rgelt,
               [out] ULONG *pceltFetched);

  [call_as(Next)]
  HRESULT RemoteNext([in] ULONG celt,
                     [out, size_is(celt),
                       length_is(*pceltFetched)] long* rgelt,
                     [out] ULONG *pceltFetched);

  HRESULT Skip([in] ULONG celt);
  HRESULT Reset();
  HRESULT Clone([out] IEnumPrimes **ppenum);
};

Porting the previous C++ client to use the collection and enumerator looks like this:

void main() {
  CoInitialize(0);

  CComPtr<IPrimeNumbers> spPrimes;
  if (SUCCEEDED(spPrimes.CoCreateInstance(CLSID_PrimeNumbers))) {
    // Populate the collection
    HRESULT hr = spPrimes->CalcPrimes(0, 1000);

    // Count the number of items in the collection
    long nPrimes;
    hr = spPrimes->get_Count(&nPrimes);
    cout << "Primes: " << nPrimes << endl;

    // Enumerate over the collection using sequential access
    CComPtr<IEnumPrimes> spEnum;
    hr = spPrimes->get__NewEnum(&spEnum);

    const size_t PRIMES_CHUNK = 64;
    long         rgnPrimes[PRIMES_CHUNK];

    do {
      ULONG celtFetched;
      hr = spEnum->Next(PRIMES_CHUNK, rgnPrimes, &celtFetched);
      if (SUCCEEDED(hr)) {
        if (hr == S_OK) celtFetched = PRIMES_CHUNK;
        for (long* pn = &rgnPrimes[0];
             pn != &rgnPrimes[celtFetched]; ++pn) {
          cout << *pn << " ";
        }
      }
    }
    while (hr == S_OK);
    cout << endl;

    spPrimes.Release();
  }

  CoUninitialize();
}

This client code asks the collection object to populate itself via the CalcPrimes method instead of adding each prime number one at a time. Of course, this procedure reduces round-trips. The client further reduces round-trips when retrieving the data in chunks of 64 elements. A chunk size of any number greater than 1 reduces round-trips but increases the data requirement of the client. Only profiling can tell you the right number for each client/enumerator pair, but larger numbers are preferred to reduce round-trips.

Dealing with the Enumerator local/call_as Oddity

One thing that’s rather odd about the client side of enumeration is the pceltFetched parameter filled by the Next method. The COM documentation is ambiguous, but it boils down to this: When only a single element is requested, the client doesn’t have to provide storage for the number of elements fetched; that is, pceltFetched is allowed to be NULL. Normally, however, MIDL doesn’t allow an [out] parameter to be NULL. So, to support the documented behavior for enumeration interfaces, all of them are defined with two versions of the Next method. The [local] Next method is for use by the client and allows the pceltFetched parameter to be NULL. The [call_as] RemoteNext method doesn’t allow the pceltFetched parameter to be NULL and is the method that performs the marshaling. Although the MIDL compiler implements the RemoteNext method, we have to implement Next manually because we’ve marked the Next method as [local]. In fact, we’re responsible for implementing two versions of the Next method. One version is called by the client and, in turn, calls the RemoteNext method implemented by the proxy. The other version is called by the stub and calls the Next method implemented by the object. Figure 8.1 shows the progression of calls from client to object through the proxy, the stub, and our custom code. The canonical implementation is as follows:

static HRESULT STDMETHODCALLTYPE
IEnumPrimes_Next_Proxy(
  IEnumPrimes * This, ULONG celt, long * rgelt,
  ULONG* pceltFetched) {
  ULONG cFetched;
  if (!pceltFetched && celt != 1) return E_INVALIDARG;
  return IEnumPrimes_RemoteNext_Proxy(This, celt, rgelt,
    pceltFetched ? pceltFetched : &cFetched);
}

static HRESULT STDMETHODCALLTYPE
IEnumPrimes_Next_Stub(IEnumPrimes * This, ULONG celt, long * rgelt,
  ULONG* pceltFetched) {
  HRESULT hr = This->lpVtbl->Next(This, celt, rgelt,
    pceltFetched);
  if (hr == S_OK && celt == 1) *pceltFetched = 1;
  return hr;
}

Figure 8.1. Call progression from client, through proxy and stub, to implementation of ``IEnumPrimes``

[View full size image]

Every enumeration interface includes this code in the proxy/stub implementation, including all the standard ones, such as IEnumUnknown, IEnumString, and IEnumVARIANT. The only difference in implementation is the name of the interface and the type of data being enumerated over (as shown in the IEnumPrimes example in bold).

When you’re building the proxy/stub for your project using the <project>PS project generated by the ATL project template, and you have a custom enumeration interface, it’s your job to inject that code into your proxy/stub. One way is to edit the <project>_p.c file, but if you were to recompile the IDL, the implementation would be lost. Another way is to add another .c file to the proxy/stub project. This is rather unpleasant and requires that you remember to update this code every time you edit the IDL file. The technique I prefer relies on macro definitions used during the proxy-/stub-building process and makes heavy use of the cpp_quote statement in IDL. [1] Whenever you have a custom enumeration interface, insert code like this at the bottom of the IDL file, and all will be right with the world (the bold code changes based on the enumeration interface):

[1]

I learned these tricks from Don Box and his enumeration-generation macros. These are available at www.sellsbrothers.com/links/dbox/enumgen.zip (http://tinysells.com/51).

cpp_quote("#ifdef __midl_proxy")
cpp_quote("static HRESULT STDMETHODCALLTYPE")
cpp_quote("IEnumPrimes_Next_Proxy")
cpp_quote("(IEnumPrimes * This, ULONG celt,long * rgelt, ULONG* pceltFetched)")
cpp_quote("{")
cpp_quote(" ULONG cFetched;")
cpp_quote(" if( !pceltFetched && celt != 1 ) return E_INVALIDARG;")
cpp_quote(" return IEnumPrimes_RemoteNext_Proxy(This, celt, rgelt,")
cpp_quote("                    pceltFetched ? pceltFetched : &cFetched);")
cpp_quote("}")
cpp_quote("")
cpp_quote("static HRESULT STDMETHODCALLTYPE")
cpp_quote("IEnumPrimes_Next_Stub")
cpp_quote("(IEnumPrimes* This, ULONG celt, long* rgelt, ULONG* pceltFetched)")
cpp_quote("{")
cpp_quote(" HRESULT hr = This->lpVtbl->Next(This, celt, rgelt,")
cpp_quote("                                 pceltFetched);")
cpp_quote(" if( hr == S_OK && celt == 1 ) *pceltFetched = 1;")
cpp_quote(" return hr;")
cpp_quote("}")
cpp_quote("#endif // __midl_proxy")

All the code within the cpp_quote statements is deposited into the <project>.h file, but because the __midl_proxy symbol is used, the code is compiled only when building the proxy/stub.

An Enumeration Iterator

One other niggling problem with COM enumerators is their ease of use or, rather, the lack thereof. It’s good that a client has control of the number of elements to retrieve in a single round-trip, but logically the client is still processing the data one element at a time. This is obfuscated by the fact that we’re using two loops instead of one. Of course, C++ being C++, there’s no reason that a wrapper can’t be built to remove this obfuscation. [2] Such a wrapper is included with the source code examples for this book. It’s called the enum_iterator and is declared like this:

[2]

Or replace one obfuscation for another, depending on your point of view.

#ifndef ENUM_CHUNK
#define ENUM_CHUNK 64
#endif

template <typename EnumItf, const IID* pIIDEnumItf,
  typename EnumType, typename CopyClass = _Copy<EnumType> >
class enum_iterator {
public:
  enum_iterator(IUnknown* punkEnum = 0,
    ULONG nChunk = ENUM_CHUNK);
  enum_iterator(const enum_iterator& i);
  ~enum_iterator();

  enum_iterator& operator=(const enum_iterator& rhs);
  bool operator!=(const enum_iterator& rhs);
  bool operator==(const enum_iterator& rhs);

  enum_iterator& operator++();
  enum_iterator operator++(int);
  EnumType& operator*();

private:
  ...
};

The enum_iterator class provides a standard C++-like forward iterator that wraps a COM enumerator. The type of the enumeration interface and the type of data that it enumerates are specified as template parameters. The buffer size is passed, along with the pointer to the enumeration interface, as a constructor argument. The first constructor allows for the common use of forward iterators. Instead of asking a container for the beginning and ending iterators, the beginning iterator is created by passing a non-NULL enumeration interface pointer. The end iterator is created by passing NULL. The copy constructor is used when forming a looping statement. This iterator simplifies the client enumeration code considerably:

...
// Enumerate over the collection using sequential access
CComPtr<IEnumPrimes> spEnum;
hr = spPrimes->get__NewEnum(&spEnum);

// Using an C++-like forward iterator
typedef enum_iterator<IEnumPrimes, &IID_IEnumPrimes, long>
  primes_iterator;
primes_iterator begin(spEnum, 64);
primes_iterator end;
for (primes_iterator it = begin; it != end; ++it) {
  cout << *it << " ";
}
cout << endl;
...

Or if you’d like to get a little more fancy, you can use the enum_iterator with a function object and a standard C++ algorithm, which helps you avoid writing the looping code altogether:

struct OutputPrime {
  void operator()(const long& nPrime) {
    cout << nPrime << " ";
  }
};

  ...
  // Using a standard C++ algorithm
  typedef enum_iterator<IEnumPrimes, &IID_IEnumPrimes, long>
    primes_iterator;
  for_each(primes_iterator(spEnum, 64), primes_iterator(),
    OutputPrime());
  ...

This example might not be as clear to you as the looping example, but it warms the cockles of my C++ heart.

Enumeration and Visual Basic 6.0

In the discussion that follows and in all references to Visual Basic in this chapter, we talk specifically about Visual Basic 6.0, not the latest version, VB .NET. COM collections and enumerations evolved with VB6 in mind, so it’s insightful to examine client-side programming with VB6 and collections. VB .NET, of course, is an entirely different subject and squarely outside the scope of this book.

The C++ for_each algorithm might seem a lot like the Visual Basic 6.0 (VB) For-Each statement, and it is. The For-Each statement allows a VB programmer to access each element in a collection, whether it’s an intrinsic collection built into VB or a custom collection developed using COM. Just as the for_each algorithm is implemented using iterators, the For-Each syntax is implemented using a COM enumerator; specifically, IEnumVARIANT. To support the For-Each syntax, the collection interface must be based on IDispatch and must have the _NewEnum property marked with the special DISPID value DISPID_NEWENUM. Because our prime number collection object exposes such a method, you might be tempted to write the following code to exercise the For-Each statement:

Private Sub Command1_Click()
    Dim primes As IPrimeNumbers
    Set primes = New PrimeNumbers
    primes.CalcPrimes 0, 1000

    MsgBox "Primes: " & primes.Count

    Dim sPrimes As String
    Dim prime As Variant

    For Each prime In primes ' Calls Invoke(DISPID_NEWENUM)
        sPrimes = sPrimes & prime & " "
    Next prime

    MsgBox sPrimes
End Sub

When VB sees the For-Each statement, it invokes the _NewEnum property, looking for an enumerator that implements IEnumVARIANT. To support this use, our prime number collection interface must change from exposing IEnumPrimes to exposing IEnumVARIANT. Here’s the twist: The signature of the method is actually _NewEnum(IUnknown**), not _NewEnum(IEnumVARIANT**). VB takes the IUnknown* returned from _NewEnum and queries for IEnumVARIANT. It would’ve been nice for VB to avoid an extra round-trip, but perhaps at one point, the VB team expected to support other enumeration types.

Modifying IPrimeNumbers to support the VB For-Each syntax looks like this:

[dual]
interface IPrimeNumbers : IDispatch {
  HRESULT CalcPrimes([in] long min, [in] long max);

  [propget]
  HRESULT Count([out, retval] long* pnCount);

  [propget, id(DISPID_VALUE)]
  HRESULT Item([in] long n, [out, retval] long* pnPrime);

  [propget, id(DISPID_NEWENUM)]
  HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum);
};

This brings the IPrimeNumbers interface into line with the ICollection template form we showed you earlier. In fact, it’s fair to say that the ICollection template form was defined to work with VB.

Note one important thing about VB’s For-Each statement. If your container contains objects (your returned variants contain VT_UNKNOWN or VT_DISPATCH), the contained objects must implement the IDispatch interface. If they don’t, you’ll get an “item not an object” error at runtime from VB 6.

The VB Subscript Operator

Using the Item method, a VB client can access each individual item in the collection one at a time:

...
Dim i As Long
For i = 1 To primes.Count
    sPrimes = sPrimes & primes.Item(i) & " "
Next i
...

Because I marked the Item method with DISPID_VALUE, VB allows the following abbreviated syntax that makes a collection seem like an array (if only for a second):

...
Dim i As Long
For i = 1 To primes.Count
    sPrimes = sPrimes & primes(i) & " " ' Invoke(DISPID_VALUE)
Next i
...

Assigning a property the DISPID_VALUE dispatch identifier makes it the default property, as far as VB is concerned. Using this syntax results in VB getting the default property – that is, calling Invoke with DISPID_VALUE. However, because we’re dealing with array syntax in VB, we have two problems. The first is knowing where to start the index1 or 0? A majority of existing code suggests making collections 1-based, but only a slight majority. As a collection implementer, you get to choose. As a collection user, you get to guess. In general, if you anticipate a larger number of VB clients for your collection, choose 1-based; and whatever you do, please document the decision.

The other concern with using array-style access is round-trips. Using the Item property puts us smack dab in the middle of what we’re trying to avoid by using enumerators: one round-trip per data element. If you think that using the For-Each statement and, therefore, enumerators under VB solves both these problems, you’re half right. Unfortunately, Visual Basic 6.0 continues to access elements one at a time, even though it’s using IEnumVARIANT::Next and is perfectly capable of providing a larger buffer. However, using the For-Each syntax does allow you to disregard whether the Item method is 1-based or 0-based.

The Server Side of Enumeration

Because the semantics of enumeration interfaces are loose, you are free to implement them however you like. The data can be pulled from an array, a file, a database result set, or wherever it is stored. Even better, you might want to calculate the data on demand, saving yourself calculations and storage for elements in which the client isn’t interested. Either way, if you’re doing it by hand, you have some COM grunge code to write. Or, if you like, ATL is there to help write that grunge code.

Enumerating Arrays

CComEnum

Because enumeration interfaces are all the same except for the actual data being enumerated, their implementation can be standardized, given a couple assumptions. Depending on how you’ve stored your data, you can use one of two ATL enumeration interface classes. The most flexible implementation class enables you to provide your data in a standard C++-like collection. This is called CComEnumOnSTL (discussed later). The simplest implementation assumes that you’ve stored your data as an array. It’s called CComEnum, and the complete implementation is as follows:

template <class Base, const IID* piid, class T, class Copy,
    class ThreadModel = CComObjectThreadModel>
class ATL_NO_VTABLE CComEnum :
    public CComEnumImpl<Base, piid, T, Copy>,
    public CComObjectRootEx< ThreadModel > {
public:
    typedef CComEnum<Base, piid, T, Copy > _CComEnum;
    typedef CComEnumImpl<Base, piid, T, Copy > _CComEnumBase;
    BEGIN_COM_MAP(_CComEnum)
        COM_INTERFACE_ENTRY_IID(*piid, _CComEnumBase)
    END_COM_MAP()
};

Although this implementation consists of only a few lines of code, there’s quite a lot going on here. The template arguments are as follows:

• Base is the enumeration interface to be implemented – for example, IEnumPrimes.

• piid is a pointer to the interface being implemented – for example, &IID_IEnumPrimes.

• T is the type of data being enumerated – for example, long.

• Copy is the class responsible for copying the data into the client’s buffer as part of the implementation of Next. It can also be used to cache a private copy of the data in the enumerator to guard against simultaneous access and manipulation.

• ThreadModel describes just how thread safe this enumerator needs to be. When you specify nothing, it uses the dominant threading model for objects, as described in Chapter 4, “Objects in ATL.” Of course, because a COM enumerator is a COM object like any other, it requires an implementation of IUnknown. Toward that end, CComEnum derives from CComObjectRootEx. You’ll see later that I further derive CComObject from CComEnum to fill in the vtbl properly.

Really, CComEnum is present simply to bring CComObjectRootEx together with CComEnumImpl, the base class that actually implements Next, Skip, Reset, and Clone. Figure 8.2 shows how these classes fit together.

Figure 8.2. The ``CComEnum`` inheritance hierarchy

Copy Policy Classes

The fundamental job of the enumerator is to copy the collection’s data into the buffer that the client provides. If the data being enumerated is a pointer or a structure that contains pointers, a simple memcpy or assignment will not do the trick. Instead, the client needs its own deep copy of each element, which it can release when it has finished with it. Toward that end, ATL enumerators use a class called a copy policy class, often just called a copy policy, to scope static methods for dealing with deep-copy semantics. The static methods of a copy policy are like the Increment and Decrement methods of the threading model classes, except that instead of incrementing and decrementing a long, copy policies know how to initialize, copy, and destroy data. For simple types, ATL provides a template copy policy class:

template <class T>
class _Copy{
public:
    static HRESULT copy(T* p1, const T* p2) {
        Checked::memcpy_s(p1, sizeof(T), p2, sizeof(T));
        return S_OK;
    }
    static void init(T*) {}
    static void destroy(T*) {}
};

Given an array of a simple type (such as long), this template works just fine:

HRESULT CopyRange(long* dest, long* src, size_t count) {
  for (size_t i = 0; i != count; ++i) {
    HRESULT hr = _Copy<long>::copy(&dest[i], &src[i]);
    if( FAILED(hr) ) {
      while( i > 0 )_Copy<long>::destroy(&dest[--i]);
      return hr;
    }
  }
  return S_OK;
}

However, given something with trickier semantics, such as a VARIANT or an OLESTR, memcpy is too shallow. For the four most commonly enumerated data types, ATL provides specializations of the _Copy template:

template<> class _Copy<VARIANT>;
template<> class _Copy<LPOLESTR>;
template<> class _Copy<OLEVERB>
template<> class _Copy<CONNECTDATA>;

For example, the copy policy for VARIANT s looks like this:

template<> class _Copy<VARIANT> {
public:
    static HRESULT copy(VARIANT* p1, const VARIANT* p2) {
        p1->vt = VT_EMPTY;
        return VariantCopy(p1, const_cast<VARIANT*>(p2));
    }
    static void init(VARIANT* p) {p->vt = VT_EMPTY;}
    static void destroy(VARIANT* p) {VariantClear(p);}
};

If you’re dealing with interface pointers, again, the _Copy template won’t do, but building your own specialization for each interface you want to copy is a bit arduous. For interfaces, ATL provides the _CopyInterface copy policy class parameterized on the type of interface you’re managing:

template <class T> class _CopyInterface {
public:
    static HRESULT copy(T** p1, T** p2) {
        ATLENSURE(p1 != NULL && p2 != NULL);
        *p1 = *p2;
        if (*p1)
            (*p1)->AddRef();
        return S_OK;
    }
    static void init(T** ) {}
    static void destroy(T** p) {if (*p) (*p)->Release();}
};

Using copy policies, we now have a generic way to initialize, copy, and delete any kind of data, making it easy to build a generic and safe duplication routine:

template <typename T, typename Copy>
HRESULT CopyRange(T* dest, T* src, size_t count) {
  for (size_t i = 0; i != count; ++i) {
    HRESULT hr = Copy::copy(&dest[i], &src[i]);
    if( FAILED(hr) ) {
      while( i > 0 ) Copy::destroy(&dest[--i]);
      return hr;
    }
  }
  return S_OK;
}

CComEnumImpl’s implementation of the Next method uses the copy policy passed as the template parameter to initialize the client’s buffer and fill it with data from the collection, much like our sample CopyRange routine. However, before we jump right into the Next method, let’s see how CComEnumImpl does its job.

CComEnumImpl

To implement the methods of an enumeration interface, CComEnumImpl maintains five data members:

template <class Base, const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base {
public:
    CComEnumImpl();
    virtual ~CComEnumImpl();

    STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);
    STDMETHOD(Skip)(ULONG celt);
    STDMETHOD(Reset)(void);
    STDMETHOD(Clone)(Base** ppEnum);

    HRESULT Init(T* begin, T* end, IUnknown* pUnk,
                 CComEnumFlags flags = AtlFlagNoCopy);

    CComPtr<IUnknown> m_spUnk;
    T* m_begin;
    T* m_end;
    T* m_iter;
    DWORD m_dwFlags;
    ...
};

The m_begin, m_end, and m_iter members are each pointers to the type of data being enumerated, as passed via the T template parameter. Each of these members keeps track of pointers into an array of the data being enumerated. In classic standard C++ style, m_begin points to the beginning of the array, m_end points to one past the end of the array, and m_iter points to the next element to hand out. The m_dwFlags member determines if and when to copy initialization data that the creator of the enumerator provides. The m_spUnk member refers to the owner of the data if the enumerator is sharing it instead of keeping its own copy. The implementations of Next, Skip, Reset, and Clone use these variables to provide their behavior. These variables are set in the Init method of CComEnumImpl.

Initializing CComEnumImpl

Calling the Init method requires the data to be arranged in an array. Maybe the collection is already maintaining the data as an array, or maybe it’s not. Either way, the begin parameter to Init must be a pointer to the beginning of an array of the type being enumerated, and the end parameter must be one past the end of the same array. Where that array comes from and how the enumerator manages it depend on the last parameter to Init, the flags parameter. This parameter can take one of three values:

• AtlFlagNoCopy means that the collection already maintains its data in an array of the type being enumerated and is willing to share the data with the enumerator. This is more efficient because the enumerator doesn’t keep its own copy;it merely initializes m_begin, m_end, and m_iter to point at the collection’s data. However, this can lead to unpredictable results if a client uses the collection to modify the data while it’s being enumerated. If you use the AtlFlagNoCopy flag, you should pass an interface pointer to the collection that owns the data as the pUnk parameter to Init. The enumerator caches this interface pointer, adding to the reference count of the collection. This is necessary to keep an enumerator from outliving the collection and, more important, the data that the collection is maintaining. For each of the other two flags, pUnk is NULL.

• AtlFlagCopy means that the collection already maintains the data in the appropriate format but would prefer the enumerator to have its own copy of the data. This is less efficient but ensures that no manipulation of the collection affects the data that the enumerator maintains.

• AtlFlagTakeOwnership means that the collection doesn’t maintain its data in an array of a type appropriate for the enumerator to use. Instead, the collection has allocated an array of the data type being enumerated using operator new[] for sole use of the enumerator. When the enumerator is destroyed, it should destroy its copy of the data using operator delete[]. This is especially handy for the implementation of IEnumVARIANT because most developers prefer to keep data in types more specific than VARIANT but are willing to provide an array of VARIANT s when creating the enumerator.

CComEnumImpl Implementation

The most interesting part of the CComEnumImpl implementation is the Next method. Recall that Next’s job is to copy the client-requested number of elements into the client-provided buffer. CComEnumImpl’s implementation of the Next method is identical in concept to the CopyRange function I showed you earlier. Next uses the copy policy to copy the data provided by the collection at initialization into the client’s buffer. If anything goes wrong, the copy policy is used to destroy the data already copied. The rest of the logic is argument validation and involves watching for the end of the data.

template <class Base, const IID* piid, class T, class Copy>
STDMETHODIMP CComEnumImpl<Base, piid, T, Copy>::Next(
      ULONG celt, T* rgelt,
      ULONG* pceltFetched) {
      if (pceltFetched != NULL)
          *pceltFetched = 0;
      if (celt == 0)
          return E_INVALIDARG;
      if (rgelt == NULL || (celt != 1 && pceltFetched == NULL))
          return E_POINTER;
      if (m_begin == NULL || m_end == NULL || m_iter == NULL)
          return E_FAIL;
      ULONG nRem = (ULONG)(m_end - m_iter);
      HRESULT hRes = S_OK;
      if (nRem < celt)
          hRes = S_FALSE;
      ULONG nMin = celt < nRem ? celt : nRem ;
      if (pceltFetched != NULL)
          *pceltFetched = nMin;
      T* pelt = rgelt;
      while(nMin--) {
          HRESULT hr = Copy::copy(pelt, m_iter);
          if (FAILED(hr)) {
              while (rgelt < pelt)
                  Copy::destroy(rgelt++);
              if (pceltFetched != NULL)
                  *pceltFetched = 0;
              return hr;
          }
          pelt++;
          m_iter++;
      }
      return hRes;
  }

The implementations of Skip and Reset are trivial:

template <class Base, const IID* piid, class T, class Copy>
STDMETHODIMP CComEnumImpl<Base, piid, T, Copy>::Skip(ULONG celt) {
    if (celt == 0)
        return E_INVALIDARG;

    ULONG nRem = ULONG(m_end - m_iter);
    ULONG nSkip = (celt > nRem) ? nRem : celt;
    m_iter += nSkip;
    return (celt == nSkip) ? S_OK : S_FALSE;
}

template <class Base, const IID* piid, class T, class Copy>
STDMETHODIMP CComEnumImpl<Base, piid, T, Copy>::Reset()
{ m_iter = m_begin;return S_OK; }

The Clone method is responsible for duplicating the current enumerator. This means creating a new enumerator of the same type and initializing it using the Init method. However, the data is never copied again for subsequent enumerators. Instead, if the collection indicated that the data was to be shared, a new enumerator gets the IUnknown* of the original collection, giving the collection another reason to live. Otherwise, if the enumerator is keeping its own copy of the data, the new enumerator is given the IUnknown* of the original enumerator. Because enumerators are read-only, one copy of the data serves for all enumerators.

template <class Base, const IID* piid, class T, class Copy>
STDMETHODIMP CComEnumImpl<Base, piid, T, Copy>::Clone(
  Base** ppEnum) {
  typedef CComObject<CComEnum<Base, piid, T, Copy> > _class;
  HRESULT hRes = E_POINTER;
  if (ppEnum != NULL) {
    *ppEnum = NULL;
    _class* p;
    hRes = _class::CreateInstance(&p);
    if (SUCCEEDED(hRes)) {
    // If this object has ownership of the data then we
    // need to keep it around
      hRes = p->Init(m_begin, m_end, (m_dwFlags & BitOwn) ?
        this : m_spUnk);
      if (SUCCEEDED(hRes)) {
        p->m_iter = m_iter;
        hRes = p->_InternalQueryInterface(*piid, (void**)ppEnum);
      }
      if (FAILED(hRes))
        delete p;
    }
  }
  return hRes;
}

CComEnum Use

As an example of a typical CComEnum use, let’s implement the IPrimeNumbers collection interface:

[dual]
interface IPrimeNumbers : IDispatch {
  HRESULT CalcPrimes([in] long min, [in] long max);

  [propget]
  HRESULT Count([out, retval] long* pnCount);

  [propget, id(DISPID_VALUE)]
  HRESULT Item([in] long n, [out, retval] long* pnPrime);

  [propget, id(DISPID_NEWENUM)]
  HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum);
};

The collection maintains a list of the prime numbers in a C++ vector. The Calc-Primes method populates the collection:

STDMETHODIMP CPrimeNumbers::CalcPrimes(long min, long max) {
  m_rgPrimes.clear();
  for (long n = min; n <= max; ++n ) {
    if (IsPrime(n)) m_rgPrimes.push_back(n);
  }
  return S_OK;
}

The get_Count and get_Item methods use the vector to perform their duties:

STDMETHODIMP CPrimeNumbers::get_Count(long* pnCount) {
  *pnCount = m_rgPrimes.size();
  return S_OK;
}

STDMETHODIMP CPrimeNumbers::get_Item(long n, long* pnPrime) {
  // Oh, let's be 1-based today...
  if (n < 1 || n > m_rgPrimes.size()) return E_INVALIDARG;
  *pnPrime = m_rgPrimes[n-1];
  return S_OK;
}

Because we’re going out of our way to support VB with our collection interface, the get__NewEnum method returns an interface on an implementation of IEnumVARIANT. Because the name of the parameterized enumerator is used more than once, it’s often handy to use a type definition:

typedef CComEnum< IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
  _Copy<VARIANT> > CComEnumVariant;

Remember, the CComEnum template parameters are, in order, the interface we’d like the enumerator to implement, the IID of that interface, the type of data we’d like to enumerate, and, finally, a copy policy class for copying the data from the enumerator’s copy to the client’s buffer. To provide an implementation of IUnknown, the CComEnum class is further used as the base class for a new CComObject class. Using this type definition, the implementation of get__NewEnum entails creating an instance of an enumerator, initializing it with array data, and filling ppunkEnum with a pointer to the enumerator for use by the client. Because we’re keeping the data as a vector, however, we have to allocate an array of VARIANT s manually, fill the data from the vector, and pass ownership to the enumeration using AtlFlagTakeOwnership. The following code illustrates this procedure:

STDMETHODIMP CPrimeNumbers::get__NewEnum(IUnknown** ppunkEnum) {
  *ppunkEnum = 0;

  // Create an instance of the enumerator
  CComObject<CComEnumVariant>* pe = 0;
  HRESULT hr = CComObject<CComEnumVariant>::CreateInstance(&pe);
  if (SUCCEEDED(hr)) {
    pe->AddRef();

    // Copy data from vector<long> to VARIANT*
    size_t nPrimes = m_rgPrimes.size();
    VARIANT* rgvar = new VARIANT[nPrimes];
    if (rgvar) {
      ZeroMemory(rgvar, sizeof(VARIANT) * nPrimes);
      VARIANT* pvar = &rgvar[0];
      for (vector<long>::iterator it = m_rgPrimes.begin();
           it != m_rgPrimes.end();
           ++pvar, ++it ) {
        pvar->vt = VT_I4;
        pvar->lVal = *it;
      }

      // Initialize enumerator
      hr = pe->Init(&rgvar[0], &rgvar[nPrimes], 0,
        AtlFlagTakeOwnership);
      if (SUCCEEDED(hr)) {
        // Fill outbound parameter
        hr = pe->QueryInterface(IID_IUnknown, (void**)ppunkEnum);
      }
    }
    else {
    hr = E_OUTOFMEMORY;
  }

  pe->Release();
 }

 return hr;
}

Unfortunately, this code leaves an unpleasant taste in one’s mouth. Although it would have been considerably simpler if we’d already had an array of VARIANT s holding the data, frankly, that’s rare. C++ programmers tend to use containers other than the error-prone C++ array. Because of this tendency, we were forced to translate the data from our preferred format to the preferred format of the ATL enumerator implementation. Given the regularity of a container’s C++ interface, this seems like a waste. In an ideal world, we’d have an enumeration implementation that could handle a standard C++ container instead of an array. In an ideal world, we’d have CComEnumOnSTL. Welcome to my ideal world.

Enumerating Standard C++ Collections

CComEnumOnSTL [3]

[3]

Technically, there’s no such thing as the “STL”; there’s just the standard C++ library. The ATL classes were named before the C++ standard was finalized, so they still use the old “STL” name.

The declaration of CComEnumOnSTL is similar to that of CComEnum:

template <class Base, const IID* piid, class T, class Copy,
  class CollType, class ThreadModel = CComObjectThreadModel>
class ATL_NO_VTABLE CComEnumOnSTL :
    public IEnumOnSTLImpl<Base, piid, T, Copy, CollType>,
    public CComObjectRootEx< ThreadModel > {
public:
    typedef CComEnumOnSTL<Base, piid, T, Copy, CollType,
        ThreadModel > _CComEnum;
    typedef IEnumOnSTLImpl<Base, piid, T, Copy, CollType >
        _CComEnumBase;
    BEGIN_COM_MAP(_CComEnum)
        COM_INTERFACE_ENTRY_IID(*piid, _CComEnumBase)
    END_COM_MAP()
};

The chief difference between CComEnumOnSTL and CComEnum is the addition of the CollType template parameter. This parameter indicates the type of collection to iterate over. The base class, IEnumOnSTLImpl, uses the collection to implement the Next, Skip, Reset, and Clone methods of the enumeration interface. The type of collection passed as the CollType must expose at least the following C++ interface:

template <typename T> class CollType {
public:
  class const_iterator; // Forward declaration
  const_iterator begin() const;
  const_iterator end() const;

  class const_iterator {
  public:
    const_iterator(const const_iterator& it); // To support
                                              // postfix ++
    const_iterator& operator=(const const_iterator& it);
    bool operator!=(const const_iterator& rhs);
    const T& operator*();
    const_iterator operator++(int); // Postfix ++
  };
};

All existing standard C++ collections adhere to these minimum requirements. If you want to make your own collection, it must adhere to this interface as well. I’ll show you later how defining your own collection type is useful for enumerating data calculated on demand.

IEnumOnSTLImpl

The base class of CComEnumOnSTL, IEnumOnSTLImpl, uses the standard C++-like collection passed as the CollType parameter to implement the Next, Skip, Reset, and Clone methods. The following is the declaration of IEnumOnSTLImpl:

template <class Base, const IID* piid, class T,
    class Copy, class CollType>
class ATL_NO_VTABLE IEnumOnSTLImpl : public Base {
public:
    HRESULT Init(IUnknown *pUnkForRelease, CollType& collection);

    STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);
    STDMETHOD(Skip)(ULONG celt);
    STDMETHOD(Reset)(void);
    STDMETHOD(Clone)(Base** ppEnum);

// Data
    CComPtr<IUnknown> m_spUnk;
    CollType* m_pcollection;
    typename CollType::const_iterator m_iter;
};

As with CComEnumImpl, IEnumOnSTLImpl keeps an m_spUnk pointer. However, unlike CComEnumImpl, the m_spUnk pointer should never be NULL and, therefore, the pUnkForRelease parameter to Init should never be NULL. Notice that IEnumOnSTLImpl keeps no m_dwFlags member data. It has no option for copying the data from the collection. Instead, it needs to ensure that the collection holding the data outlives the enumerator. Every call to Init assumes the equivalent of the CComEnum’s AtlFlagNoCopy flag. Although this is more efficient than AtlFlagCopy or the manual copying required for AtlFlagTakeOwnership, if the collection changes while it’s being enumerated, the behavior is undefined. If you need ATL’s C++-based enumerator to have its own copy of the data, you must wrap a copy of the data in its own COM object, a technique I show you later.

CComEnumOnSTL Use

If our prime number collection object held a collection of VARIANT s, the implementation of get__NewEnum would look like this:

STDMETHODIMP CPrimeNumbers::get__NewEnum(IUnknown** ppunkEnum) {
  *ppunkEnum = 0;

  typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
                        _Copy<VARIANT>, vector<VARIANT> >
          CComEnumVariantOnVector;

  CComObject<CComEnumVariantOnVector>* pe = 0;
  HRESULT hr = CComObject<CComEnumVariantOnVector>::CreateInstance(&pe);
  if (SUCCEEDED(hr)) {
    pe->AddRef();

    hr = pe->Init(this->GetUnknown(), m_rgPrimes);
    if (SUCCEEDED(hr)) {
      hr = pe->QueryInterface(ppunkEnum);
    }

    pe->Release();
  }

  return hr;
}

Of course, we’d prefer not to keep a collection of VARIANT s. Instead, we’d like to keep a collection of a type that matches our needsin this case, long s. Fortunately, unlike CComEnumImpl, IEnumOnSTLImpl allows on-demand data conversion, enabling us to keep our collection in a convenient type but still providing the data in a format that the enumerator requires.

On-Demand Data Conversion

The implementations of the Next, Skip, Reset, and Clone methods using a standard C++ collection are almost identical to those of the CComEnumImpl class. The single significant difference is a nifty loophole in the IEnumOnSTLImpl’s Next method. The CComEnumImpl class ties the data type being enumerated to the data type held in the array of the enumerator. However, IEnumOnSTLImpl has no such limitation. Look at this snippet from IEnumOnSTLImpl’s Next method:

template <class Base, const IID* piid, class T, class Copy,
  class CollType>
STDMETHODIMP
IEnumOnSTLImpl<Base, piid, T, Copy, CollType>::Next(
  ULONG celt, T* rgelt, ULONG* pceltFetched) {
  ...
  T* pelt = rgelt;
  while (SUCCEEDED(hr) && m_iter != m_pcollection->end() &&
    nActual < celt) {
    hr = Copy::copy(pelt, &*m_iter);
    ...
  }
  ...
    return hr;
}

The template parameters allow the type of the *pelt to be different from the type of the &*m_iter. In other words, the type of data that the collection holds can be different from the type of data that the client receives in the call to Next. This means that the copy policy class must still be capable of initializing and destroying the data of the type being enumerated, but the copy operation could actually be hijacked to convert from one data type to another.

Imagine the following copy policy:

struct _CopyVariantFromLong {
  static HRESULT copy(VARIANT* p1, long* p2) {
    p1->vt = VT_I4;
    p1->lVal = *p2;
    return S_OK;
  }
  static void init(VARIANT* p) { VariantInit(p); }
  static void destroy(VARIANT* p) { VariantClear(p); }
};

If the collection held long s but the enumerator exposed VARIANT s, the _CopyVariantFromLong copy policy could be used to convert that data on demand. For example, if the prime number collection object was keeping a collection of long s, the following code would create an enumerator that could convert from long to VARIANT, as appropriate, during the client’s Next call:

STDMETHODIMP CPrimeNumbers::get__NewEnum(IUnknown** ppunkEnum) {
  *ppunkEnum = 0;

  typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
                        _CopyVariantFromLong, vector<long> >
          CComEnumVariantOnVectorOfLongs;

  CComObject<CComEnumVariantOnVectorOfLongs>* pe = 0;
  ... // The rest is the same!
}

The only difference between this example and the previous one is the enumerator type definition. Instead of building it using a vector of VARIANT s, we build it using a vector of long s. Because the data type of the collection is different from the data type of the enumerator, we simply provide a copy policy class whose copy method converts appropriately. This is an especially useful technique for mapping between whatever is the most convenient type to hold in your collection object and VARIANT s to support the VB For-Each syntax.

Giving CComEnumOnSTL Its Own Copy

As I mentioned, unlike CComEnum, CComEnumOnSTL doesn’t provide an option to copy the data the collection holds. Instead, it assumes that it will share the data with the collection. Sometimes, this can lead to undefined behavior if the collection is being modified while it is also being enumerated. All is not lost, however. It is possible to give a CComEnumOnSTL object its own copy of the data. The key is to build a COM object whose job it is to hold the original container for the life of the enumerator. Then, when Init is called, pUnkForRelease is the pointer to this container copy object. When the enumerator is done, it releases the container copy object, thus destroying the copy of the data. Unfortunately, ATL provides no such class. Fortunately, it’s easy to build one. CComContainerCopy is a generic class for holding a copy of a standard C++ container. The complete implementation follows:

template <typename CollType, typename ThreadingModel =
  CComObjectThreadModel>
class CComContainerCopy :
  public CComObjectRootEx<ThreadingModel>,
  public IUnknown { // CComEnumOnSTL only needs an IUnknown*
public:
  HRESULT Copy(const CollType& coll) {
    try {
      m_coll = coll;
      return S_OK;
    }
    catch(...) {
      return E_OUTOFMEMORY;
    }
  }

BEGIN_COM_MAP(CComContainerCopy)
    COM_INTERFACE_ENTRY(IUnknown)
END_COM_MAP()

  CollType m_coll;
};

Notice that the CComContainerCopy class is parameterized by the type of collection it is to hold. This class can be used to copy any standard C++-like container. The Copy method copies the collection using assignment. Because the CComContainerCopy class derives only from IUnknown, it is ideally suited for one purpose: as the first argument to IEnumOnStlImpl’s Init method. The second argument is the public m_coll member. Using the Copy method of the CComContainerCopy class mimics the use of the CComEnum class’s AtlFlagCopy. The collection already has the data in the appropriate format, but the enumerator should have its own copy. Populating the m_coll member of the CComContainerCopy directly works like AtlFlagTakeOwnership. The collection doesn’t already have the data in the appropriate format, but the container has converted the data for use by the enumerator. An example of CComContainerCopy using the Copy method follows:

STDMETHODIMP CPrimeNumbers::get__NewEnum(IUnknown** ppunkEnum) {
  *ppunkEnum = 0;

  typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
                        _Copy<VARIANT>, vector<VARIANT> >
          CComEnumVariantOnVector;

  CComObject<CComEnumVariantOnVector>* pe = NULL;
  HRESULT hr = CComObject<CComEnumVariantOnVector>::CreateInstance(&pe);
  if (SUCCEEDED(hr)) {
    pe->AddRef();

    // Create the container copy
    CComObject< CComContainerCopy< vector<VARIANT> > >*
      pCopy = NULL;
    // Use pCopy as a scoping mechanism to bind to the
    // static CreateInstance
    hr = pCopy->CreateInstance(&pCopy);
    if (SUCCEEDED(hr)) {
      pCopy->AddRef();

      // Copy the C++ container to the container copy
      hr = pCopy->Copy(m_rgPrimes);
      if (SUCCEEDED(hr)) {

        // Init the enumerator with the copy
        hr = pe->Init(pCopy->GetUnknown(), pCopy->m_coll);
        if (SUCCEEDED(hr)) {
          hr = pe->QueryInterface(ppunkEnum);
        }
      }
      pCopy->Release();
    }
    pe->Release();
  }

  return hr;
}

On-Demand Data Calculation

CComEnum requires initialization with an array of data that is already calculated. CComEnumOnSTL, on the other hand, accesses the data by calling member functions on objects that we provide. Therefore, calculating data on demand is a matter of providing implementations of the member functions that perform the calculations instead of accessing precalculated results.

For example, there’s no reason the collection of prime numbers needs to precalculate all the results and store them. Instead, we need a standard C++-like container that looks like what CComEnumOnSTL needs (as I showed you before) but calculates the next prime number on demand. This container has two responsibilities. The first is to keep track of the range of values to iterate over. The second responsibility is to expose an iterator for both the beginning and one past the ending of the data. The beginning and ending iterator must be exposed via begin and end methods, and each must return a value of type const_iterator, a type nested inside the class. The PrimesContainer class lives up to both these responsibilities:

class PrimesContainer {
public:
  class const_iterator; // Forward declaration

  PrimesContainer() : m_min(0), m_max(0) {}

  // For IPrimeNumbers::CalcPrimes
  void SetRange(long min, long max)
  { m_min = min; m_max = max; }

  // For IPrimeNumbers::get_Count
  size_t size()
  { return CountPrimes(m_min, m_max); }

  // For IPrimeNumbers::get_Item
  long operator[](size_t i)
  { return NthPrime(i + 1, m_min, m_max); }

  // The rest is for CComEnumOnSTL
  const_iterator begin() const
  { return const_iterator(m_min, m_max); }

  const_iterator end() const
  { return const_iterator(); }

  class const_iterator {...};
private:
  long m_min, m_max;
};

Notice that, in addition to supporting the minimum interface required by the implementation of CComEnumOnSTL, the PrimesContainer class provides a SetRange method for managing the range of prime numbers, a size method for counting the prime numbers in the range, and an operator[] method for extracting items in a random-access fashion. These methods make the PrimesContainer class suitable for implementing the IPrimeNumbers interface.

class ATL_NO_VTABLE CPrimeNumbers :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CPrimeNumbers, &CLSID_PrimeNumbers>,
    public IDispatchImpl<IPrimeNumbers, &IID_IPrimeNumbers> {
public:
...
// IPrimeNumbers
public:
  STDMETHODIMP CalcPrimes(long min, long max)
  { m_rgPrimes.SetRange(min, max); return S_OK; }

  STDMETHODIMP get_Count(long* pnCount)
  { *pnCount = m_rgPrimes.size(); return S_OK; }

  STDMETHODIMP get_Item(long n, long* pnPrime) {
    if (n < 1 || n > m_rgPrimes.size() ) return E_INVALIDARG;
    *pnPrime = m_rgPrimes[n-1];
    return S_OK;
  }

  STDMETHODIMP get__NewEnum(IUnknown** ppunkEnum) {
    *ppunkEnum = NULL;

    typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT,
      VARIANT, _CopyVariantFromLong, PrimesContainer >
      CComEnumVariantOnPrimesContainer;

    CComObject<CComEnumVariantOnPrimesContainer>* pe = NULL;
    HRESULT hr = pe->CreateInstance(&pe);
    if (SUCCEEDED(hr)) {
      pe->AddRef();

      hr = pe->Init(this->GetUnknown(), m_rgPrimes);
      if (SUCCEEDED(hr)) {
        hr = pe->QueryInterface(ppunkEnum);
      }
      pe->Release();
    }
    return hr;
  }

  private:
    PrimesContainer m_rgPrimes;
};

In fact, this code is nearly identical to the code I’ve already shown you. The difference is that, instead of using a container that already has a precalculated set of values, we have one that knows how to calculate them on demand. Specifically, the iterator does the magic:

class PrimesContainer {
...
  const_iterator begin() const
  { return const_iterator(m_min, m_max); }

  const_iterator end() const
  { return iterator(); }

class const_iterator {
  public:
    const_iterator (long min = -1, long max = -1)
    : m_max(max), m_next(NthPrime(1, min, max))
    { if( m_next == -1 ) m_max = -1; } // Match end()

    bool operator!=(const const_iterator& rhs)
    { return (m_next != rhs.m_next || m_max != rhs.m_max); }

    const long& operator*()
    { return m_next; }

    const_iterator operator++(int) {
      const_iterator it(m_next, m_max);
      m_next = NthPrime(1, m_next + 1, m_max);
      if( m_next == -1 ) m_max = -1; // Match end()
      return it;
    }

  private:
    long m_next, m_max;
  };
...
};

The key to understanding the iterator is understanding how CComEnumOnSTL uses it. CComEnumOnSTL keeps a pointer to the collection, called m_pcollection, and an iterator, called m_iter, that marks the current position in the container. The m_iter data member is initialized when the enumerator is constructed or when Reset is called to the result of m_pcollection->begin(). The implementation of begin constructs an iterator that uses the range of possible prime numbers to cache the next prime number and the maximum number to check. As the container is iterated, the next prime number is calculated one ahead of the request. For every element in the container, the following sequence is performed:

1. m_pcollection->end() constructs an iterator that marks the end of the data. This, in turn, creates an iterator with 1 for each of m_min, m_max, and m_next. Special member data values are common for constructing an iterator that marks the end of the data.

2. operator!= compares the current iterator with the ending iterator.

3. operator* pulls out the prime number at the current location of the iterator.

4. The postfix operator++ calculates the next prime number. If there are no more prime numbers, m_min, m_max, and m_next are each set to 1 to indicate the end of the data. The next time through the loop, the comparison with the ending iterator succeeds and CComEnumOnSTL detects that it has reached the end of the collection.

You can see this behavior by looking at the main loop in the CComEnumOnSTLImpl::Next implementation:

template <class Base, const IID* piid, class T, class Copy,
  class CollType>
STDMETHODIMP
IEnumOnSTLImpl<Base, piid, T, Copy, CollType>::Next(
  ULONG celt, T* rgelt, ULONG* pceltFetched) {
  ...

  ULONG nActual = 0;
  HRESULT hr = S_OK;
  T* pelt = rgelt;
  while (SUCCEEDED(hr) &&
         m_iter != m_pcollection->end() && nActual < celt) {
    hr = Copy::copy(pelt, &*m_iter);
    if (FAILED(hr)) {
      while (rgelt < pelt) Copy::destroy(rgelt++);
      nActual = 0;
    }
    else {
      pelt++;
      m_iter++;
      nActual++;
    }
  }
  ...
  return hr;
}

If you find the occasion to calculate data on demand using a custom container and iterator pair, yours will be called in the same sequence. This gives you an opportunity to calculate data appropriately for your data set – for example, lines in a file, records in a database, bytes from a socket. Why go to all this trouble to calculate data on demand? Efficiency in both time and space. There are 9,592 prime numbers between 0 and 100,000. Precalculating and storing the primes as long s costs nearly 38 KB. Worse, the client must wait for all primes to be calculated in this range, even if it never gets around to enumerating them all. On the other hand, calculating them on demand requires the m_min and m_max members of the container and the m_next and m_max members of the current iterator. That’s 16 bytes no matter how many prime numbers we’d like to calculate, and the cost of calculating them is realized only when the client requests the next chunk. [4]

[4]

Of course, there are far more efficient ways to store and calculate prime numbers than what I have shown here. Even so, space versus time trade-offs make calculating on demand an attractive option.

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 class – For 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 keep – for example, vector<long> or PrimesContainer.

• The ItemType parameter indicates the type of data exposed from the iterator of the collection – for 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 number s, 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 CComEnumOnSTLImpl<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 VARIANT s. 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,
  _CopyVariantFromLong, vector<long> >
  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__NewEnum.
// Converts the storage type (long) to the item type (VARIANT).
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.

Standard C++ Collections of ATL Data Types

If you’re a fan of the standard C++ library, you might find yourself wanting to keep some of ATL’s smart types (such as CComBSTR, CComVariant, CComPtr, and CComQIPtr) in a standard C++ container. Many containers have a requirement concerning the elements they hold that makes this difficult for ATL smart types: operator& must return an address to an instance of the type being held. However, all the smart types except CComVariant overload operator& to return the address of the internal data:

BSTR* CComBSTR:operator&() { return &m_str; }
T** CComPtr::operator&()   { ATLASSERT(p==NULL); return &p; }
T** CComQIPtr::operator&() { ATLASSERT(p==NULL); return &p; }

These overloads mean that CComBSTR, CComPtr, and CComQIPtr cannot be used in many C++ containers or with standard C++ algorithms with the same requirement.The classic workaround for this problem is to maintain a container of a type that holds the ATL smart type but that doesn’t overload operator&. ATL provides the CAdapt class for this purpose.

ATL Smart Type Adapter

The CAdapt class is provided for the sole purpose of wrapping ATL smart types for use in C++ containers. It’s parameterized to accept any of the current or future such types:

template <class T> class CAdapt {
public:
    CAdapt() { }

    CAdapt(__in const T& rSrc) :
        m_T( rSrc )
    { }

    CAdapt(__in const CAdapt& rSrCA) :
        m_T( rSrCA.m_T )
    { }

    CAdapt& operator=(__in const T& rSrc)
    { m_T = rSrc; return *this; }

    bool operator<(__in const T& rSrc) const
    { return m_T < rSrc; }

    bool operator==(__in const T& rSrc) const
    { return m_T == rSrc; }

    operator T&()
    { return m_T; }

    operator const T&() const
    { return m_T; }

T m_T;
};

Notice that CAdapt does not have an operator&, so it works just fine for C++ containers and collections. Also notice that the real data is held in a public member variable called m_T. Typical usage requires using either this data member or a static_cast to obtain the underlying data.

CAdapt Usage

For example, imagine that you want to expose prime numbers as words instead of digits. Of course, you’d like the collection to support multiple languages, so you want to expose the strings in Unicode. Also, you’d like to support type-challenged COM mappings, so the strings have to be BSTR s. These requirements suggest the following interface:

[ object, dual]
interface IPrimeNumberWords : IDispatch {
  HRESULT CalcPrimes([in] long min, [in] long max);

  [propget]
  HRESULT Count([out, retval] long* pnCount);

  [propget, id(DISPID_VALUE)]
  HRESULT Item([in] long n,
    [out, retval] BSTR* pbstrPrimeWord);

  [propget, id(DISPID_NEWENUM)]
  HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum);
};

Notice that the Item property exposes the prime number as a string, not a number. Also keep in mind that although the signature of _NewEnum is unchanged, we will be returning VARIANT s to the client that contain BSTR s, not long numbers.

Because we’re dealing with one of the COM data types that’s inconvenient for C++ programmers, BSTR s, we’d like to use the CComBSTR smart data type described in Chapter 3, “ATL Smart Types.” The compiler doesn’t complain if we use a data member like this to maintain the data:

vector<CComBSTR> m_rgPrimes;

Unfortunately, depending on what we do with the vector, some obscure runtime errors can result because of CComBSTR’s overloaded operator&. Instead, we use CAdapt to hold the data:

vector< CAdapt<CComBSTR> > m_rgPrimes;

Of course, because we’re using strings, our method implementations change. To calculate the data, we change the prime numbers to strings:

STDMETHODIMP CPrimeNumberWords::CalcPrimes(long min, long max) {
  while (min <= max) {
    if (IsPrime(min)) {
      char sz[64];
      CComBSTR bstr = NumWord(min, sz);
      m_rgPrimes.push_back(bstr);
    }
    ++min;
  }

  return S_OK;
}

Notice how we can simply push a CComBSTR onto the vector. The compiler uses the CAdapt<CComBSTR> constructor that takes a const CComBSTR& to construct the appropriate object for the vector to manage. The get_Count method doesn’t change, but the get_Item method does:

STDMETHODIMP CPrimeNumberWords::get_Item(long n,
  BSTR* pbstrPrimeWord) {
  if (n < 1 || n > m_rgPrimes.size()) return E_INVALIDARG;

  CComBSTR& bstr = m_rgPrimes[n-1].m_T;
  return bstr.CopyTo(pbstrPrimeWord);
}

Notice that we’re reaching into the vector and pulling out the appropriate element. Again, remember that the type of element we’re holding is CAdapt<CComBSTR>, so I’ve used the m_T element to access the CComBSTR data inside. However, because the CAdapt<CComBSTR> class has an implicit cast operator to CComBSTR&, using the m_T member explicitly is not necessary.

Finally, the get__NewEnum method must also change. Remember that we’re implementing IEnumVARIANT, but instead of holding long numbers, we’re holding BSTR s. Therefore, the on-demand data conversion must convert between a CAdapt<CComBSTR> (the data type held in the container) to a VARIANT holding a BSTR. This can be accomplished with another custom copy policy class:

struct _CopyVariantFromAdaptBstr {
  static HRESULT copy(VARIANT* p1, CAdapt<CComBSTR>* p2) {
    p1->vt = VT_BSTR;
    p1->bstrVal = p2->m_T.Copy();
    return (p1->bstrVal ? S_OK : E_OUTOFMEMORY);
  }
  static void init(VARIANT* p) { VariantInit(p); }
  static void destroy(VARIANT* p) { VariantClear(p); }
};

The corresponding enumeration type definition looks like this:

typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
                        _CopyVariantFromAdaptBstr,
                        vector< CAdapt<CComBSTR> > >
        CComEnumVariantOnVectorOfAdaptBstr;

Using these two type definitions, implementing get__NewEnum looks much like it always does:

STDMETHODIMP CPrimeNumberWords::get__NewEnum(
  IUnknown** ppunkEnum) {
  *ppunkEnum = 0;

  CComObject<CComEnumVariantOnVectorOfAdaptBstr>* pe = 0;
  HRESULT hr = pe->CreateInstance(&pe);
  if( SUCCEEDED(hr) ) {
    pe->AddRef();

    hr = pe->Init(this->GetUnknown(), m_rgPrimes);
    if (SUCCEEDED(hr)) {
      hr = pe->QueryInterface(ppunkEnum);
    }

    pe->Release();
  }

  return hr;
}

Using ICollectionOnSTLImpl with CAdapt

If you want to combine the use of ICollectionOnSTLImpl with CAdapt, you already have half the tools: the custom copy policy and the enumeration type definition. You still need another custom copy policy that copies from the vector of CAdapt<CComBSTR> to the BSTR* that the client provides to implement get_Item. This copy policy can be implemented like this:

struct _CopyBstrFromAdaptBstr {
    static HRESULT copy(BSTR* p1, CAdapt<CComBSTR>* p2) {
    *p1 = SysAllocString(p2->m_T);
    return (p1 ? S_OK : E_OUTOFMEMORY);
  }

  static void init(BSTR* p) { }
  static void destroy(BSTR* p) { SysFreeString(*p); }
};

Finally, we can use CAdapt with ICollectionOnSTLImpl like this:

typedef IDispatchImpl<IPrimeNumberWords, &IID_IPrimeNumberWords>
        IPrimeNumberWordsDualImpl;

typedef ICollectionOnSTLImpl<IPrimeNumberWordsDualImpl,
                                vector< CAdapt<CComBSTR> >,
                                BSTR,
                                _CopyBstrFromAdaptBstr,
                                CComEnumVariantOnVectorOfAdaptBstr>
        IPrimeNumberWordsCollImpl;

class ATL_NO_VTABLE CPrimeNumberWords :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CPrimeNumberWords,
    &CLSID_PrimeNumberWords>,
  public IPrimeNumberWordsCollImpl {
public:
...
// IPrimeNumberWords
public:
  STDMETHODIMP CalcPrimes(long min, long max) {
    while (min <= max) {
      if (IsPrime(min)) {
      char        sz[64];
      CComBSTR bstr = NumWord(min, sz);
      m_coll.push_back(bstr);
      }
      ++min;
    }

    return S_OK;
  }
};

ATL Collections

Using standard C++ puts one burden firmly on the shoulders of the developer: exception handing. Many calls into collections and algorithms can cause exceptions that must be caught before they leave the method boundary. [5] And because C++ exception handling requires the C runtime (CRT), the CRT libraries must be linked with any ATL project that uses the standard C++ library. Although ATL servers do link with the CRT by default, it remains the case that some ATL servers are built without the CRT; therefore, an alternative for the standard library is needed. ATL includes three classes that provide basic array, list, and map functionality that are not unlike the C++ vector, list, and map classes. In the spirit of ATL, none of these classes throws exceptions or requires the CRT. Arguably more compelling than freedom from the CRT, these classes are specialized to yield additional classes tailored for use with COM by automatically managing collections of types such as interfaces.

[5]

Letting a C++ or Win32 structured exception escape a COM method is illegal. All such exceptions must be caught and turned into appropriate HRESULT s. For more information on this topic, see Effective COM (Addison-Wesley, 1998), by Don Box, Keith Brown, Tim Ewald, and Chris Sells.

CAtlArray

This class is a dynamically sized array that grows on demand. It is a template class, so it can hold any kind of data. Its declaration is as follows:

template< typename E, class ETraits = CElementTraits< E > >
class CatlArray {

public:
    CAtlArray() ;
    ~CAtlArray() ;

    size_t GetCount() const ;
    bool IsEmpty() const ;
    bool SetCount( size_t nNewSize, int nGrowBy = -1 );

    void FreeExtra() ;
    void RemoveAll() ;

    const E& GetAt( size_t iElement ) const;
    E& GetAt( size_t iElement );

    const E* GetData() const ;
    E* GetData() ;

    void SetAt( size_t iElement, INARGTYPE element );
    void SetAtGrow( size_t iElement, INARGTYPE element );

    size_t Add();
    size_t Add( INARGTYPE element );
    size_t Append( const CAtlArray< E, ETraits >& aSrc );

    void Copy( const CAtlArray< E, ETraits >& aSrc );

    const E& operator[]( size_t iElement ) const;
    E& operator[]( size_t iElement );

    void InsertAt( size_t iElement, INARGTYPE element,
        size_t nCount = 1 );
    void InsertArrayAt( size_t iStart,
        const CAtlArray< E, ETraits >* paNew );
    void RemoveAt( size_t iElement, size_t nCount = 1 );

#ifdef _DEBUG
    void AssertValid() const;
#endif // _DEBUG

// Implementation
private:
    E* m_pData;
    size_t m_nSize;
    size_t m_nMaxSize;
    int m_nGrowBy;

    // Private to prevent use
    CAtlArray( const CAtlArray& ) ;
    CAtlArray& operator=( const CAtlArray& ) ;
};

The class members manage the memory associated with the m_pData member, a dynamically sized array of type E. The second template parameter (Etraits) to the CAtlArray class is the key to understanding how ATL supports collections of different element types. This class provides methods for copying elements, comparing elements, moving elements, and computing element hash values for building hash tables. By default, CAtlArray uses a template class called CElementTraits that supplies implementations of these element policies that are appropriate for simple data types. Storing more complex objects typically requires “overriding” these default policies by passing in an alternate class for the ETRaits parameter. Indeed, you’ll see in a moment that ATL does precisely this to provide more specialized collection classes for dealing with commonly used types such as interfaces.

Here are the five static member functions and two typedefs ATL expects you to provide for the class specified as the Etraits template parameter. In these method signatures, T represents the element type.

typedef const T& INARGTYPE; // type to be used for
                            // adding elements
typedef T& OUTARGTYPE;      // type to be used for
                            // retrieving elements

static bool CompareElements( const T& element1,
  const T& element2 );

static int CompareElementsOrdered( const T& element1,
  const T& element2 );

static ULONG Hash( const T& element ) ;

static void CopyElements( T* pDest, const T* pSrc,
  size_t nElements );

static void RelocateElements( T* pDest, T* pSrc,
  size_t nElements );

The default CElementTraits class that AtlArray uses ultimately resolves to CDefaultElementTraits when primitive types such as int and bool are specified as the array element type. This class supplies the required static member functions through three base classes, one providing the comparison policy, one encapsulating the hashing algorithm, and another supplying the correct element copy semantics.

template< typename T >
class CDefaultElementTraits :
    public CElementTraitsBase< T >,
    public CDefaultHashTraits< T >,
    public CDefaultCompareTraits< T >
{ ... };

ATL provides template specializations of the CElementTraits class that automatically handle the unique comparison and copying semantics of the CComBSTR and CComVariant smart types. Additionally, a different hashing algorithm is used forthese types to produce a better statistical distribution of hash keys than would result with the trivial algorithm used for primitive types.

For dealing with arrays of interfaces, ATL provides CInterfaceArray. Its definition simply derives from CAtlArray and uses CComQIPtr as the array element type and a special interface-savvy element traits class.

template< class I, const IID* piid = &__uuidof( I ) >
class CInterfaceArray :
  public CAtlArray< ATL::CComQIPtr< I, piid >,
    CComQIPtrElementTraits< I, piid > >
{ ... }

A special array type called CAutoPtrArray is also available for dealing with arrays of smart pointers. It is also defined in terms of CAtlArray.

template< typename E >
class CAutoPtrArray :
  public CAtlArray< ATL::CAutoPtr< E >,
    CAutoPtrElementTraits< E > >
{ ... }

Here’s how you might use CInterfaceArray in code:

void GetPrimes(CInterfaceArray<IPrimeCalc>* prgCalc) {
  // Declare array of IPrimeCalc interface pointers
  CInterfaceArray<IPrimeCalc> rgCalc;

  // Populate array
  for (int i = 0; i < 50; i++) {
    IPrimeCalc* pCalc = NULL;
    ::CoCreateInstance(CLSID_CPrimeCalc, NULL, CLSCTX_ALL,
      __uuidof(pCalc), (void**)&pCalc);

    rgCalc[i] = pCalc; // ERROR: operator[] doesn't grow array

    rgCalc.Add(pCalc); // grows array, inserts, calls AddRef
    pCalc->Release();
  }

  *prgCalc = rgCalc; // ERROR: operator= marked private
                     // to prevent use

  prgCalc->InsertArrayAt(0, &rgCalc); // OK, prgCalc has
                                      // 50 AddRef'd itfs
} // CInterfaceArray destructor calls
  // Release on all elements in rgCalc

Unfortunately, CAtlArray isn’t very useful for implementing an enumeration interface, even though it could be easily used with CComEnum, because you’re not likely to want to hold data in the same type as is being enumerated. Because CComEnum doesn’t support conversion on demand as CComEnumOnSTL does, you must manually convert your CAtlArray data into an array of data appropriate for enumerating.

CAtlList

The CAtlList collection class provides a convenient way to store objects in an ordered list. Compared to CAtlArray, inserting elements into CAtlList is quite fast because it occurs in constant time. However, you can’t access the elements in a list by index as you can with an array. Like its array-based cousin, CAtlList is defined in terms of an element traits class that encapsulates the details of dealing with individual items in the list.

template< typename E, class ETraits = CElementTraits< E > >
class CAtlList {
public:
    typedef typename ETraits::INARGTYPE INARGTYPE;

private:
    class CNode : ... {
    ...
    public:
        CNode* m_pNext;
        CNode* m_pPrev;
        E m_element;
    };

public:
    CAtlList( UINT nBlockSize = 10 ) ;
    ~CAtlList() ;

    size_t GetCount() const ;
    bool IsEmpty() const ;

    E& GetHead() ;
    const E& GetHead() const ;
    E& GetTail() ;
    const E& GetTail() const ;
    E RemoveHead();
    E RemoveTail();
    void RemoveHeadNoReturn() ;
    void RemoveTailNoReturn() ;

    POSITION AddHead();
    POSITION AddHead( INARGTYPE element );
    void AddHeadList( const CAtlList< E, ETraits >* plNew );

    POSITION AddTail();
    POSITION AddTail( INARGTYPE element );
    void AddTailList( const CAtlList< E, ETraits >* plNew );

    void RemoveAll() ;

    POSITION GetHeadPosition() const ;
    POSITION GetTailPosition() const ;
    E& GetNext( POSITION& pos ) ;
    const E& GetNext( POSITION& pos ) const ;
    E& GetPrev( POSITION& pos ) ;
    const E& GetPrev( POSITION& pos ) const ;

    E& GetAt( POSITION pos ) ;
    const E& GetAt( POSITION pos ) const ;
    void SetAt( POSITION pos, INARGTYPE element );
    void RemoveAt( POSITION pos ) ;

    POSITION InsertBefore( POSITION pos, INARGTYPE element );
    POSITION InsertAfter( POSITION pos, INARGTYPE element );

    POSITION Find( INARGTYPE element,
        POSITION posStartAfter = NULL ) const ;
    POSITION FindIndex( size_t iElement ) const ;

    void MoveToHead( POSITION pos ) ;
    void MoveToTail( POSITION pos ) ;
    void SwapElements( POSITION pos1, POSITION pos2 ) ;

// Implementation
private:
    CNode* m_pHead;
    CNode* m_pTail;
    CNode* m_pFree;
    ...
};

This class manages a doubly linked list of CNode objects, each of which simply hold pointers to the data of the specified type (E), as well as pointers to the previous and next nodes in the list. Two list classes are also provided for dealing with smart pointers and interface pointers: CAutoPtrList and CInterfaceList. As with their array-based counterparts, these classes simply use CAtlList as their base class and specify type-specific element trait classes.

template< class I, const IID* piid = &__uuidof( I ) >
class CInterfaceList :
  public CAtlList< ATL::CComQIPtr< I, piid >,
    CComQIPtrElementTraits< I, piid > >
{ ... }

template< typename E >
class CAutoPtrList :
  public CAtlList< ATL::CAutoPtr< E >,
    CAutoPtrElementTraits< E > >
{ ... }

CAtlMap

If you want the functionality of the C++ map class, ATL provides CAtlMap:

template< typename K, typename V,
  class KTraits = CElementTraits< K >,
  class VTraits = CElementTraits< V > >
class CAtlMap {
public:
  typedef typename KTraits::INARGTYPE KINARGTYPE;
  typedef typename KTraits::OUTARGTYPE KOUTARGTYPE;
  typedef typename VTraits::INARGTYPE VINARGTYPE;
  typedef typename VTraits::OUTARGTYPE VOUTARGTYPE;

  class CPair : ... {
  public:
    const K m_key;
    V m_value;
  };

private:
  class CNode : public CPair { ... }

public:
  ...
  size_t GetCount() const ;
  bool IsEmpty() const ;

  bool Lookup( KINARGTYPE key, VOUTARGTYPE value ) const;
  const CPair* Lookup( KINARGTYPE key ) const ;
  CPair* Lookup( KINARGTYPE key ) ;
  V& operator[]( KINARGTYPE key ) ;

  POSITION SetAt( KINARGTYPE key, VINARGTYPE value );
  void SetValueAt( POSITION pos, VINARGTYPE value );

  bool RemoveKey( KINARGTYPE key ) ;
  void RemoveAll() ;
  void RemoveAtPos( POSITION pos ) ;

  POSITION GetStartPosition() const ;
  void GetNextAssoc( POSITION& pos, KOUTARGTYPE key,
    VOUTARGTYPE value ) const;
  const CPair* GetNext( POSITION& pos ) const ;
  CPair* GetNext( POSITION& pos ) ;
  const K& GetNextKey( POSITION& pos ) const ;
  const V& GetNextValue( POSITION& pos ) const ;
  V& GetNextValue( POSITION& pos ) ;
  void GetAt( POSITION pos, KOUTARGTYPE key,
    VOUTARGTYPE value ) const;
  CPair* GetAt( POSITION pos ) ;
  const CPair* GetAt( POSITION pos ) const ;
  const K& GetKeyAt( POSITION pos ) const ;
  const V& GetValueAt( POSITION pos ) const ;
  V& GetValueAt( POSITION pos ) ;

  UINT GetHashTableSize() const ;
  bool InitHashTable( UINT nBins, bool bAllocNow = true );
  void EnableAutoRehash() ;
  void DisableAutoRehash() ;
  void Rehash( UINT nBins = 0 );
  void SetOptimalLoad( float fOptimalLoad, float fLoThreshold,
    float fHiThreshold, bool bRehashNow = false );

// Implementation
private:
  CNode** m_ppBins;
  CNode* m_pFree;
  ...
};

CAtlMap maintains a list of nodes, each of which holds a key and a value. In this case, element trait classes must be provided for both the key type and the value type. The key is used to generate a hash for locating nodes in the list. CAtlMap would be useful for implementing collection item lookup by name instead of by index.

Be aware that CAtlMap does not have the same performance guarantees as the C++ std::map<> container. std::map<> uses a balanced binary tree that guarantees O(lg N) performance for inserts or lookups. CAtlMap, on the other hand, uses a hash table. Under good conditions, the hash table can give O(1) lookup performance, but a bad hash function can reduce the hash table to linear searches.

Object Models

A COM object model is a hierarchy of objects. Collections allow the subobjects to be manipulated. Enumerators allow these objects to be accessed. Most object models have one top-level object and several noncreateable subobjects. The following stylized IDL shows a minimal object model:

library OBJECTMODELLib {
    importlib("stdole32.tlb");
    importlib("stdole2.tlb");

    // Document sub-object ////////////////////////////////////
    [ object, dual ] interface IDocument : IDispatch {
      [propget] HRESULT Data([out, retval] BSTR *pVal);
      [propput] HRESULT Data([in] BSTR newVal);
    };

    coclass Document {
        [default] interface IDocument;
    };

    // Documents collection ///////////////////////////////////
    [ object, dual ] interface IDocuments : IDispatch {
      HRESULT AddDocument([out, retval] IDocument** ppDocument);
      [propget] HRESULT Count([out, retval] long* pnCount);
      [id(DISPID_VALUE), propget]
      HRESULT Item([in] long n, [out, retval] IDocument** ppdoc);
      [id(DISPID_NEWENUM), propget]
      HRESULT _NewEnum([out, retval] IUnknown** ppEnum);
    };

    coclass Documents {
        [default] interface IDocuments;
    };

    // Application top-level object ///////////////////////////
    [ object, dual ] interface IApplication : IDispatch {
      [propget] HRESULT Documents(
        [out, retval] IDocuments** pVal);
    };

    coclass Application {
        [default] interface IApplication;
    };
};

An instance hierarchy of this object model looks like Figure 8.3.

Figure 8.3. Simple object model instance hierarchy

Implementing the Top-Level Object

The top-level object of an object model is createable and exposes any number of properties and any number of collection subobjects. The example implementation looks like the following:

class ATL_NO_VTABLE CApplication :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CApplication, &CLSID_Application>,
    public IDispatchImpl<IApplication, &IID_IApplication> {
public:
DECLARE_REGISTRY_RESOURCEID(IDR_APPLICATION)
DECLARE_NOT_AGGREGATABLE(CApplication)
DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CApplication)
    COM_INTERFACE_ENTRY(IApplication)
    COM_INTERFACE_ENTRY(IDispatch)
END_COM_MAP()

  // Create instance of the Documents collection
  HRESULT CApplication::FinalConstruct()
  { return CDocuments::CreateInstance(&m_spDocuments); }

// IApplication
public:
  // Hand out the Documents collection to interested parties
  STDMETHODIMP CApplication::get_Documents(IDocuments** pVal)
  { return m_spDocuments.CopyTo(pVal); }

private:
  CComPtr<IDocuments> m_spDocuments;
};

Implementing the Collection Object

The collection object is the most difficult of the three layers to implement, not because of any difficult code, but because of the maze of type definitions. The first set is required to implement the enumerator:

template <typename T>
struct _CopyVariantFromAdaptItf {
  static HRESULT copy(VARIANT* p1, CAdapt< CComPtr<T> >* p2) {
    HRESULT hr = p2->m_T->QueryInterface(IID_IDispatch,
      (void**)&p1->pdispVal);
    if (SUCCEEDED(hr)) {
      p1->vt = VT_DISPATCH;
    }
    else {
      hr = p2->m_T->QueryInterface(IID_IUnknown,
        (void**)&p1->punkVal);
      if( SUCCEEDED(hr) ) {
        p1->vt = VT_UNKNOWN;
      }
    }

    return hr;
  }

  static void init(VARIANT* p) { VariantInit(p); }
  static void destroy(VARIANT* p) { VariantClear(p); }
};
typedef CComEnumOnSTL<IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
  _CopyVariantFromAdaptItf<IDocument>,
  list< CAdapt< CComPtr<IDocument> > > >
  CComEnumVariantOnListOfDocuments;

The _CopyVariantFromAdaptItf class is a reusable class that converts an interface into a VARIANT for use in enumerating a collection of interface pointers. The collection object is expected to hold a C++ container of elements of type CAdapt<CComPtr<T>>. Notice how the copy policy is used in the type definition of CComEnumVariantsOnListOfDocuments to obtain the implementation of IEnumVARIANT for the collection object.

The next set of type definitions is for the implementation of the collection methods:

template <typename T>
struct _CopyItfFromAdaptItf {
    static HRESULT copy(T** p1, CAdapt< CComPtr<T> >* p2) {
    if( *p1 = p2->m_T ) return (*p1)->AddRef(), S_OK;
    return E_POINTER;
  }

  static void init(T** p) {}
  static void destroy(T** p) { if( *p ) (*p)->Release(); }
};

typedef ICollectionOnSTLImpl<
  IDispatchImpl<IDocuments, &IID_IDocuments>,
  list< CAdapt< CComPtr<IDocument> > >,
  IDocument*,
  _CopyItfFromAdaptItf<IDocument>,
  CComEnumVariantOnListOfDocuments>
  IDocumentsCollImpl;

The _CopyItfFromAdaptItf is used to implement the Item property, again assuming a C++ container holding elements of type CAdapt<CComPtr<T>>. The copy policy is then used to define the collection interface implementation, IDocumentsCollImpl.

Finally, IDocumentsCollImpl is used as the base class of the IDocuments implementation:

class ATL_NO_VTABLE CDocuments :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CDocuments>, // noncreateable
    public IDocumentsCollImpl
{
public:
DECLARE_NO_REGISTRY()
DECLARE_NOT_AGGREGATABLE(CDocuments)
DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CDocuments)
    COM_INTERFACE_ENTRY(IDocuments)
    COM_INTERFACE_ENTRY(IDispatch)
END_COM_MAP()

// IDocuments
public:
  STDMETHODIMP AddDocument(IDocument** ppDocument) {
    // Create a document to hand back to the client
    HRESULT hr = CDocument::CreateInstance(ppDocument);
    if( SUCCEEDED(hr) ) {
      // Put the document on the list
      CComPtr<IDocument> spDoc = *ppDocument;
      m_coll.push_back(spDoc);
    }

    return hr;
  }
};

The benefit of all the type definitions is that the standard methods of the collection are implemented for us. We only have to implement the AddDocument method, which creates a new CDocument and adds it to the list that the ICollectionOnSTLImpl base class maintains.

Implementing the Subobjects

The subobjects can do whatever you want, including maintaining collections of objects further down the hierarchy. Our example maintains a BSTR, representing its data:

STDMETHODIMP CDocument::get_Data(BSTR *pVal) {
  return m_bstrData.CopyTo(pVal);
}
STDMETHODIMP CDocument::put_Data(BSTR newVal) {
  m_bstrData = newVal;
  return (m_bstrData || !newVal ? S_OK : E_OUTOFMEMORY);
}

Using the Object Model

You normally design an object model to be used by many language mappings, including scripting environments. Here’s an example HTML page that uses this example object model:

<html>
<script language=vbscript>
    dim app
    set app = CreateObject("ObjectModel.Application")

    dim docs
    set docs = app.Documents

    dim doc
    set doc = docs.AddDocument
    doc.Data = "Document 1"

    set doc = docs.AddDocument
    doc.Data = "Document 2"

    for each doc in docs
        msgbox doc.data
    next
</script>
</html>

Summary

COM has abstractions much like those of the C++ standard library. Collections maintain lists of things, often objects. Enumerators enable navigation over the list of things maintained in a collection. To standardize access to collections and enumerators, they have a standard protocol. These standards aren’t required, but if they are followed, they make an object model programmer’s life easier because the usage is familiar. Implementing an object model is a matter of defining the higher-level object, the lower-level object, and the collection that joins the two. ATL implements both collection and enumeration interfaces, if you’re not afraid of the type definitions required to make it all work.