Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

• Table of Contents
  • Copyright
  • About the Authors
  • About the Contributors
  • Acknowledgments
  • Tell Us What You Think!
  • Introduction
  • How to Use This Book
  • What You Need to Use This Book
  • What's New in Visual C++ 6.0
  • Contacting the Main Author
  • Part I: Introduction
  • Chapter 1. The Visual C++ 6.0 Environment
  • Part II: MFC Programming
  • Chapter 2. MFC Class Library Overview
  • Chapter 3. MFC Message Handling Mechanism
  • Chapter 4. The Document View Architecture
  • Chapter 5. Creating and Using Dialog Boxes
  • Chapter 6. Working with Device Contexts and GDI Objects
  • Chapter 7. Creating and Using Property Sheets
  • Chapter 8. Working with the File System
  • Chapter 9. Using Serialization with File and Archive Objects
  • Part III: Internet Programming with MFC
  • Chapter 10. MFC and the Internet Server API (ISAPI)
  • Chapter 11. The WinInet API
  • Chapter 12. MFC HTML Support
  • Part IV: Advanced Programming Topics
  • Chapter 13. Using the Standard C++ Library
  • Chapter 14. Error Detection and Exception Handling Techniques
  • Chapter 15. Debugging and Profiling Strategies
  • Chapter 16. Multithreading
  • Chapter 17. Using Scripting and Other Tools to Automate the Visual C++ IDE
  • Part V: Database Programming
  • Chapter 18. Creating Custom AppWizards
  • Chapter 19. Database Overview
  • Chapter 20. ODBC Programming
  • Chapter 21. MFC Database Classes
  • Chapter 22. Using OLE DB
  • Chapter 23. Programming with ADO
  • Part VI: MFC Support for COM and ActiveX
  • Chapter 24. Overview of COM and Active Technologies
  • Chapter 25. Active Documents
  • Chapter 26. Active Containers
  • Chapter 27. Active Servers
  • Chapter 28. ActiveX Controls
  • Part VII: Using the Active Template Library
  • Chapter 29. ATL Architecture
    • The History of ATL
    • ATL's Advanced Use of Templates
    • Commonly Used ATL Classes
    • Using the Interface Definition Language
    • ATL Wizards
    • Summary
  • Chapter 30. Creating COM Objects Using ATL
  • Chapter 31. Creating ActiveX Controls Using ATL
  • Chapter 32. Using ATL to Create MTS and COM+ Components
  • Part VIII: Finishing Touches
  • Chapter 33. Adding Windows Help
  • Part IX: Appendix

ATL Wizards

Two wizards are supplied by Visual C++ to simplify the building of custom COM objects with ATL:

• The ATL COM AppWizard helps you create a project that builds a module—a DLL, EXE, or service—that hosts COM classes.
• The ATL Object Wizard helps you add a COM object to your project.

These wizards are discussed in the next two sections.

Using the ATL COM AppWizard

The easiest way to create an ATL project is to use the ATL COM AppWizard. This wizard creates a skeleton project for you based on the type of project you select (see Figure 29.1).

Figure 29.1 The ATL COM AppWizard.

You can build three types of projects using the ATL COM AppWizard:

• DLL The module will be built as an in-process DLL. As discussed in previous chapters, this is the most efficient type of COM module.
• EXE The module will be built as an out-of-process server. As discussed in earlier chapters, this type of module is more robust than a DLL.
• Service The module will be built as a Windows NT or Windows 2000 service.

If you chose to build your project as a DLL, you have three additional options that are enabled in the lower half of the wizard page:

• Allow merging of proxy/stub code. Enables you to include the proxy/stub marshaling code in your DLL, thus reducing the effort required to deploy the DLL on other machines. If you do not enable this check box, you will need to distribute a separate proxy/stub DLL with the DLL that contains your COM server.
• Support MFC. Enables MFC support in your ATL project. If you absolutely cannot live without MFC, enable this check box.
• Support MTS. Adds the necessary MTS libraries to your project.

Given a project named JensCoffee, the ATL COM AppWizard will create the following files for your ATL project:

If you create a DLL project that allows the proxy/stub code to be merged, the following files are created:

The files are not automatically added to your project—you must follow the steps outlined later in the section "Merging the Proxy/Stub Code with Your DLL."

This file is created for all DLL-based projects:

Finally, the following file is created for all EXE and service projects:

Using the ATL Object Wizard

As discussed earlier, you use the ATL Object Wizard to add an ATL COM class to your project. You launch the ATL Object Wizard by choosing Insert, New ATL Object from the Visual C++ menu. The ATL Object Wizard appears, as shown in Figure 29.2.

Figure 29.2 The ATL Object Wizard.

You can choose from four categories of ATL classes to insert into your project:

• Objects Contains Active Server Page (ASP) components, Microsoft Management Console (MMC) snap-ins, Microsoft Transaction Server (MTS) components, and other basic COM components.
• Controls Contains controls suitable for embedding in ActiveX containers. These controls are discussed in Chapter 31, "Creating ActiveX Controls Using ATL."
• Miscellaneous Contains a dialog box that can be added to your project.
• Data Access Contains data provider and consumer classes.

Seven types of classes are offered in the Objects category:

• Simple Object Generates a simple COM class for the project.
• Add-In Object Creates a COM class that can extend the Visual C++ IDE.
• Internet Explorer Object Creates a non-visual COM class that can be hosted inside Internet Explorer.
• ActiveX Server Component Creates a COM class that can be used with Active Server Pages in IIS.
• MMC SnapIn Creates a class that can be used with Microsoft Management Console.
• MS Transaction Server Component Creates a COM server that can be used with MTS.
• Component Registrar Object Creates a class that enables you to register individual components in a DLL instead of registering all components at once.

After a component type has been selected, a property sheet is displayed that enables you to define attributes for the component. Some component types display specialized property pages specific to their object type. The MTS component includes an MTS page used only for that particular type of component, for example. All component types present a Names property page, as shown in Figure 29.3.

Figure 29.3 The Names property page contains naming attributes for ATL components.

Eight items are displayed on the Names property page:

• Short Name The name of the COM component.
• Class The name of the C++ class that implements the component. By default, this is the name of the component prefixed with a C.
• .H File The name of the header file for the component. By default, this is the name of the component with an .H extension.
• .CPP File The name of the implementation file for the component. By default, this is the name of the component with a .CPP extension.
• CoClass The name of the component's coclass. By default, this is the name of the component.
• Interface The name of the interface exposed by the component. By default, this is the name of the component prefixed with I.
• Type A description string stored in the System Registry under the component's Prog ID. By default, this is the name of the component, followed by Class.
• Prog ID The program ID for the component. By default, this is <project name>.<component name>. A project named JensCoffee that has a component named Latte, for example, would have a Prog ID of JensCoffee. Latte.

The second tab for most component types is the Attributes property page, which is used to collect information about the component, such as its threading model (see Figure 29.4).

Figure 29.4 The Attributes property page contains characteristics for ATL components.

The Attributes property page enables you to define the following properties for the component:

• Threading Model The threading model for the COM component. The options for this property follow:Single The component will always be created in the first STA (also known as the main STA) of the process.Apartment The component will be created in an STA.Both The component will be created in either an STA or the MTA, depending on the apartment of the caller.Free The component will be created in MTA of the process.
• Interface Select Dual for an Automation-compatible interface or Custom for a COM vtable interface.
• Aggregation The type of aggregation supported by the component. The options for this property follow:Yes The component can be aggregated by another component.No The component can not be aggregated by another component.Only The component must be aggregated by another component
• Support ISupportErrorInfo Adds support for the ISupportErrorInfo interface to your COM component.
• Support Connection Points Adds support for connection points to your component. Using connection points is discussed in Chapter 30.
• Free Threaded Marshaler Adds support for simplified marshaling of interface pointers between apartments (under some circumstances).

Given a component named Latte, the ATL Object Wizard creates the following files:

The ATL Object Wizard also modifies the following files:

Merging the Proxy/Stub Code with Your DLL

If your component uses custom interfaces, you must supply a DLL that contains a marshaling proxy and stub code. Normally, you compile a separate proxy/stub DLL that must be distributed and registered with your component. This DLL is created using the proxy/stub makefile that is created as part of the initial project. This file has the name <project>ps.mk. The JensCoffee project, for example, has a makefile named JensCoffeeps.mk that is used to create the proxy/stub DLL.

As discussed earlier in this chapter, the ATL COM AppWizard provides an option to allow proxy/stub DLL to be merged into the component's server DLL. If you select this option, the dlldatax.c and dlldatax.h files are added to your project. They will not be included in the build, however.

If you want to merge the proxy/stub into your DLL, you must follow these steps:

1. Go to the FileView tab in the Project Workspace and right-click on the dlldatax.c file. Choose Settings from the pop-up menu. The Project Settings dialog box appears.
2. On the General tab in the Project Settings dialog box, clear the Exclude File from Build check box. Keep the dialog box open.
3. Repeat this procedure for the dlldatax.h header file.
4. Click on the dlldatax.c file icon in the Project Workspace.
5. Keep the dialog box open and select the C++ tab.
6. Choose the Precompiled Headers category from the drop-down list, and select the Not Using Precompiled Headers radio button.
7. Choose the Preprocessor category, and add _MERGE_PROXYSTUB as a preprocessor definition. Make sure the new symbol is separated from the previous symbol by a comma.
8. Click OK to close the dialog box.

After the project has been built, the DLL that contains the component also will contain the code required for proxy/stub marshaling.

Share This