=============== comtypes.client =============== .. contents:: The ``comtypes.client`` package implements the high-level ``comtypes`` functionality. 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. .. _`WMI monikers`: http://www.microsoft.com/technet/scriptcenter/guide/sas_wmi_jgfx.mspx?mfr=true ``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 "", line 1, in 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. Examples ........ Some examples:: >>> from comtypes.client import GetModule >>> GetModule("shdocvw.dll") >>> 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.