The ATL Object Wizard

---

Once you have created the component housing using the ATL COM AppWizard, you need to insert the coclasses themselves. To insert ATL-based COM classes into your project, you access the ATL Object Wizard. Activate this tool by right-clicking on your project node from ClassView, and select New ATL Object from the context menu (this tool is also available from the Insert | New ATL Object menu selection as well as the ATL toolbar).

Figure 6-12: Accessing the Object Wizard.

Note 

Many of ATL's wizards are accessed from the ClassView tab. If you are not in the habit of using this aspect of the VC++ IDE, begin doing so now.

The Object Wizard specifies four categories of COM objects that you may insert into your component home, as shown in Figure 6-13. While you use the ATL COM AppWizard once per project, the Object Wizard is used numerous times throughout the development of your ATL COM servers. A single server may contain any number of, and types of, ATL objects. Be aware, however, that some objects make little sense in the context of EXE servers (such as ActiveX controls, which are always loaded in-proc).

Figure 6-13: The ATL Object Wizard allows you to insert COM objects into component housing generated by the ATL COM AppWizard.

Following is a breakdown of each object type.

The Objects Category

The Objects category allow you to insert "traditional" object types as well as more specialized COM items such as MMC Snap Ins. In general, selections from the Objects category do not provide much by way of an interactive user interface, but instead focus on COM-based "business objects" (i.e., no GUI and all logic). Here is a rundown of each selection from the Objects category:

• Simple Object: If you are interested in creating a COM "business object" containing no user interface, this will be your object of choice. These objects are equipped with an IUnknown implementation and a default class factory. This is the "minimal and complete" coclass.

• Add-in Object: This selection allows you to create a COM component that integrates into the Visual C++ IDE, complete with a toolbar button and event handling support, allowing your coclass to respond to various Visual Studio commands. Objects of this type support and implement the IDSAddIn interface which provides the methods for the VC IDE and your object to communicate.

• Internet Explorer Object: A coclass with the necessary interfaces required by Internet Explorer, but without a UI. This coclass implements the IObjectWithSite interface, which provides a lightweight way to "site" your object in the container, allowing the object to communicate with IE. ATL provides an implementation of this interface with the IObjectWithSiteImpl<> template.

• ActiveX Server Component: A non-GUI server-side coclass equipped to run in an Active Server Page (ASP) under Internet Information Server (IIS). Allows the object to handle Request, Session, Response, Application, and Server objects.

• MMC SnapIn: Creates a COM framework used to create an extension to the Microsoft Management Console (MMC). Provides support for object persistence as well as the required COM interfaces used to communicate with the MMC GUI shell (such as menus, property sheets, and toolbars).

• MTS Component: Creates a new coclass configured to run under control of the Microsoft Transaction Server (MTS) runtime. The property sheet for MTS objects provides an option to support the IObjectControl interface which allows an object running under the MTS runtime to do any necessary initialization or clean up when it is activated or deactivated by the MTS runtime.

• Component Registrar Object: Creates a coclass supporting the IComponentRegistrar interface. This allows you to develop an object providing programmatic control over the process of registering and unregistering components in your server. ATL projects already provide default registration support operating on every coclass defined in the object map; however, if you wish to selectively register or unregister individual objects in a server, this is the option for you.

The Controls Category

The next set of options comes by way of the Controls category as shown in Figure 6-14.

Figure 6-14: Types of ActiveX controls supported by ATL 3.0.

Here you will find three different variations of GUI-based ActiveX controls, each providing a Lite and Full version. Full controls support the entire set of necessary COM interfaces needed to function in any ActiveX-compliant container. The only down side of Full controls is you may end up with implementation code you will never access (depending on the requirements of the container), resulting in some marginal code bloat.

Lite controls are slimmed-down versions of their Full counterparts and do offer a smaller footprint; however, they are not guaranteed to function in each and every ActiveX control container. For example, Lite controls will not function correctly if placed inside MS Office 97 containers. Chances are, you can live with a small amount of code bloat for the resulting peace of mind. Here are the choices provided by the Controls section:

• Full/Lite Controls: A traditional ActiveX control. Supports the required COM interfaces for screen rendering, property persistence, and in-place activation.

• Full/Lite Composite Controls: ActiveX controls which may contain other ActiveX controls as part of their makeup. Visual Basic developers (since the release of VB 5) have been given the ability to create ActiveX controls in a drag-and-drop environment. ATL composite controls provide similar support for C++ developers.

• Full/Lite HTML Controls: Creates a control project supporting DHTML. This ATL object type allows you to create controls that can access the IE object model, which in turn provides access to the rendering, scripting, and browsing support provided by the container.

• Property Page: Although not an ActiveX control, property pages are also found under the Controls category, as they provide a design-time mechanism used to configure ActiveX controls.

Remaining Object Wizard Selections

As for the remaining two Object Wizard selections, the Miscellaneous category currently provides only a single selection: dialog box. This option allows you to insert a traditional Windows dialog box into your server project. These dialogs are implemented with help from ATL base classes, but provide no COM-related functionality (for example, ATL dialog boxes do not implement any COM interfaces). Just to remind you, ATL dialogs do not offer the same level of support as found in MFC, and are basically a thin C++ wrapper around the Win32 APIs.

Finally, the Data Access category gives you the option to create ATL objects using the OLE DB (OLE database) protocol. OLE DB supports the vision of universal data access whereby a database client (called data consumers in OLE DB-speak) can access data held in numerous formats through a set of COM interfaces. From this tab you may create OLE DB providers or OLE DB consumers. We will not be covering data access object types in this book. OLE DB is a book (or two) in its own right.

Inserting a Simple Object

Each object you select from the Object Wizard will launch a unique property sheet allowing you to configure various attributes for your new coclass. The number of tabs (and what they allow you to specify) for an object's property sheet will vary depending on the type of object you have selected. Let's insert a Simple Object named CoHexagon into the ATLShapesServer.dll project. Simple objects have two configuration tabs: Names and Attributes. Figure 6-15 illustrates the Names tab:

Figure 6-15: Configuration options for an ATL Simple Object.

From this tab, you configure the C++ source code names (class name, header file, and CPP file) and the COM-related names. All choices are based on the Short Name edit box, and may be modified to your liking. The *.h and *.cpp files for the coclass will be named according to the .H File and .CPP File edit boxes. The name of the class is controlled (of course) from the Class field.

The COM names selections allow you to configure the name of the first interface supported by the coclass. Most often you will want to change the interface field, as this too is based on the "short name." Thus, the initial interface name for CoHexagon is set to ICoHexagon, which we will edit to be our good friend IDraw instead. Also notice that the ProgID is built using standard <ServerName.Coclass.Version> syntax. The Type field will be used to provide a simple string description of the COM object, which may be accessed by various object browser tools.

The Attributes tab (Figure 6-16) allows you to configure your object's threading model, aggregation support, and interface type. You can also specify whether your object supports the COM event protocol (Support Connection Points) and/or extended error information (Support ISupportErrorInfo). We examine these topics at a later time. CoHexagon will support a Custom interface, as this corresponds to the COM vTable interfaces we have been creating thus far. As well, we will support the default aggregation (Yes) and the Apartment threading model options.

Figure 6-16: Attributes for a Simple Object.

Note 

The default interface configuration is for a Dual, not Custom, interface. If you forget to check Custom, you will find your ATL coclass is derived from IDispatchImpl<> and the IDL definition is quite different. This option is used to configure scriptable COM objects, and will be fully detailed in Chapter 10.

When you hit the OK button, the ATL Object Wizard will insert a new Simple Object into your component housing. Figure 6-17 shows our new CoHexagon class from the ClassView tab. Notice that we see two IDraw interface jacks. The IDraw lollipop listed directly under the CCoHexagon class is used to navigate to the C++ implementations of the IDraw interface methods (currently none). The IDraw lollipop coming off the project node is used to navigate to the IDL code defining the interface methods (also currently none).

Figure 6-17: Navigating ATL source code with the ClassView tab.

Removing an ATL Coclass

The ATL Object Wizard is a great way to insert new coclasses into your project; however, this tool is completely clueless about how to remove a coclass. Sometimes you may wish to remove a class from an ATL project, and no matter how hard you look, you will not find a "Remove Coclass Wizard." When you wish to remove a coclass inserted by the wizard, you will need to follow these steps.

Assume you have added CoOops into your project using the ATL Object Wizard, and now wish to remove this from your project. First, you will need to edit your project's object map. Open your server's implementation file, and comment out (or remove) the offending map entry. As well, in this same file, comment out (or remove) the preprocessor #include call for the coclass's header file:

// Comment out the header file and OBJECT_ENTRY listing for the // class you wish to remove from your project. #include "stdafx.h" #include "resource.h" #include <initguid.h> #include "ATLShapesServer.h" #include " ATLShapesServer_i.c" // #include "CoOops.h" CComModule _Module; BEGIN_OBJECT_MAP(ObjectMap)      // OBJECT_ENTRY(CLSID_CoOops, CCoOops) END_OBJECT_MAP()

Now you will need to delete the code inserted into your IDL file. The Object Wizard will automatically write an interface definition for the [default] interface, as well as add a coclass definition to your library statement. Go into your IDL file and remove the offending code.

Next, you will need to edit your project's *.rc file. The simplest way to do so is to open this file from WordPad, and locate the section beginning with the REGISTRY comment. Carefully select the entire line of the offending resource (shown in bold below) and delete.

// REGISTRY IDR_COSTRINGREADER      REGISTRY DISCARDABLE "CoStringReader.rgs" IDR_COOOPS              REGISTRY DISCARDABLE "CoOops.rgs" 

Finally, you will need to remove the *.cpp, *.h, and *.rgs files from your project workspace. Open up your FileView tab, select the *.cpp file from the Source Files subdirectory and delete the file. Do the same for the header file and RGS file. You may also wish to go under the Windows Explorer and delete the CoOops.h, CoOops.cpp, and CoOops.rgs from your hard drive. Recompile the project, and code on.

Examining the Updated Project

Before we learn how to add methods to our IDraw interface, as well as support additional interfaces, we need to examine the changes made to the existing ATLShapesServer project. Because CoHexagon is a creatable COM object, you will find that your OBJECT_MAP has been updated with an OBJECT_ENTRY listing. The first parameter to this macro is the CLSID of the coclass (which ATL has supplied for you). The second parameter is the name of the C++ class representing your COM class:

// Recall the object map holds a list of all creatable coclasses in the server. BEGIN_OBJECT_MAP(ObjectMap)      OBJECT_ENTRY(CLSID_CoHexagon, CCoHexagon) END_OBJECT_MAP()

The ATL Object Wizard also updated your IDL file, providing an empty definition of the IDraw interface (with a new IID) and a coclass listing (with a new CLSID) in the server's library statement. The first interface added to a coclass is set to be the [default] for the coclass; however, you are always free to change this after the fact. Here are the relevant changes to our IDL file, after inserting CoHexagon:

Note 

Unlike MFC wizard-generated ODL code, you can rip apart ATL IDL generated code to your heart's content (within the syntactic constraints of IDL!) without breaking the tools.

// Updated IDL file. // The IDraw Interface. [     object, uuid(4A01DD02-066C-11D3-B8E5-0020781238D4),      helpstring("IDraw Interface"),      oleautomation,      /*added to enforce interface registration */      pointer_default(unique) ]      interface IDraw : IUnknown { }; // This coclass definition will appear within your library statement. [      uuid(4A01DD03-066C-11D3-B8E5-0020781238D4),           helpstring("CoHexagon Class") ] coclass CoHexagon {      [default] interface IDraw; };

As you would expect, the MIDL-generated files will also be updated with the next build, defining GUIDs, interface bindings, type information, and stub/proxy code as dictated by the CoHexagon coclass.

---