Creating Component Housing with the ATL COM AppWizard

---

Your ATL projects begin by accessing the ATL COM AppWizard located under the File | New menu selection of the Visual C++ IDE (see Figure 6-2).

Figure 6-2: Creating a new ATL project workspace.

Once you provide the name of your ATL project, you will be presented with a one-step CASE tool named the ATL COM AppWizard, as shown in Figure 6-3. Based on your initial selections, you will receive a number of starter files representing your component housing.

Figure 6-3: The ATL COM AppWizard is used to generate boilerplate code for your component housing.

The ATL COM AppWizard offers four configuration choices used in constructing your component home. Below is an overview of the ATL COM AppWizard selections.

 On the CD   In this chapter we will be investigating an in-process server named ATLShapesServer.dll with no support for MFC, MTS, or merging of stub/proxy code. This project is included on the companion CD under the Labs\Chapter 06 subdirectory.

Specifying the Type of Server Housing

The Server Type section allows you to specify how you wish to package your COM objects. As we have already written in-proc, local, and remote servers in the first part of this book, these choices should be relatively clear.

• Dynamic Link Library: The ATL COM AppWizard will generate component housing for a COM-based DLL (in-proc) server. All DLL export functions will be fully implemented, and exposed through an associated DEF file.

• Executable: The ATL COM AppWizard will generate component housing for a COM-based EXE. A WinMain() implementation will be provided on your behalf.

• Service: The ATL COM AppWizard will generate component housing code for an EXE server which may be run as an NT service, a local server, or a remote server.

Once you have decided on the type of component housing, you have three remaining choices to make before beginning to insert coclasses into the AppWizard-generated code.

Note 

Each of the remaining options are only available when you create in-process (DLL) servers. Although it is possible to implement an EXE server using these options, you will be making the necessary modifications by hand.

Allow Merging of Proxy/Stub Code

You already know quite a bit about the role stubs and proxies play in COM development. Recall that if you restrict your COM servers to use only VARIANT compliant types, you can leverage the universal (type library) marshaler, and will not need a custom proxy/stub DLL at all. If you plan to use [oleautomation] restricted interfaces (as well as dual interfaces, which we address later), there is no need to check this box, as you will end up with a small amount of code bloat that is not actually required.

If you plan to build interfaces falling outside of the range of VARIANT compliant types, checking this option will add the necessary hooks to allow the custom proxy/stub code to be bundled inside of your DLL server, resulting in one less file to distribute. Of course, keep in mind that you are never required to merge your stub/proxy DLL into your in-proc server (every DLL server will work just fine if this option is unselected). This is just another design step to consider as you build your COM servers.

If you do select this option, the ATL COM AppWizard will generate two extra files for your project: dlldatax.h and dlldatax.c. As you recall, every COM-based DLL server must export DllCanUnloadNow(), DllRegisterServer(), DllUnregisterServer(), and DllGetClassObject() to interact with the COM runtime. In order to circumvent the name clashes resulting from two sets of DLL entry points (your server DLL and the stub/proxy DLL), dlldatax.c adjusts the entry points for the stub/proxy DLL:

// dlldatax.c // Server exports             stub/proxy exports #define DllMain               PrxDllMain #define DllRegisterServer     PrxDllRegisterServer #define DllUnregisterServer   PrxDllUnregisterServer #define DllGetClassObject     PrxDllGetClassObject #define DllCanUnloadNow       PrxDllCanUnloadNow

Dlldatax.h prototypes each "Prx-" function, which are implemented as in dlldatax.c as simple stub code. For example, here is the stub code for PrxDllCanUnloadNow():

// 'Prx-' functions are implemented as stub code to avoid name clashes // resulting from two sets of DLL export functions. STDAPI PrxDllCanUnloadNow(void) {      return S_OK; }

The remaining "Prx-" methods are implemented with similar stub code. In this way, the server is able to define one set of DLL exports. Now, although these files have been included into your project workspace, you must manually configure them before the stub and proxy code is actually merged into your server DLL. This three-step process begins by right-clicking on dlldatax.c (from FileView) and selecting Settings from the resulting context menu. From the General tab of the Project Settings dialog box, uncheck the Exclude file from build option:

Figure 6-4: Including dlldatax.c into your project's build.

Next, from the C/C++ tab, configure dlldatax.c with the Not using precompiled headers option, from the Precompiled Headers category (see Figure 6-5):

Figure 6-5: Removing precompiled header dependencies from dlldatax.c.

Finally, define the _MERGE_PROXYSTUB symbol for your program from the C/C++ tab under the Preprocessor category:

Figure 6-6: The final step to merge your stub/proxy DLL: define the preprocessor symbol _MERGE_PROXYSTUB.

At this point, your stub/proxy code will be merged into your DLL server. Doing so, however, is left to your discretion, as we will not do so in this book.

Note 

You must have at least one ATL coclass in your project before compiling a project merging stub and proxy code, as dlldatax.c is including dlldata.c, which will not exist until the MIDL compiler is run!

Support MFC (just say no)

This choice allows your ATL project to leverage the Microsoft Foundation Class (MFC) library. The chances of you needing to select this option should be slim to none. By doing so, you tie your ATL code to the MFC runtime library, and therefore must ensure the MFC runtime DLL is installed (and shipped) along with your ATL COM server. Most developers who feel compelled to select this option reason that there are a handful of MFC classes that they simply cannot live without (CString being the biggest offender). Resist this temptation! Although the CComBSTR class provided by ATL is not as robust as MFC's CString, it does provide you with a subset of the same functionality. With a bit of extra coding on your part, you can avoid dependency upon the MFC runtime DLL (which is approximately 970K in size). To illustrate:

// This string cost me 970K, enough said. CString strWasItWorthIt; strWasItWorthIt = "no"; 

In all fairness, there are times when linking to the MFC runtime might be beneficial. If you are developing a COM server which is only to be used by some legacy MFC application, you may wish to support MFC. Even then, however, you may wish to create an MFC COM server from the onset, as MFC COM servers can be easier to develop than ATL COM servers (more often than not).

Support Microsoft Transaction Server (MTS)

Checking this option will configure your project to access and interact with the MTS runtime by linking your project with the MTS libraries (mtx.lib and mtxguid.lib). MTS is a "super surrogate" that will host your COM-based DLL servers and provide a robust runtime environment, which we will not concern ourselves with at this time.

Confirming the New Project

The New Project Information dialog, shown in Figure 6-7, summarizes your selections. Once you select the component type and configure support for MFC, MTS, and merging of stub/proxy code, the wizard will whirl away for a moment, and dump a handful of new files into your project subdirectory.

Figure 6-7: New Project confirmation dialog.

At this point you can fully compile your DLL or EXE server; however, you will have a very lonely dwelling as no COM objects have yet been invited to the party. COM objects are inserted into ATL component housing using another CASE tool, the ATL Object Wizard. Before we begin inserting coclasses, let's examine the files generated by the ATL COM AppWizard.

---