Home : COM / OLE / ActiveX notes : Creating a COM object with ATL

Creating a COM object with ATL

1. Create the COM server

You first need a COM "server" – normally a DLL file – which can instantiate (create) your COM object(s). In Visual C++ version 6:

Select the menu option File | New….
Select the tab Projects.
Select the option ATL COM AppWizard.

The AppWizard consists of a single step.

The Server Type will normally be a Dynamic Link Library (DLL).
If your COM object(s) will need be accessed across process or apartment boundaries, i.e. if it will require marshalled access, then check the Allow merging of proxy/stub code box. This allows the marshalling code to be incorporated into the same DLL file.
If you want to use MFC within your COM object(s), also check the Support MFC box.

2. Create COM classes within the server

You now need to add one (or more) COM classes to your server. These classes define the COM objects provided by the server. In the COM server project:

Select the menu option Insert | New ATL Object….

Simple COM object

The object Objects | Simple Object provides a minimal COM class.

ActiveX control

The object Controls | Full Control provides an ActiveX control, with lots of interfaces provided and implemented for you automatically.

"Names" properties

Short Name: The name of the C++ class that is the COM class. Other names on the property page are filled in automatically, but can be manually changed.

Interface: the name of the first COM interface supported by your COM object.

Type: a human readable name for the COM object.

Prog ID: the ProgID for the COM object. Client code can use the ProgID to specify your COM object, as an alternative to the CLSID.

"Attributes" properties

Threading Model, select one of:

Apartment, the COM object will be loaded into a STA (Single Threaded Apartment).
Both, the COM object will be loaded into the apartment (either single or multi-threaded) from which the client code called CoCreateInstance. Not available for ActiveX controls.
Free, the COM object will be loaded into the MTA (Multi-Threaded Apartment). Not available for ActiveX controls.

Interface: select Custom if Automation support isn’t required.

Aggregation: select No if the COM object will never be aggregated by another object.

"Miscellaneous" properties

Only available for ActiveX controls.

Windowed Only: If checked, the ActiveX control always creates its own window for its graphical display. If unchecked, the ActiveX control supports "windowless" activation, where it draws directly into its parent’s window (which must supply a Device Context to the control whenever it needs to be redrawn).

3. Add a new interface to the COM class

Generate an IID (i.e. a new GUID) for the interface, for example by using the GUIDGEN.EXE application supplied with Visual Studio.

Open the project’s IDL file. Add a new section defining the new interface (you don’t need to define the methods yet), entering the new IID in the uuid section:

[
object, uuid(12345678-1234-1234-1234-123456789ABC), helpstring("INewInterface Interface"), pointer_default(unique)
] interface INewInterface : IUnknown { };

Also, add the new interface to the type library for the COM class:

library NAME_OF_DLLLib {
…
coclass MyComObject {
…
interface INewInterface;
};
};

Re-build the project. Then, in "ClassView", right click on your COM class, and select "Implement Interface…" from the context menu. In the dialogue box that appears, check the interface you want to add, then click on OK.

4. Add a method to a COM interface

In "ClassView", right click on the interface, and select "Add Method…" from the context menu. In the dialogue box that appears, enter the method’s name, list its parameters (using IDL syntax, so you can use [in] and [out] attributes), then click on OK.

5. Add a pre-defined interface to the COM class

In "ClassView", right click on your COM class, and select "Implement Interface…" from the context menu. In the dialogue box that appears, click on "Add Typelib…", click on "Browse…", and find the type library for the project where the interface was defined. Check the interface(s) you want to add, then click on OK.