Commands for COM servers
|comserver_factory CLSID MEMBER_MAP CREATE_COMMAND ?FACTORYNAME?|
|install_coclass PROGID CLSID VERSION PATH ?options?|
|install_coclass_script PROGID CLSID VERSION SCRIPTPATH ?options?|
|uninstall_coclass PROGID ?-scope SCOPE? ?-keepappid?|
This module provides commands for implementing COM clients and servers in Tcl. For writing COM clients, see the COM client module. TWAPI's COM server support enables writing COM components in Tcl that can be accessed by any COM client that can access COM automation components through the IDispatch interface.
This documentation is reference material that assumes familiarity with COM programming concepts such as COM interfaces, automation, PROGID and CLSID identifier types and so on. For more introductory material and a guide with examples, see the COM chapter in the Tcl on Windows online book.
COM components may be implemented as DLL's which run inside the client process, termed in-process, or as separate processes, termed as localserver or out-of-process. TWAPI only supports the implementation of the latter type of component.
Information about COM components is stored in the Windows registry including the DLL or executable in which it is implemented. When a client attempts to create a COM object that is implemented as an out-of-process component, the Windows Service Control Manager (SCM) looks up executable command line for the passed CLSID in the registry and starts up a new process if there is not one already running that can service the request. The new process registers class factories with the SCM for each type of component implemented by the process (a single executable may house more than one component classes). The appropriate class factory is then invoked to create an object which is then returned to the client.
Implementing a COM component thus involves:
Note that implementing a component using TWAPI does not require you to write an IDL file or generate a COM type library.
The core functionality can be implemented by any Tcl command, with optional prefix arguments, that takes some action or returns a result based on a method or property name and their parameters that are passed as additional arguments. Thus it may be implemented by a TclOO object, a namespace ensemble or even a simple proc with a switch statement.
Installing a COM class involves creating the appropriate entries in the Windows registry as documented in the Windows SDK. Although these entries may be created by any means such as through a
file, TWAPI provides the install_coclass and install_coclass_script commands for the purpose. Once installed, the executable will be started by the SCM whenever a client creates an object of the class.
When a COM class is no longer required, it can be uninstalled by calling uninstall_coclass.
When the executable containing a component begins execution, it must register factories for the classes it implements. These are invoked by the SCM to create objects belonging to a class.
The comserver_factory creates a new factory for a component class. This returns a Tcl command object. Registering the class factory with SCM is done by invoking the register method on this class.
When a factory is registered, it is in suspended mode where it does not respond to requests for object creation. The command start_factories activates all factories in the process. They are then invoked whenever a client instantiates a new object. Method calls are passed on to the class implementation and return values are passed back to the client.
For this to work, the application must be running the Tcl event loop as COM uses Windows messages to dispatch client calls to the implementing server.
When the process is no longer used by the SCM and there are no running COM objects resident in it, it is notified as described in the documentation for start_factories. It must then clean up by calling the destroy method on the class factory command objects returned by the comserver_factory method. The process may continue running beyond this point but the factories must be destroyed regardless.
The interaction between a COM client and server is covered by a security blanket that governs authentication, impersonation, authorization and other security parameters. This security blanket is negotiated at the time the connection is established between the client and the server. The security parameters associated with the connection from a particular client can be retrieved with the com_query_client_blanket call.
|-authenticationlevel||The authentication level on the connections, such as packetintegrity, privacy etc.|
|-authenticationservice||The name of the authentication service, such as negotiate, ntlm etc.|
|-authorizationservice||The name of the authorization service, such as dce.|
|-clientprincipal||The client principal name.|
|-cloaking||One of the value none, static or dynamic indicating the type of client identity cloaking that is in effect.|
|-serverprincipal||The server principal name.|
|-appid APPID||Specifies the GUID to use as the AppID for the component. Defaults to CLSID.|
|-appname APPNAME||Specifies a human readable application name to associate with the AppID.|
|-inproc||Specifies that the coclass is to be installed as an in-process component. PATH is the path to a DLL implementing the component.|
|-name NAME||Specifies a human readable coclass name to associate with the class.|
|-outproc||Specifies that the coclass is to be installed as an out-of-process component. PATH is the path to an executable implementing the component.|
|-params PARAMS||Specifies PARAMS as additional command line parameters to be passed to the component. Only valid for out-of-process and service components and ignored otherwise.|
|-scope SCOPE||If SCOPE is user (default), the component is installed only for the current user. If SCOPE is system it is installed for the entire system.|
|-service||Specifies that the coclass is to be installed as an service. PATH is the name of the Windows service that implements the component. When a client attempts to access the component, the SCM will start the service PATH. Note that the service itself must have been installed previously.|
Copyright © 2014-2016 Ashok P. Nadkarni