ATL Collections and Enumerators

A collection is a COM object that provides an interface that allows access to a group of data items (raw data or other objects). An interface that follows the standards for providing access to a group of objects is known as a collection interface.

At a minimum, collection interfaces must provide a Count property that returns the number of items in the collection, an Item property that returns an item from the collection based on an index, and a _NewEnum property that returns an enumerator for the collection. Optionally, collection interfaces can provide Add and Remove methods to allow items to be inserted into or deleted from the collection, and a Clear method to remove all items.

Note You can learn more about collection interfaces and the importance of the _NewEnum property to Visual Basic clients in the article Implementing OLE Automation Collections by Charlie Kindel.

An enumerator is a COM object that provides an interface for iterating through items in a collection. Enumerator interfaces provide serial access to the elements of a collection via four required methods Next, Skip, Reset, and Clone.

You can learn more about enumerator interfaces by reading about the archetypal (but entirely imaginary) IEnumXXXX interface.

Note There are different design principles behind each type of interface:

A collection interface provides random access to a single item in the collection via the Item method, it lets clients discover how many items are in the collection via the Count property, and often allows clients to add and remove items.
An enumerator interface provides serial access to multiple items in a collection, it doesn't allow the client to discover how many items are in the collection (until the enumerator stops returning items), and it doesn't provide any way of adding or removing items.

Each type of interface plays a different role in providing access to the elements in a collection.

ATL Classes

ATL provides the following classes to help you implement collections and enumerators.

Class	Description
ICollectionOnSTLImpl	Collection interface implementation
IEnumOnSTLImpl	Enumerator interface implementation (assumes data stored in an STL-compatible container)
CComEnumImpl	Enumerator interface implementation (assumes data stored in an array)
CComEnumOnSTL	Enumerator object implementation (uses IEnumOnSTLImpl)
CComEnum	Enumerator object implementation (uses CComEnumImpl)
_Copy	Copy policy class
_CopyInterface	Copy policy class
CAdapt	Adapter class (hides operator & allowing CComPtr, CComQIPtr, and CComBSTR to be stored in STL containers)

For an example of implementing an STL-based collection, see Implementing an STL-Based Collection.