The Component Object Model

A COM interface is a collection of related methods (operations) and properties (data), collectively referred to as members, that define a set of services or functions. The interface definition does not say anything about how these are implemented. For example, an interface definition for remote file access may define the operations that can be done on a remote file. There can then be multiple implementations that adhere to that interface definition but use different protocols like FTP, HTTP and so on, underneath.

A coclass implements one or more COM interfaces. We will use the generic term class interchangeably with coclass.

A COM object is an instantiation of a COM class. Continuing our example, a COM object would represent a specific remote file. The data it encapsulates, such as file size, will correspond to the properties of that file and any method invoked on it will operate on that file.

Ofttimes, multiple COM components implement related functions. These components need to share common settings for configuration of remote activation, security etc. To ease an administrator’s task of configuring each component separately, COM offers a mechanism for grouping components together as an “application”.

A COM component is a binary, either a DLL or an executable, that implements one or more classes. Servers host COM components and the applications that use their services are COM clients. COM servers are classified into three categories based on where they reside with respect to clients.

One of the features of COM is that a client need not be aware of the above scenarios. It makes use of the COM server component in the same way regardless.

A moniker is an COM object that whose sole purpose in life is to identify another COM object. The object to be identified may be as simple as a specific file or a specific cell range in a specific sheet in a specific Excel workbook. Objects may themselves be hierarchical or composed from other objects. Monikers must work with all these cases and hence their function is not as simple as it might seem at first glance.

Moniker objects provide their functions through the IMoniker interface. For our purposes, it suffices to know that:

For compiled languages like C and C++, the code required on the client side to access COM objects is generated from the definition of the interface. This definition is written in the Interface Definition Language (IDL). The midl compiler generates the requisite C code (for example) based on the interface definition. With scripting languages, these tools are generally not needed so we will only occasionally refer to them in passing without going into any details.

Historically, the use of IDL compilers to generate source code for interfacing to COM components was not suitable for scripting languages like VBScript and Javascript for several reasons:

To work around these issues, Microsoft created an interface definition, IDispatch, along with rules to be followed by COM components which would allow them to be invoked from scripting languages. Collectively this technology has been known by various terms such COM automation, ActiveX or simply the IDispatch interface.

For the most part, scripting languages, including Tcl’s twapi_com package, can only work with COM components that support the automation interfaces. Fortunately, most COM components that are not internal to an application and are intended to be used by third parties support these interfaces. This includes Microsoft’s Office applications as well as operating system components like WMI.

In the simplest case, we instantiate a COM object by passing the PROGID of its class to the TWAPI comobj command. This returns a Tcl object that wraps the instantiated COM object. This wrapper object exposes all the methods and properties of the underlying COM object and in addition implements some supplementary methods of its own.

This will create a new instance of the Internet Explorer component. You will not see an Internet Explorer window at this point but if you look in the Windows Task Manager, you will see an instance of the iexplore.exe process running if it was not already there.

A COM object’s properties contain the publically accessible data associated with the object. Internet Explorer has a property Visible which contains its visibility status. Let us retrieve it using the -get method on our COMOBJ wrapper.

This explains why the window was not visible. Properties that are not read-only can be modified so we turn on visibility using the -set method.

In practice, the -get and -set can be left out so the following will also work.

The only time that the -get and -set are required is when there is ambiguity as to whether the referenced name, Visible in this example, is a property or a method. COM automation provides for separate namespaces for methods, property retrieval and property setting functions. Thus the object could conceivably also have a method called Visible. The -get and -set disambiguate between property operations and method calls which are indicated using -call.

However, this situation is rare and so in the vast majority of cases there is no need to disambiguate.

Methods are invoked in essentially the same manner that properties are accessed.

Just like in the case of properties, we almost never need to specify -call and automation methods are case-insensitive so

would work just as well.

When working with COM, many a times you will need to access some object that is deeply nested within other objects. The intermediary objects have to be retrieved and discarded just in order to “navigate” to the target object.

For example, the following code fills an range in an Excel spreadsheet.

In the above example, in order to get to the range we have to navigate through a hierarchy of objects, starting with the application, the workbook collection, a workbook within the collection, the worksheets collection, a worksheet within that collection and finally the cell range. After setting the value, all the created objects have to be deleted.

As an alternative, the COMOBJ automation wrapper provides -with supplementary method to simplify this process:

The first argument to -with is a list of methods or properties, some of which may have parameters (like Item and Range). Each method or property in the list is invoked on the object returned by the previous one and should itself return a new object. The argument after the list (Value2 in this example) is the method or property to invoke on the final object created with any additional arguments being passed to it. All objects created are automatically destroyed.

Not only method calls, but properties as well, can take an arbitrary number of parameters. In the case of properties, these are actually indices into an indexed property but are passed in the same manner as method parameters and in this discussion we use the latter term to refer to either.

Passing parameters to methods is for the most part straightforward but there are a few special cases that we discuss here.

When scripting an application via COM, how does one know what properties and methods are implemented by a component, the parameter types, default values and so on?

The obvious answers are to look up the component documentation or do an Internet search. For well documented and widely used components this is generally more than adequate but there are times when documentation is either unavailable or unclear^[2]. In this case, there are two ways you can get hold of the interface definitions for a component including its methods and properties.

The output should be self-explanatory for the most part but a little discussion is in order.

Once you are done with a component, you can call the -destroy method to release resources associated with the object. This destroys the COMOBJ wrapper object and decrements the reference count on the wrapped COM automation object. This does not mean that if there are no other references to the automation object its containing COM server exits. For example with Internet Explorer, the Quit method must be called else the process will continue running even after the COM object is destroyed. This behaviour depends on the specific component or application.

Accessing a method or property on the object will now result in an error.

In the original implementation of COM automation, the interface IDispatch presented by an automation object was fixed at design time (essentially by the defining IDL source). The interface members could not be added or removed or renamed. Later on, in order to support dynamic languages like Javascript, where members could be added and removed at runtime, a new interface IDispatchEx was defined which provided methods to accomodate these dynamic requirements. Automation objects which support this new interface are popularly known as expando objects.

From a Tcl scripting point of view, expando objects work like any other automation objects except for two issues that have to be kept in mind:

You can iterate over all items in a collection with the supplementary -iterate method of the automation object wrapper. This works much like the Tcl foreach command, looping over the collection, assigning each item to the specified variable and invoking the supplied script.

The COM automation object $drive is explicitly destroyed in each iteration because it is no longer needed. Instead we could have held on to it, for example by adding it to a list, if we needed to access it later. Or instead of an explicit -destroy, we could have used the -cleanup option to the -iterate method to automatically destroy the created objects.

We have to remember to cleanup the collection itself.

Before a COM component can be used by a client, it has to be installed or registered on the system. This registration consists primarily of setting values in the Windows registry that informs the SCM of the component’s name, location, type, invocation method and so on. This registration may be done by a specialized installation program but components are often self-registering.

The mechanism for self-registration depends on whether the component is implemented as a DLL, a self-standing executable or a service.

Self-registering DLL’s are usually registered and unregistered using with the regsvr32 Windows program.

Self-registering server executables are registered or unregistered by invoking them with a command line parameter /RegServer or /UnRegServer respectively.

From Tcl, you can use the twapi::install_coclass or twapi::install_coclass_script commands to install a COM component. This is illustrated in our examples later.

When a client attempts to instantiate a COM object, it passes the CLSID of the object’s class to one of several functions in the COM library. These in turn delegate the operation to the SCM. The SCM has to first locate the binary form of the requested component. It does this via entries in the Windows registry.

Information about COM components installed on a system is looked up in the Windows registry under the HKEY_CLASSES_ROOT key. This key is actually a merged view of two keys:

COM registry keys shows some of the relevant keys.

Let us interactively simulate the lookup sequence for our Internet Explorer examples.

First the CLSID corresponding to the IE PROGID is retrieved.

Next, depending on whether the client application has indicated a preference for in-process or out-of-process versions of the component, the SCM retrieves the InprocServer32 and LocalServer32 keys.

Note that Internet Explorer does not have an in-process version. If it did have one and the client preferences did not exclude in-process components, the SCM would load the DLL specified by the resulting path into the calling client process.

Since there is no in-process component of IE, the SCM will use the out-of-process one. If there is already a process running that can service the request, the SCM will pass the request to it. Otherwise, it checks if the CLSID is associated with an AppID which has a LocalService entry specifying a Windows service that implements the component and if so, passes the request to it. If none of these apply, it will start one up using the command line given by the LocalServer32 key or give up and fail.

This resolves the question of how the SCM locates the component but still unanswered is how the SCM knows what function to call to actually create the requested object. The answer is that it doesn’t and that brings us to the next section.

Since the SCM does not know the specifics of how a particular type of COM object is created, it has to somehow ask the component itself to do this task. For each class that it implements, the component must also implement a class factory, a special type of COM object that “knows” how to create objects of a specific class. So to create an object of the type that the client has requested, the SCM simply has to ask the object’s class factory to create one.

We have of course only postponed the problem. Instead of figuring out how to instantiate the client-requested COM object, the SCM now has to figure out how to instantiate the class factory object. It does this by asking the component itself to register with the SCM, the class factories for all classes supported by the component.

The mechanism for doing this depends on whether the component is an in-process component or an out-of-process component.

We now look what is required for the client process to access a method or property of the COM object once it is created.

In the case of a COM object that is not an automation object, methods and properties defined for an interface are mapped to functions accessed through a table. This happens as part of the process of compiling the IDL file that contains its definition. In the case that C++ is the implementation language, this table of functions is the virtual table of the implementing C++ class. When an object is created by a factory, the returned pointer for the object points to a structure whose first field is a pointer to this table. The client code then calls methods by indexing into this table.

Things are a little different in the case of a COM object that is an automation component. Unlike the previous case, where the table and contained functions were both different for different classes and interfaces, all automation objects implement and present the same interface (the famous IDispatch interface). All method calls are made through the same entry, Invoke, in the corresponding function table. How does the component know which real method the client wants invoked ? The answer is that the client passes in an integer value, called the DISPID, representing the name of the method and the component’s Invoke implementation “dispatches” (hence the name IDispatch) the call based on this value. And how does the client know what DISPID to pass in for a particular method? It can either ask the component directly using another call, GetIdsOfNames, in the IDispatch interface or it can get it from the component’s type library if it has one.

When working with COM automation from Tcl, this is for the most part all hidden. However, there are a couple of rules to be kept in mind regarding the mapping between DISPID values and method names. We will discuss these when we (eventually) get around to actually writing a automation server.

The final aspect we have to look at is shutting down the component when there are no active clients for the objects (including factories) running in the component. Every object maintains an internal count that tracks how many references to it are outstanding. This count is co-operatively maintained between the client and object implementation (again hidden at the scripting level). When the internally maintained counts indicate that no objects or factories are in use, a component can free up its resources.

In the case of an in-process component, the containing DLL can then be unloaded. In the case of an out-of-process component, the containing process can then exit or optionally continue running. For example, the Microsoft Excel automation object will continue running until there is either an explicit Quit method call or the the user exits the application.

We are now ready to implement a component in Tcl and since at this point you are practically an expert in COM technology, this should be a breeze! And it is.

Our component is a script which will be run “on-demand” by the SCM. It implements a single COM class that will represent a bank account.

We will need the TWAPI package.

We define the CLSID and PROGID of the COM class. We also define the map between the integer DISPID values and methods names as described earlier. Once a component is published, the CLSID must be always refer to this exact interface.

We also define the AppID and the application name for the component. We will have no use for it right now, but will need it when we discuss COM remoting and security.

The implementation using TclOO is shown below and is more or less the same as that described in the Object Oriented Programming chapter. Note that this is purely an implementation choice. As mentioned earlier, we could have implemented the COM class in any manner we like, using a different OO framework, as a namespace ensemble or whatever.

One notable difference in this class definition compared to the one in the Object Oriented Programming chapter is that the object is explicitly initialized through the initialize method. There is no implicit constructor mechanism in COM, so the client application has to make an explicit initialize call to specify the account that the object should represent.

We will need to define an background error handler for any errors that are reported asynchronously by method calls. Here we will log the error to the Windows event log. This default handler is installed only when we are actually running as a component server.

We next define a proc for running the component:

We have defined everything we need to but there are a few final considerations to take into account:

When constructing the command that the SCM calls to execute the component process, we will use the file attributes command to convert all paths used in the command to their short 8.3 versions. This is to avoid having to deal with quoting issues when there are spaces or other special characters in the paths.

And there you have it. A COM component in just a few lines of code. No need for understanding or writing IDL files or any additional compiler tools. Here is the full listing.

To make sure the component actually works, we need to first install it.

Let us try it out and see if returns the correct results.

Voila! There we go. And any suspicious souls who are not convinced we are using COM, can run the VBscript below.

Now that we have our irrefutable proof that it actually works, we can uninstall the component so as to not clutter up the registry.

We finish our illustration with a couple of comments about the script structure.

If you take a close look at the component source code that we implemented, you will see it takes very little code to expose Tcl as a COM object to other applications. There is not even any IDL required. Very few languages make it so simple to write components.

There are also some limitations in components implemented using Tcl and the twapi_com package. They can only run as out-of-process components which has an impact on performance compared to in-process implementations. (However, this is true for most dynamic languages, not just Tcl). Also, the components only support the automation based interfaces. This limits their use in some situations like Windows Shell plug-ins which require in-process implementations using custom interfaces (not based on automation).

When instantiating a COM object, a client can request the object be activated or instantiated on a specific remote system. From Tcl this is done by specifying the -system option to the comobj command.

This is all that is required assuming

Note the server need not even be aware that the client is remote.

Administrators can also configure the system (through the ubiquitous registry) such that a request is satisfied by a remote component even without the client requesting it. In this case, even the client is not aware that the server is located on a different system. This is done through the dcomcnfg program as described in Component configuration example or by directly creating a registry value with name RemoteServerName under the key \Software\Classes\AppID\APPID where APPID is the AppID of the component. The value of RemoteServerName should be the name of the remote server. Now even a simple instantiation command

will result in the object being created on the remote system, unbeknownst to the client.

When using the registry method, the component must be “installed” on the client system. Essentially, this means the binaries need not be present but the corresponding registry entries have to be there so that component CLSID can be mapped to the appropriate APPID.

Like for any other secured resource, security for COM can require a client that is attempting to access a COM server to prove its identity. Less commonly, the client may also need to authenticate a server, for example before it passes on sensitive data. COM security allows for both sides to verify each other’s identity.

There are various facets to this aspect of security that we discuss here.

COM defines authentication levels that specify the level of protection of communication between client and server. This protection includes

The various levels of authentication are shown in COM authentication levels in ascending order of the protection they provide.

If you are worried about security (and you always should be) only one of the top two levels should be configured depending on whether privacy of data is a concern or not.

The security features that protect a COM interaction may be implemented via different protocols implemented by various authentication services. The security package providers that provide these services and the features they support are shown in Authentication service provider.

Let us revisit our earlier discussion of Distributed COM. As we described there, instantiating a remote object involves two separate negotiated connections:

Clearly, before the server is actually running, it cannot programmatically control what clients invoke it. Thus activation security is configured purely outside of the COM server itself via settings in the Windows registry. An administrator uses a tool, usually dcomcnfg.exe, to configure these permissions. Call security can also be configured in this fashion but the difference is that since the component is now already activated and running, it can itself programmatically configure the security on its connection as well as control access to its hosted objects.

A COM server can control access to its objects and even object methods using the native Windows access control mechanism described in the Windows Security chapter. This takes the form of one or more security descriptors that define which accounts can access the protected object or method.

Access control can be configured through the registry (usually using dcomcnfg.exe) or programmatically by the COM server. In the latter case, the access control can be done through a single one-time call that controls access without any more explicit checks on incoming method invocations, or explicitly for every object and method by checking the client identity against the security descriptor(s) using the access control API’s.

Although COM defines the notion of authorization, none of the implemented security providers, NTLM, Kerberos, or Schannel support it. We do not discuss it further here.

The term security blanket refers to the entire set of security attributes associated with one or more COM connections proxies in a process. These include authentication services and levels, identities, impersonation levels and access control lists.

This security blanket interaction is negotiated between the client and the server at the time the transport connection is established between the two. The proposed parameters for the negotiations may come from system defaults set in the registry, component specific settings in the registry, programmatically set by a process for all COM connections in the process, or programmatically set for each connection.

The actual process of negotiation is somewhat involved but in a nutshell, it results in a security blanket composed of

Note as an aside that the access control settings are not actually negotiated but are simply enforced on the server side.

If you are still reading at this point, clearly your head is happily intact and we can look at how COM security is implemented by working through a couple of examples.

In the first example, we will use the component we developed earlier and show how it can be accessed remotely in secure fashion purely through system configuration and without any changes to the component code.

In the next section we will illustrate a second, little more sophisticated example with impersonation and access control where both configuration-based and programmatic mechanisms will be utilized.

In the previous section we showed how secure remote access to a component is done purely through configuration and without any coding.

Security settings from a client perspective are usually done in this fashion. Although it is possible in theory to also configure these through the registry, unlike components, client programs do not register themselves and therefore configuration via the registry or dcomcnfg is rare.

Why would a component want to specify settings programmatically? An example would be a component that wants to ensure all data is sent encrypted irrespective of how the system defaults or component registry settings are configured (or misconfigured). Another would be a situation where security parameters are dynamically changed based on factors such as client identity, location etc.

The following can be programmatically specified:

These settings are then used as described earlier in Security blanket negotiation.

Programs can set these security settings either on a process-wide basis or in a more fine-grained manner for access to specific objects and methods. In the latter case, they can even be changed dynamically, for example, to raise the level of protection when communicating sensitive data.

Because there are a whole bunch of things that can go wrong in getting remote access to work, this section lists some common issues that may arise that prevent access and provides some hints for troubleshooting.

If you are getting errors like

it is most likely that either the remote server name cannot be resolved or that network connectivity issues, including firewalls, are blocking access. (Remember that COM communication takes place over RPC.) Follow the troubleshooting guide at http://social.technet.microsoft.com/wiki/contents/articles/4494.windows-server-troubleshooting-the-rpc-server-is-unavailable.aspx for detailed troubleshooting instructions. Additional useful information about Windows firewall settings to permit RPC and name resolution is available at http://technet.microsoft.com/en-us/library/cc732839(v=ws.10).aspx, http://technet.microsoft.com/en-us/library/cc947809(v=ws.10).aspx and http://technet.microsoft.com/en-us/library/cc738971(v=ws.10).aspx.

Note that the executable that implements the server component (generally your tclsh.exe or wish.exe executable for components implemented in Tcl) must be permitted to receive incoming connection.

In order to run a server under any account, that account is required to have the SeBatchLogonRight privilege. You can verify this through the MMC Users and Groups plug-in.

Use dcomcnfg to verify that

Remember both of the above must be satisfied before access is allowed.

id_com_administrators_limits You will find that the Administrators group is listed in the system-wide permissions settings by default and therefore reasonably expect that a client presenting credentials belonging to an member of this group on the server would be allowed access.

How naive of you to expect things to work reasonably!

Although the group Administrators is listed with all the appropriate permissions, attempted remote access under a local user account that belongs to the Administrators group can (and most likely will) fail with a “Access denied.” error. This is because for remote access newer versions of Windows (basically those implementing User Account Control) will by default downgrade the admistrative account rights to a standard user account. This behaviour apparently does not affect domain accounts that belong to the Administrators group.

To change this behaviour, the registry key

can be set to a value of 1. The author strongly recommends against this kind of action that has a global effect on the system unless there is no alternative. A better solution is to not use the Administrators group for access but instead create a specific group (or add the account to Distributed COM Users) for remote access instead. However that does not help if you actually want to do additional operations remotely that require administrative privileges. See the Microsoft knowledgebase article http://support.microsoft.com/kb/951016.

Moreover, if your require unauthenticated remote COM access (never a good idea), additional registry changes may be required. See the Microsoft TechNet article http://technet.microsoft.com/en-us/library/cc781010(v=ws.10).aspx.

You may have verified your component permissions, and that you are not affected by the administrative account issues above, and therefore expect that everything will now work. But it doesn’t! You forgot about group policy settings!

Remember if those group policies are enabled, the access limits there override the ones configured in the registry with dcomcnfg and any set programmatically by the component So verify those are correct if you are using group policies.

You can enable logging of access control errors in COM. This can be tremendously useful because the log messages often pinpoint the cause of the errors. The log messages indicate

Logging is off by default. To enable logging, set the registry DWORD values shown in COM logging registry settings under the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole.

The messages are logged to the Windows event log. Check both the application and system event logs for relevant messages.

Further details about the use of these settings is available at http://msdn.microsoft.com/en-us/library/windows/desktop/ms687309(v=vs.85).aspx.