comtypes.client

Functions that create COM objects

CreateObject(progid, clsctx=None, machine=None, interface=None)

Create a COM object and return an interface pointer to it. progid specifies which object to create. It can be a string like "InternetExplorer.Application", a comtypes.GUID instance, a GUID string in the form "{2F7860A2-1473-4D75-827D-6C4E27600CAC}", or any object with a _clsid_ attribute that must be a comtypes.GUID instance or a GUID string.

clsctx specifies how to create the object, any combination of the comtypes.CLSCTX_... constants can be used. If nothing is passed, comtypes.CLSCTX_SERVER is used.

machine allows to specify that the object should be created on a different machine, it must be a string specifying the computer name. DCOM must be enabled for this to work.

interface specifies the interface class that should be returned, if not specified comtypes will try to determine a useful interface itself and return a pointer to that.

CoGetObject(displayname, interface=None)

Return an interface pointer to an named COM object. For the interpretation of displayname consult the Microsoft documentation for the Windows CoGetObject function. "winmgmts:", for example, is the displayname for WMI monikers:

wmi = CoGetObject("winmgmts:")

interface specifies the interface class that should be returned, if not specified comtypes will try to determine a useful interface itself and return a pointer to that.

GetActiveObject(progid, interface=None)

Returns a pointer to a running object. progid specifies the active object from the OLE registration database; interface specifies the interface class that should be used.

The GetActiveObject function succeeds when the COM object is already running, and has registered itself in the COM running object table. Not all COM objects do this. Here is an example that starts two separate Excel instances, and then calls GetActiveObject to connect to one of them:

c:\>python
Python 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from comtypes.client import CreateObject, GetActiveObject
>>> GetActiveObject("Excel.Application")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "comtypes\client\__init__.py", line 165, in GetActiveObject
    obj = comtypes.GetActiveObject(clsid, interface=interface)
  File "comtypes\__init__.py", line 846, in GetActiveObject
    oledll.oleaut32.GetActiveObject(byref(clsid), None, byref(p))
  File "\loewis\25\python\Modules\_ctypes\callproc.c", line 754, in GetResult
WindowsError: [Error 22] Vorgang nicht verf³gbar
>>> e1 = CreateObject("Excel.Application")
>>> e2 = CreateObject("Excel.Application")
>>> e1 == e2
False
>>> e3 = GetActiveObject("Excel.Application")
>>> e3 == e2
False
>>> e3 == e1
True
>>> ^Z
c:\>

All the three functions mentioned above will create the typelib wrapper automatically if the object provides type information. If the type library is not exposed by the object itself, the wrapper can be created by calling the GetModule function.

Early binding

comtypes supports early binding even to custom COM interfaces.

GetModule(tlib)

This function generates a Python wrapper for a COM typelibrary.

tlib can be a ITypeLib COM pointer from a loaded typelibrary, a pathname of a file containing a type library (.tlb, .exe or .dll), a tuple or list containing the GUID of a typelibrary, a major and a minor version number, plus optionally a LCID, or any object that has a _reg_libid_ and _reg_version_ attributes specifying a type library.

GetModule(tlib) generates a Python module (if not already present) from the typelibrary, containing interface classes, coclasses, constants, and structures and returns the module object itself. The modules are generated inside the comtypes.gen package. The module name is derived from the typelibrary guid, version number and lcid. The module name is a valid Python module name, so it can be imported with an import statement. A second wrapper module is also created in the comtypes.gen package with a shorter name that is derived from the type library name itself, this does import everything from the real wrapper module but can be imported easier because the module name is easier to type.

For example, the typelibrary for Internet Explorer has the name SHDocVw (this is the name specified in the type library IDL file, it is not the filename), the guid is {EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B}, and the version number 1.1. The name of the real typelib wrapper module is comtypes.gen._EAB22AC0_30C1_11CF_A7EB_0000C05BAE0B_0_1_1 and the name of the second wrapper is comtypes.gen.SHDocVw.

When you want to freeze your script with py2exe you can ensure that py2exe includes these typelib wrappers by writing:

import comtypes.gen.SHDocVw

somewhere.

gen_dir

This variable determines the directory where the typelib wrappers are written to. If it is None, modules are only generated in memory.

comtypes.client.gen_dir is calculated when the comtypes.client module is first imported. It is set to the directory of the comtypes.gen package when this is a valid file system path; otherwise it is set to None.

In a script frozen with py2exe the directory of comtypes.gen is somewhere in a zip-archive, gen_dir is None, and even if tyelib wrappers are created at runtime no attempt is made to write them to the file system. Instead, the modules are generated only in memory.

comtypes.client.gen_dir can also be set to None to prevent writing typelib wrappers to the file system. The downside is that for large type libraries the code generation can take some time.

Connecting to COM events

GetEvents(source, sink, interface=None)

This functions connects an event sink to the COM object source.

Events will call methods on the sink object; the methods must be named interfacename_methodname or methodname. The methods will be called with a this parameter, plus any parameters that the event has.

interface is the outgoing interface of the source object; it must be supplied when comtypes cannot determine the outgoing interface of source.

GetEvents returns the advise connection; you should keep the connection alive as long as you want to receive events. To break the advise connection simply delete it.

ShowEvents(source, interface=None)

This function connects a special event sink to the source object for debugging. The event sink will first print out all event names that are found in the outgoing interface, and will later print out the events with arguments as they occur.

Details about code generation

The GetModule(tlib) function generates Python modules from a COM typelibrary. The Python modules are generated

XXX describe logging, gen_dir, wrap, _manage (?)

XXX describe what com interface pointer is and what you can do with it.