Previous Page TOC Next Page



Appendix E


ActiveX Template Library


The ActiveX Template Library (ATL) was created to simplify the programming of COM objects. ATL enables you to focus on programming the functionality of your objects

This appendix defines what ATL is and when ATL should be used in your object development. In addition, this appendix outlines the software components contained within the ATL product.

What Is ATL?


ATL is a set of template-based C++ classes that enables developers to create fast, lightweight COM objects. Developers can define their own types of data that are specific to their own applications by using the template-based classes.

ATL simplifies object type definitions by the following:


What Object Model Does ATL Support?


ATL supports the key OLE COM (Component Object Model) features such as aggregation, dual interface, connection points, enumerations, and tear-off interfaces.

ATL also supplies a custom AppWizard, which can be used with Visual C++ 4.1 and later to create a basic skeleton of a COM object. This wizard is targeted for creating dual interfaces in particular. ATL can be used to create any arbitrary COM interface, however. The following sections discuss the COM Server interfaces and the threading model ATL supports.

COM Servers


The ATL supports the following COM servers:


Threading Model


The threading models ATL supports include No threading, Apartment-model threading, and free threading.

Interface Types


ATL supports many interface types, such as the following:


Other Interfaces


ATL also supports interfaces such as these:


Using ATL with C++ Frameworks?


The Microsoft File Class (MFC) is a C++ framework that contains standard, customizable implementations of the major OLE and ActiveX interfaces and the logic around their use. This makes it fairly simple to add, for example, the capability of hosting ActiveX controls in an MFC application, or to create an application that enables other applications to embed objects within it.

For creating advanced OLE- and ActiveX-based applications, such as ActiveX controls, ActiveX Documents, and regular embedded and linked objects, MFC is an excellent C++ framework.

To build them with ATL requires a significant amount of work, for relatively little gain.

ATL


ATL is focused primarily for creating COM servers that have specific requirements of size and speed. ATL is the best choice to create generic COM objects for OLE automation objects with dual interface support.

If your intent is to support the COM free threading model, which is available only under Windows NT 4.0 or later versions of Windows, ATL should be used.

ATL Software Product


ATL can be downloaded from http://www.microsoft.com/visualc/v42/atl/default.htm. The ATL is distributed in the form of a zip file that includes the following:


What Do I Need to Make Use of ATL?


ATL is contained in Visual C++ 4.x and the Win32 SDK products. Purchasing either of these products will give you the libraries and supportive documentation you need to get started.

Note


ATL can also be used with the NT 4.0 beta SDK component. The advantage of using the NT beta 4.0 beta version of the MIDL compiler is that you no longer have to maintain an ODL file in addition to your IDL file. For more information on the new MIDL compiler, see the NT 4.0 beta documentation.


How Do I Build an ATL Server?


ATL includes a custom AppWizard you can use to build a basic skeleton of your server application.

The following steps are necessary to create a new project with the custom AppWizard:

  1. 1. From the File menu, choose New, and then select Project Workspace.
  2. 2. Choose OLE COM wizard in the New Project Workspace dialog box.
  3. 3. Click the Finish button.
  4. 4. Use the Custom Build tab in the Project Settings dialog box to add the necessary custom build rules.
  5. 5. Add methods to your object's interface by modifying the IDL or ODL files if using older tools.
  6. 6. Modify the object's H file and specify the method there.
  7. 7. Modify the object's CPP file to specify the implementation of each method.
  8. 8. Build or rebuild all after having added all your methods.

Base Classes Provided with ATL


The next sections introduce some basic classes provided by ATL.

CComObjectRoot


All ATL COM objects are usually derived from the CComObjectRoot or CComObjectBase classes. CComObjectBase is inherited from CComObjectRoot.

CComISupportErrorInfoImpl


CComISupportErrorInfoImpl is inherited from ISupportErrorInfo.

ATL supports the OLE error reporting mechanism with the Error() member function in CComObjectBase and the CComISupportErrorInfoImpl classes. These classes each have a member, InterfaceSupportsErrorInfo(), which indicates that returning rich error information is supported.

CComTearOffObjectBase


Tear-off interfaces can be used for interfaces to an object that are likely to be used only rarely, or for groups of related interfaces. They enable some interfaces to be implemented in another object. This method saves four bytes that would be required for a virtual table (vtable) pointer when an object supports interfaces through multiple inheritance instead.

To do this, you declare a class that inherits from all the interfaces you want to implement in the tear-off interface and from CComTearOffObjectBase<CLSID*, class Owner>, where Owner is the class of the main object:


class CComTearOffObjectBase : public CComObjectBase<pclsid>

CComConnectionPoint


ATL supports the COM connection point mechanism with the CComConnectionPoint and CComConnectionPointContainerImpl classes.

The following gives the relationship between the classes:


class CComConnectionPointBase : public IConnectionPoint

class CComConnectionPoint : public CComConnectionPointBase

class CComConnectionPointContainerImpl : public IConnectionPointContainer

CComEnumImpl


ATL supports OLE automation collections with the CComEnumImpl class. This class enables you to specify whether you enumerate on the actual data or a copy of the data. You need to specify a class that provides the copy, init, and destroy member functions:


class CComEnumImpl : public Base
Note


The Base class is the user's class, which derives from CComObjectRoot and whatever interfaces the user wants to support on the object.

ATL is great tool that developers can use to create generic COM objects for OLE automation objects with dual interface support.

Previous Page Page Top TOC Next Page