Handling Aggregation

This section explains how the aggregatable and aggregates attributes are used to control the aggregation behavior of COM components .

Review of COM Aggregation and Delegation

Before discussing keywords, Ill provide a quick review of COM aggregation and delegation, because the distinctions between the two are often not understood very well by COM programmers. Delegation means that one COM object creates another and delegates method calls on one or more interfaces to the created object, as shown in Figure 6-7.

Figure 6-7: COM delegation does not expose the delegated object to the client.

Client code sees only the outer object, and the inner object is private . Lifetime and interface management is simple because the inner object is used only by its creator. One of the main advantages of delegation lies in being able to selectively expose functionality from inner objects: you can filter the data being passed to calls or even decide not to expose some interfaces or methods at all. The main disadvantage of delegation is that the outer object has to be written to perform the delegation. Delegation has no special support from ATL because the code needed to work with a delegated object will be different in each case.

If delegation is essentially a code reuse mechanism, aggregation is a COM identity trick used to create one logical COM object out of two or more physical objects. When one COM object aggregates another, it provides the identitythe GUIDfor the aggregate, but this time the inner object exposes its interfaces directly to the client. This is shown in Figure 6-8.

Figure 6-8: COM aggregation exposes aggregated interfaces to the client.

The outer object creates the inner object, and the clientunder the impression that it is talking to a single objecttalks directly to both of them. This necessitates cooperation between the inner and outer objects to maintain reference counts and handle QueryInterface calls. This support is provided by ATL.

The aggregatable and aggregates Attributes

The aggregatable attribute is used to indicate whether a coclass wants to be aggregated. It can take one of three values:

• allowed , meaning the coclass can be instantiated as aggregated or stand-alone.

• never , meaning the coclass cannot be instantiated as an aggregated object. If an attempt is made to do so, the class factory will return CLASS_E_NOAGGREGATION .

• always , meaning the coclass must be instantiated as an aggregated object. If an attempt is made to create a stand-alone object, the class factory will return E_FAIL .

Heres an example of the attribute in use:

 [coclass,aggregatable(always)] classMyClass { //... }; 

These values correspond to the yes , no , and always choices presented by the ATL Object Wizard. The default attribute parameter is allowed , so you wont see this attribute in the generated code if you choose the yes option in the wizard.

The aggregates attribute is used to specify one or more objects that are going to be aggregated by a class. For example

 //ThisclassaggregatesinstancesoftheCObject1 //andCObject2classes [coclass, aggregates(__uuidof(CObject1)), aggregates(__uuidof(CObject2)) ] classMyClass { }; 

By default, the aggregates attribute will add a COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND entry to the objects interface map, which will expose all the interfaces in the aggregated object. If you dont want to do this, you can use the com_interface_entry attribute to specify individual interfaces on aggregated objects, like this:

 [coclass, com_interface_entry("COM_INTERFACE_ENTRY_AGGREGATE(__uuidof(IAbc),pUnk)") ] classMyClass { //... }; 

In this example, the COM_INTERFACE_ENTRY_AGGREGATE macro puts an entry in the interface map so that all calls to interface IAbc are forwarded to the object whose IUnknown pointer is passed as the second parameter. This second parameter will typically be a data member of the class to which the attribute is being applied.