COM servers with comtypes

Define the COM interface

Start writing an IDL file. It is a good idea to define dual interfaces, and only use automation compatible data types.

import "oaidl.idl";
import "ocidl.idl";

[
        uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx),
        dual,
        oleautomation
]
interface IMyInterface : IDispatch {
        HRESULT MyMethod([in] INT a, [in] INT b, [out, retval] INT *presult);
}

[
      uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
]
library MyTypeLib
{
        importlib("stdole2.tlb");

        [uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]
              coclass MyObject {
              [default] interface IMyInterface;
        };
};

Please note that you must replace the 'xxxx' placeholders in the section above with separate GUIDs that you must generate yourself. You can use Python to generate unique GUIDs by running this in a windows console:

C:\> python -c "from comtypes import GUID; print GUID.create_new()"
{26F87CEB-603A-4FFE-8865-DB67A9E3A308}
C:\>

The IDL file should now be compiled with the Microsoft MIDL compiler to a TLB type library file.

Implement the class

Generate and import the wrapper module (which is named after the library statement in the IDL file), and create a subclass of the MyObject coclass.

Most required class attributes are already defined in the typelib wrapper file. You must at least add attributes for registration that are not in the type library.

import comtypes
import comtypes.server.localserver

from comtypes.client import GetModule
# generate wrapper code for the type library, this needs
# to be done only once (but also each time the IDL file changes)
GetModule("mytypelib.tlb")

from comtypes.gen.MyTypeLib import MyObject

class MyObjectImpl(MyObject):
    # registry entries
    _reg_threading_ = "Both"
    _reg_progid_ = "MyTypeLib.MyObject.1"
    _reg_novers_progid_ = "MyTypeLib.MyObject"
    _reg_desc_ = "Simple COM server for testing"
    _reg_clsctx_ = comtypes.CLSCTX_INPROC_SERVER | comtypes.CLSCTX_LOCAL_SERVER
    _regcls_ = comtypes.server.localserver.REGCLS_MULTIPLEUSE

The meaning of the attributes:

_reg_threading_ must be set to "Both", "Free", or "Apartment". It specifies the apartment model in which the server runs.

_reg_progid_ and _reg_novers_progid are optional short names that can later be used to specify your object, instead of the CLSID in type library. Typically the type library name plus the coclass name plus a version number are combined to form the progid, and the type library name plus the coclass name are combined to form the version independend progid.

_reg_desc_ is the (optional) name of the coclass.

The _reg_clsctx_ constant specifies in which contexts the com server can operate.

The optional _regcls_ constant is only used for com objects that run in their own process, see the MSDN docs for more info. In comtypes, several REGCLS values are defined in the comtyper.server.localserver module.

You do not yet implement any methods on the class, because basic functionality is already present.

Register and run the object for the first time

A COM object must by registered with Windows, and will also be started at runtime by Windows. This magic, on the comtypes side, is done by the comtypes.server.register.UseCommandLine function. You should call it in the if __name__ == "__main__" block of your script, with the MyObjectImpl class:

if __name__ == "__main__":
    from comtypes.server.register import UseCommandLine
    UseCommandLine(MyObjectImpl)

You should now run your script with a /regserver command line option, this will write information about your object into the Windows registry:

C:\> python myserver.py /regserver

If you have the Microsoft OLEVIEW utility, you can now open the "All Objects" item, and look for the "Simple COM server for testing" object. If everything works well, you can even create an instance of your COM object by double clicking the entry, and you will see that the object implements quite some interfaces already.

You can also create an instance of the object with comtypes:

>>> from comtypes.client import CreateObject
>>> x = CreateObject("MyTypelib.MyObject")
>>> print x
<POINTER(IMyInterface) ptr=0x1216328 at 1216620>
>>>

Of course calling a method does not yet work since it is not implemented in the server script:

>>> x.MyMethod(a, 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
_ctypes.COMError: COMError(0x80004001, 'Nicht implementiert', (None, None, None, 0, None))
>>>

Implementing COM methods

NOTE: The documentation in this section is also valid for writing COM event handlers!

In the IDL file, the method signature is defined like this:

HRESULT MyMethod([in] INT a, [in] INT b, [out, retval] INT *presult);

So, this method takes two integers and returns a third one, writing the latter into a pointer.

You must add e Python method to the class MyObject that implements this behaviour.

...
class MyObjectImpl(MyObject):
...
    # Note the 'this' second parameter
    def MyMethod(self, this, a, b, presult):
        presult[0] = a + b
        return 0

class MyObjectImpl(MyObject):
...
    # Note: NO second 'this' parameter
    def MyMethod(self, a, b):
        return a + b

Run the object again and test the method

We can now create the object and test the implemented method:

>>> from comtypes.client import CreateObject
>>> x = CreateObject("MyTypelib.MyObject")
>>> print x
<POINTER(IMyInterface) ptr=0x1216328 at 1216620>
>>> print x.MyMethod(42, 5)
47
>>>