Beginning ATL COM Programming
Home About Workshops Articles Writing Talks Books Contact
ISBN: 1-861000-11-1
Richard Grimes, Alex Stockton, George Reilly, Julian Templeton, Karli Watson

Buy this book from Richard Grimes

Chapter 1

An Introduction to COM

COM is Microsoft's object model and ATL is the library of choice to use to program COM objects. The first question of course is why COM? The chapter starts with a one sentence description of COM and then leads on to explain COM terms like interfaces, objects and IUnknown. This leads on to a discussion on object lifetime, interface discoverability and versioning.

COM allows objects to be implemented in DLLs or EXEs and accessed on the same machine as the client or on a different machine. This cross process (strictly cross-apartment) communication requires marshaling and so the discussion covers how this applies to memory management and introduces the language used to describe interfaces: IDL.

The second half of this chapter covers writing a COM object and a client to use it. It covers the steps from defining the IDL, to implementing interfaces, implementing class factories, module locking and registration of objects.

Chapter 2

Building and Calling a COM Object Using ATL

This chapter starts by introducing you to the various tools provided by Visual C++ 5.0 to create and edit an ATL project. It shows you the various options of these tools and explains the code that is generated.

The chapter develops a simple server using ATL, and it also creates a client using ATL. This ma sound strange, but ATL has many classes that you can use even if you are not implementing an object server. In this case ATL is used to implement a simple dialog that will create and call a COM object. The chapter also introduces the reader to the new VC COM Compiler Support classes and the code generated by #import.

Chapter 3

ATL Architecture

This chapter is concerned with the actual template that an ATL class should use, what these templates do and how to use them. It also introduces you to the ATL maps that you will use and explains what they do to your class and why they are needed. The chapter also goes into greater depth about class factory templates and explains the difference between how these are implemented in DLLs and EXEs.

To illustrate which ATL templates and maps are needed, the first example in this chapter takes an ATL dialog class and adds COM support to this, thus step-by-step you see the support than you are adding and exactly what the code will do. The second example in this chapter illustrates COM aggregation.

Chapter 4

Automation and Error Handling

Automation is important because the object models of Office applications use automation, and scripting clients like VBScript must use automation. This chapter starts by explaining the various terminology used and how this fits in with type libraries, IDispatch, dual and dispinterfaces. It then describes the variable types that you can use and gives examples of how to access automation objects from various popular programming languages.

The final part of the chapter illustrates how you create an automation object in ATL, the various templates supplied and some of the pitfalls with automation. This example is also used to explain how to implement rich error handling in COM using error objects.

Chapter 5

Marshaling and Threading

COM objects can be implemented in DLLs or EXEs and physically these servers can be on the same machine, or on a different machine to the client. In all cases the client treats the object the same: it treats it as if the object is running in the same process (strictly apartment) as the client code. To do this COM uses in-process objects called proxies and this chapter explains when these are used (cross apartment calls) and how you create the code to implement them.

It starts by explaining what marshaling is and then describes the three main forms of marshaling used: standard, type library and custom marshaling. This is then brought into the context of remote servers and the discussion leads to COM surrogates and how to access a remote object including the necessary registration entries and COSERVERINFO.

The example in this chapter is a simple object that allows you to get information about the machine's disk. However, to illustrate the concepts of inproc, local, remote and surrogate-wrapped objects, the example object is implemented in each of these ways and a client is develped that allows you to access the various object types. During the development of this example you see how to create and register proxies and how to use DCOMCnfg.

The second half of the chapter covers COM threading models and how to use them in ATL.

Chapter 6

Connectable Objects

Connection points were added to allow in-process OLE controls have bi-directional communications with their containers. They are useful for non control objects and for non inproc objects too. This chapter explains how connections points work and how to use them in AT.

The first part of the chapter explains the terminology: what incoming and outgoing interfaces are, what a source interface is and how this fits in with sink objects and interfaces.

The second half of the chapter is an example that uses connection points. This example is in three parts. The first part is a COM object that waits on an a Win32 event object and when the event is set it will inform any connected clients. The Win32 event object is set or reset using the second part of the example: a MFC project. The final part of the example is a control that gives visual feed back when the object informs it that the Win32 event object has changed state.

The example gives various tests to show you how connection points work. However, it omits to show you how to make connection points (or any callback mechanism to a inproc client) work over DCOM.

Chapter 7

Properties, Persistence and Collections

COM objects can have properties. Properties represent the state of the object and thus you may decide that you want to initialise a new object with some state, or save the state of an existing object and to do this you need some persistence mechanism.

The chapter starts by explaining what properties are and introducing the various terminologies: custom properties, stock properties and ambient properties. It gives code that shows you how to implement these properties on your controls and how to change these properties through scripting.

The chapter then explains persistence, what it is, why you need it and how ATL helps you. In short, ATL gives you various templates that implements persistence, and allows you to indicate the persisted properties through the property map. However, just adding a property to the map is not all you need to do. Since properties represent the internal state of an object you also need to take into account how the changing of a property affects the object, in particular if a control's properties change this could also change the visual representation of a control and hence you need to know how to get a control to update its view and how to update the metafile that a container may have cached for the control. The final part of this section covers initialising controls that are embedded on a web page.

The last part of this chapter covers automation collections. Collections are used by the Office applications to hold together several objects of the same type and VBA has a construct, for each, that allows you to iterate through all the objects in a collection. This section shows you how to implement your own collection in ATL and explains the ATL2.1 enumerator templates.

Chapter 8

A Full Control

The final chapter of the book looks at controls in more depth. The first part explains the difference between the various control types in the ATL2.1 Object Wizard and it describes the various ATL templates that are used. It then describes how you write the code to show a control's visual representation and how to change its size (this is illustrated with an example).The chapter explains terminology like natural extent, windowed and windowless controls. It then discusses the various communication interfaces used to talk to the container, including connection points and advise interfaces.

The next section covers property pages. It explains what they are and how to create them in ATL. This is subject gets more coverage in the example. Controls are visual objects and hence have a window, so an ATL control must be able to handle windows messages. To do this ATL uses message maps. These basically implement a window procedure for the control and handle messages from the system and any child windows on the control. ATL also allows you to sub- or super-class windows so your control can reuse the functionality of an existing windows class. This section explains terms like contained windows and chaining message maps.

The example in this chapter superclasses a Win32 Tree view control to allow it to hold internet URLs. When you click on a branch the URL is shown in an accompanying edit control and when you double click on the branch an instance of IE is launched using that URL. This example shows you how to:

  • Superclass a window
  • Communicate between contained windows
  • Prepare the code for use in IE (ie make it safe for initialisation and scripting)
  • Add persistence code so that it can be initialised by IE and VB
  • Add a property page for the Control
  • How to print the control.

Appendix A

HRESULT Facility Codes


(c) 2006 Richard Grimes