The macros for declaring and implementing COM interfaces


There are two ways of declaring COM interfaces, the hard way and the easy way.

The easy way is to use an IDL file and let the MIDL compiler generate your COM interface for you. If you let MIDL do the work, then you also get __uuidof support at no extra charge, which is a very nice bonus.

The hard way is to do it all by hand. If you choose this route, your interface will look something like this:

#undef  INTERFACE
#define INTERFACE   ISample2

DECLARE_INTERFACE_(ISample2, ISample)
{
    BEGIN_INTERFACE

    // *** IUnknown methods ***
    STDMETHOD(QueryInterface)(THIS_ REFIID riid, void **ppv) PURE;
    STDMETHOD_(ULONG,AddRef)(THIS) PURE;
    STDMETHOD_(ULONG,Release)(THIS) PURE;

    // ** ISample methods ***
    STDMETHOD(Method1)(THIS) PURE;
    STDMETHOD_(int, Method2)(THIS) PURE;

    // *** ISample2 methods ***
    STDMETHOD(Method3)(THIS_ int iParameter) PURE;
    STDMETHOD_(int, Method4)(THIS_ int iParameter) PURE;

    END_INTERFACE
};

What are the rules?

  • You must set the INTERFACE macro to the name of the interface being declared. Note that you need to #undef any previous value before you #define the new one.

  • You must use the DECLARE_INTERFACE and DECLARE_INTERFACE_ macros to generate the preliminary bookkeeping for an interface. Use DECLARE_INTERFACE for interfaces that have no base class and DECLARE_INTERFACE_ for interfaces that derive from some other interface. In our example, we derive the ISample2 interface from ISample. Note: In practice, you will never find the plain DECLARE_INTERFACE macro because all interfaces derive from IUnknown if nothing else.

  • You must list all the methods of the base interfaces in exactly the same order that they are listed by that base interface; the methods that you are adding in the new interface must go last.

  • You must use the STDMETHOD or STDMETHOD_ macros to declare the methods. Use STDMETHOD if the return value is HRESULT and STDMETHOD_ if the return value is some other type.

  • If your method has no parameters, then the argument list must be (THIS). Otherwise, you must insert THIS_ immediately after the open-parenthesis of the parameter list.

  • After the parameter list and before the semicolon, you must say PURE.

  • Inside the curly braces, you must say BEGIN_INTERFACE and END_INTERFACE.

There is a reason for each of these rules. They have to do with being able to use the same header for both C and C++ declarations and with interoperability with different compilers and platforms.

  • You must set the INTERFACE macro because its value is used by the THIS and THIS_ macros later.

  • You must use one of the DECLARE_INTERFACE* macros to ensure that the correct prologue is emitted for both C and C++. For C, a vtable structure is declared, whereas for C++ the compiler handles the vtable automatically; on the other hand, since C++ has inheritance, the macros need to specify the base class so that upcasting will work.

  • You must list the base class methods in exactly the same order as in the original declarations so that the C vtable structure for your derived class matches the structure for the base class for the extent that they overlap. This is required to preserve the COM rule that a derived interface can be used as a base interface.

  • You must use the STDMETHOD and STDMETHOD_ macros to ensure that the correct calling conventions are declared for the function prototypes. For C, the macro creates a function pointer in the vtable; for C++, the macro creates a virtual function.

  • The THIS and THIS_ macros are used so that the C declaration explicitly declares the "this" parameter which in C++ is implied. Different versions are needed depending on the number of parameters so that a spurious trailing comma is not generated in the zero-parameter case.

  • The word PURE ensures that the C++ virtual function is pure, because one of the defining characteristics of COM interfaces is that all methods are pure virtual.

  • The BEGIN_INTERFACE and END_INTERFACE macros emit compiler-specific goo which the compiler vendor provides in order to ensure that the generated interface matches the COM vtable layout rules. Different compilers have historically required different goo, though the need for goo is gradually disappearing over time.

And you wonder why I called it "the hard way".

Similar rules apply when you are implementing an interface. Use the STDMETHODIMP and STDMETHODIMP_ macros to declare your implementations so that they get the proper calling convention attached to them. We'll see examples of this next time.

Comments (16)
  1. bg says:

    a even easier way is to use #import

  2. …or you could use attributed C++, which will generate the TLB and the header file (suitable for C and C++).

  3. Mike Dunn says:

    Note that the ATL wizard in VC 6 has a bug, it generates header files with STDMETHOD when it should be STDMETHODIMP. This isn’t a problem in practice because the difference is that STDMETHOD includes "virtual", which is harmless to repeat in the impl class.

    Attributed C++ is about the worst thing I’ve ever encountered in my life. I have never gotten an attrib C++ ATL project to work in VC 7.1. Well, the wizard-generated code compiles, but as soon as I try to add my own stuff to the class, things break; and since the logic is hidden in attributes, there’s no way to debug it. (Things like: the class’s RGS file isn’t processed at registration time.)

  4. Centaur says:

    However, this assumes that one wants a header that compiles both in C++ and C. Of course that’s a sensible thing to want. However, none of that macroing will give a declaration valid for other languages such as Object Pascal. Meanwhile, going the IDL way will likely yield a type library which is easily imported by other systems.

    Borland Delphi and C++ Builder have a somewhat perverse way of defining interfaces; namely, you first make a type library by the use of a visual (and a pretty brittle at that) editor, and then the IDE generates or updates you the headers and the implementation. Also, you have the option of exporting the IDL for the type library.

    Also, while generating the headers and the implementation, BCB insists on turning all interface pointer parameters into smart pointers that, among other things, automatically AddRef and Release. An unsuspecting victim is then forced to mentally step through different modes of a method call ([in], [out] and [in, out]) to understand why the object is suddenly gone after handing it to a method.

  5. Mike Dunn: I think that the problem with Attributed C++ isn’t that it doesn’t work, but rather that the documentation is nearly nonexistant.

  6. Michael says:

    > I think that the problem with Attributed C++

    > isn’t that it doesn’t work,

    Actually, I’ve heard a lot of information that some parts of the generated code has memory leaks in some dispatch/invoke type stuff, and various other problems which of course are pretty hard to fix when they are automatically generated.

    These are mentioned frequently on the microsoft.public.vc.atl newsgroup, such as this post for example:

    http://groups.google.com/groups?q=attributed+bug+%22Alexander+Nickolov%22&hl=en&lr=&ie=UTF-8&group=microsoft.public.vc.atl&safe=off&selm=%23RNWlozzDHA.556%40TK2MSFTNGP11.phx.gbl&rnum=3

    It seems like attributes were sort of a short-lived and unsuccessful experiment by the Visual Studio team. They haven’t even stood by them enough to fix these problems that are mentioned on the newsgroup.

    Of course, to "help you out", attributed is turned on by default when you create a new ATL project…

  7. Chris Conti says:

    Centaur: I’ve always wished that MIDL had on option to not generate the C compatible code (i.e. generate C++ only) OK-this is a minor point, and what does it hurt to generate both …

    Isn’t it humorous that the visual studio team picked the same ‘perverse’ backwards method for generating wsdl code?

    I’ve also been disappointed that microsoft has never provided an idl->.NET tool (relying instead on the lossy #import style tlbimp)

  8. Rob Kennedy says:

    Raymond, could you please make sure that a copy of today’s post is sent to the people in charge of the Platform SDK’s TextServ.h? That file is a perfect example of why people declaring interfaces in C or C++ should use the COM macros. The ITextServices and ITextHost interfaces in that unit are declared using "unmacroed" C++, and that makes them totally incompatible with anything else, especially languages that don’t understand Microsoft’s default thiscall calling convention.

  9. Raymond Chen says:

    I agree that textserv.h is broken but it’s too late now. If you changed it to use the COM macros then you’d be changing the calling convention and existing clients would start crashing.

  10. Raymond Chen says:

    But how many compilers support #import and attributed C++? Remember, the point of these macros is to admit a *compiler-independent* way of expressing COM interfaces. It’s great that there are shortcuts you can use that work only on certain compilers, but that’s not the issue here.

  11. This comment is not about the macros…

    Your posts are cool!

    Raymond, do you plan compile these technical information (posts from COM, Win32, Win64) in a book? A lot of real Microsoft developers will be grateful!

  12. Anon says:

    Raymond> But how many compilers support #import and attributed C++?

    …or __uuidof?

  13. Raymond Chen says:

    It’s one thing to make a compiler-specific feature available. It’s another to require it.

    If your compiler doesn’t support __uuidof then including the header file gets you the interfaces but you don’t get any __uuidof magic – but at least the interfaces work and you can use them. Whereas if your compiler doesn’t support #import and the header file uses it, then you’re stuck.

  14. Norman Diamond says:

    Why are IDL and ODL almost but not quite compatible? What are the criteria for choosing one or the other? What is the method for switching from one to the other if the programmer’s actions in VC++ happened to generate the less appropriate choice?

  15. Raymond Chen says:

    Beats me, I’ve never heard of ODL.

Comments are closed.