Version 23 of tcom server

Updated 2012-09-03 11:57:00 by oehhar

tcom server

Use tcom as an Active-X server, e.g. create com objects with tcl.

Chin Huang creates and maintains tcom. HaO has created this page on 2012-08-31 within a project with a wrapped application and without deep knowledge of COM in general. I personally made a trial and error process and was surprised that, at the end, something worked.

I hope this might be useful to someone. Feel free to change anything !

Table of contents:


Original documentation


There are two connection methods to propose a com object to other applications:

Running object

The server aplication is already running and creates a com object without and client contact. The com object is registered in the running object table (ROT) of windows. This table is not contained in the registry but in memory. Registry entries are only used for helper issues.

TCOM clients contact those objects using getactiveobject :

Server object

The TCL server application is started by the client and may be incorporated as DLL in the same process as the client or might be in another process.

The registry is used to inform the client application about the location of the com server.

TCOM clients contact those objects using createobject .

Here are three variants:

Inproc

The COM object server is loaded as a DLL in the same process as the client application.

Local

The COM object server is loaded in another process. It might be an exe or a DLL.

Remote

The COM object server is loaded on another machine than the client program. It might be an exe or a DLL.

The server seams to be identical. The COM machinery will transport the information.


The server may be a TCL script invoked by the tcl dll library or a wrapped exe file. Here is an overview, which method might be with which file type:

Running objectInproc Server object DLLLocal or Remote Server object
TCL scriptyesyesyes
Wrapped exeyesnoyes

TCL script

The original documentation describes this implementation method.

Chin Huang explained to Jeff Godfrey on clt what really happens in the command ::tcom::server register :

The tcom COM server implementation starts up a Tcl interpreter for
each COM server, so I don't see how it can invoke the code in a
wrapped application.  The Tcl command

     ::tcom::server register Banking.tlb

creates the Windows registry key

     HKEY_CLASSES_ROOT\\CLSID\\$clsid\\tcom

with two values:

"TclDLL" contains the full path to the Tcl interpreter DLL to load.

"Script" contains Tcl code which the Tcl interpreter will execute to
load and register the Tcl implementation of that COM class.  The
script is simply "package require Banking" because the Banking package
encapsulates the COM class implementation.

I personally have no experience with this method, please follow the .

Tools

The following tools are helpful. They are included in many Microsoft development packages like Visual C++ Express. I use MS-Visual C++ 6.0 and Microsoft Platform SDK for Windows Server 2003 SP1.

Required command line development tools:

  • midl.exe: IDL compiler
  • uuidgen: Generates UID strings

Debugging tools

  • regedit.exe: Show registry, contained in windows
  • irotview.exe: show the Running Object Table (ROT)
  • OLE-COM Object viewer: Show COM-View of registry, recompile type libraries to idl

Registration tools

  • regtlib: Register type library, use as administrator

Type library

The first step to a COM server is the creation of a type library.

To create a type library, first an interface definition file must be written. An example is below. Its properties in descending logical order are:

  • File name: com_link_process.idl
  • Library name: Application
  • Object class: Step (coclass clause)
  • Interface name: IStep
  • Method name: Process
  • Input parameter: pIn of type binary string pointer (BSTR *).
  • return value: pRet of type binary string pointer (BSTR *).
import "oaidl.idl";
import "ocidl.idl";

        [
                object,
                uuid(0C7E66F0-B50E-4B03-B784-2C89A9069B65),
                dual,
                helpstring("COM Link Step Interface"),
                pointer_default(unique)
        ]
        interface IStep: IDispatch
        {
                [id(1), helpstring("COM Link Process")]
                HRESULT Process(
                        [in] BSTR *pIn,
                        [out, retval] BSTR *pRet);
        };

[
        uuid(16A8EC94-8E85-4D72-9425-B0C64E3BF6A8),
        version(1.0),
        helpstring("COM Link Process 1.0 Type Library")
]
library Application
{
        importlib("stdole32.tlb");

        [
                uuid(A7CB39F0-4996-4A43-AD5A-1C718D41CB98),
                helpstring("COM Link Step Class")
        ]
        coclass Step
        {
                [default] interface IStep;
        };


};

uuid

An uuid is required for the identification of all items. Those may be generated by:

C:\test>uuidgen
09e8f1b9-5d1a-409e-9a07-bba3dfbbdf5c

I experienced that it may be helpful to put them in uppercase.

generate type library file

To generate a type library file (.tlb) from an interface definition file, one may use midl:

C:\test>midl com_link_process.idl

The generated file com_link_processs.tlb must be copied to the server project files. In this example, it is copied in the same folder as the wrapped server executable. Thus, the file name is:

set Filename [file join [file dirname [info nameofexecutable]] com_link_process.idl]

Register type library

Within this context, registering the type library seams not to be of any use.

It could be done using regtlib <file>. It might be helpful for any programming frameworks.

The registry subtree is HKEY_LOCAL_MACHINE\SOFTWARE\Classes\TypeLib\{<uuid>}.

Load type library

The first step of the com server script is to import the type library:

if {[catch {
    package require tcom
    ::tcom::import $Filename
} errMsg]} {
    tk_messageBox -message "Type library file '$Filename' missing.\n$Err"
    exit
}

This creates the command ::Application::Step.

If the type library file is included in a wrapped application, it must first be copied out of it:

set Filename [file join $::env(Tmp) com_link_process.idl]
file copy -force -- [file join [file dirname [info script]] com_link_process.idl] $Filename 

::tcom::object command

All server objects are created using this command family:

::tcom::object registerfactory factorycmd ?deletecmd?
::tcom::object create ?-registeractive? methodcmd ?deletecmd?

All parameters with cmd are evaluated. They are aranged to well support IncrTCL Objects. In contrast, the examples use plain TCL:

factorycmdis invoked on a client connect. The returned result of each invocation is registered as methodcmd.
methodcmd method ?arg?...is invoked when a method or property is invoked by the client.
deletecmd methodcmdis invoked when the client frees the object with the registered methodcmd as parameter.

Running object

The exposed object of the server is created by:

set objectHandle [::tcom::object create -registeractive ::Application::Step ObjectCallback ObjectDeleteCallback]

The procedure ObjectCallback is invoked, if a client invokes the method Process of the step.

The procedure ObjectDeleteCallback is invoked with the parameter ObjectCallback when the client deletes the object.

The MS-Visual tools contain a program ROT Viewer. The object may now be seen by the ROT-Viewer by its class uuid: "A7CB39F0-4996-4A43-AD5A-1C718D41CB98".

Object handling procedure

Each call to the object invokes the object handling procedure ObjectCallback.

proc ObjectCallback {method args} {
    switch -exact -- $method {
        Process {
            return "[lindex $args 0] ok"
        }
        default {
            return -code error "Unknown method '$method'"
        }
    }
}

Some hints about the procedure:

  • Get and Set calls get the following prefixes to the method: _get_ and _set_.
  • Script errors are sent to the server (which is handy). I personally catch the whole procedure at least to log error in the server.
  • Often, a Quit method is foreseen to quit the application. The corresponding program exit should be delayed to correctly return the com request (after idle {exit 0}).
  • Be shure, that the return value has the right internal representation. See the tcom page for hints.

Object delete procedure

The object delete procedure is called when the client deletes the object. To have a constant registered object, one may reregister an object:

proc ObjectDeleteCallback {args} {
    ::tcom::object create -registeractive ::Application::Step ObjectCallback ObjectDeleteCallback
}

Invoke the object by its class id

Another interpreter may now access the object by its class uuid and invoke the process method:

% package require tcom
% set h [::tcom::ref getactiveobject -clsid A7CB39F0-4996-4A43-AD5A-1C718D41CB98]
::tcom::handle0x02715AA9
% $h Process A
A OK

Register Program ID

To use the program ID Link3.Application instead the class ID, the following registry keys are necessary to set:

package require registry
registry set {HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Link3.Application} "" "EasySoft.Link"
registry set {HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Link3.Application\CLSID} "" "{A7CB39F0-4996-4A43-AD5A-1C718D41CB98}"

Explanations: [L1 ]

The first key must be of the format vendor.component . An included space resulted in the windows api function CLSIDFromProgID to return an error.

This must be done as administrator or may be done by the installation routine.

Invoke the object by its program id

Another interpreter may now access the object by its program id and invoke the Process method:

% package require tcom
% set h [::tcom::ref getactiveobject Link3.Application]
::tcom::handle0x02715AA8
% $h Process A
A OK

(Wrapped) Local Server

The server is now started using registry keys. The upper example is continued and the local server capacity is added to the same script.

Registry registration

They should be installed by a command line switch /regserver and uninstalled by /unregserver. It is a convenient way to start the exe in the installation routine to do the registration.

My code:

if { "/regserver" in $::argv || "/unregserver" in $::argv } {
    if {[catch {
        package require registry
        set Key {HKEY_LOCAL_MACHINE\SOFTWARE\Classes}
        if {"/regserver" in $::argv} {
            # map Link3.Application to class uuid
            registry set $Key\\Link3.Application "" Link3
            registry set ${Key}\\Link3.Application\\CLSID ""\
                    \{A7CB39F0-4996-4A43-AD5A-1C718D41CB98\}
                                
            # execute exe if class required
            append Key \\CLSID\\\{A7CB39F0-4996-4A43-AD5A-1C718D41CB98\}
                                
            registry set $Key "" Link3
                        
            registry set $Key\\LocalServer32 ""\
                    [file nativename [file normalize [info nameofexecutable]]]
            registry set $Key\\ProgID "" Link3.Application
        } else {
            registry delete $Key\\Link3.Application
            registry delete $Key\\CLSID\\\{A7CB39F0-4996-4A43-AD5A-1C718D41CB98\}
        }
    } Err]} {
        tk_messageBox -message "Error registering com server.\nPropably not administrator"
        exit 1
    }
    exit 0
}

Key explanation: [L2 ]

Register COM client connection callback

The following command registers a callback when a client connects the object:

set objectHandle [::tcom::object registerfactory ::Application::Step ObjectFactoryCallback ObjectDeleteCallback2]

The called procedure must return the method callback command:

proc ObjectFactoryCallback {} {
    return ObjectCallback
}

The Object delete callback is different to the registered object, as it is not automatically recreated. Here we do nothing, but any cleanup code may be placed here.

proc ObjectDeleteCallback2 {} {
}

We are ready to call the com server from another instance:

% set h [::tcom::ref createobject Link3.Application]
::tcom::handle0x02930090
% $h Process a

The server will be started with the command line switch -Embedding and should eventually not show any gui.

VBA Client

Now, Visual Basic for Applications (VBA) is used as client (not tcom). Here are some interesting observations:

  • It seams, that all parameters are in general of type variant. The parameter type in the type library is ignored.
  • To check parameter type in VBA, the function VarName() always returns Variant. Use VarType() and find the return value in the internet...
  • If the TCL object callback function returns with a value which have the internal representation of a list, VarType() is 8024. The value may be acced within VBA using varname(0), varname(1)...
  • Be shure, that the function parameters have the right type. I observed values like ::tcom::handle0x045BAA00 for a BSTR parameter when passing a variable of type String. A dummy operation helped: "" + varname. For me, this looks like a bug.

A vba script to use the upper com object:

set oLink3 = CreateObject("Link3.Application")
oLink3.Process("a")

Open Issues

The following issues are open to me:

  • How may callbacks/events be used ?

My Wish list

  • 64 Bit Version
  • No dependency on the internal representation of TCL variables