Commands for accessing COM servers
package require twapi
This module is still experimental and liable to change.
This module provides commands for supporting COM clients. TWAPI's COM support is limited to client side calls only and is not intended to compete with the OpTcl or TCOM packages. It was added to allow TWAPI access to some of the simpler COM based API's in Windows including WMI and ADSI.
A COM object can be created through the command comobj using the PROGID or CLSID of the corresponding COM class. This returns a Tcl command that may be used to access the object through subcommands.
When the object is no longer required, it must be explicitly destroyed by calling the command with the -destroy subcommand.
The properties and methods of a COM object can be accessed as subcommands of the Tcl command representing that object. The names of properties and methods can in theory overlap. Althouth TWAPI can usually figure out whether a property is being retrieved/set or a method is being called, you can explicitly control this by using the -get, -set or -call subcommands followed by the actual name. The following sequence of commands shows a sample session that drives Internet Explorer through its properties and methods.
Start up Internet Explorer (note it will not be visible yet)
set ie [comobj InternetExplorer.Application -enableaaa]Make its window visible by changing its Visible property.
$ie Visible trueThis could also have been written as
$ie -set Visible trueto explicitly indicate we want to set the property called Visible as opposed to making a call to the COM object's method of the same name (if there was one).
To go to the TWAPI home page, invoke the Navigate method
$ie Navigate http://twapi.sf.netGet the LocationURL property to find the URL after redirection
$ie LocationURLNot specifying any parameters gets the default value of the object. This is the property marked as the default value in the COM object's IDL definition.
$ieAsk the application to exit by calling its Quit method.
$ie QuitFinally, destroy the COM object.
$ie -destroy
Some COM objects are collection of items which may even be other COM objects. The items within these collections can be accessed by their index (which is not necessarily an integer) but it is often easier to iterate over them using the -iterate operator on the collection object. The following example illustrates this.
set fso_obj [comobj Scripting.FileSystemObject] set drives_obj [$fso_obj Drives] $drives_obj -iterate drive_obj { puts [$drive_obj DriveLetter] $drive_obj -destroy } $drives_obj -destroy $fso_obj -destroyThe Drives method of the Scripting.FileSystemObject returns a collection drives_obj. The -iterate operator on the collection then loops through each item in the collection, assigning the item to drive_obj. In this case, each item is itself a COM object from which we get the DriveLetter property. Note that the drive_obj object generated in each iteration has to be explicitly destroyed.
In many cases, the desired objects have to be created by navigating through other objects. For example, the following example sets all cells within a range in a spreadsheet to 12345.
set xl [comobj Excel.Application] $xl Visible true set workbooks [$xl Workbooks] set workbook [$workbooks Add] set sheets [$workbook Sheets] set sheet [$sheets Item 1] set cells [$sheet range a1 c3] $cells Value 12345 $cells -destroy $sheet -destroy $sheets -destroy $workbook -destroy $workbooks -destroy $xl Quit $xl -destroyIn 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 -with subcommand can be used to navigate through the intermediate objects as follows:
set xl [comobj Excel.Application] $xl Visible true $xl -with { Workbooks Add Sheets {Item 1} {range a1 c3} } Value 12345 $xl -destroyThe -with subcommand takes a list of intermediate methods and associated parameters each of which should return a new object. Each element in the list is invoked on the previously created object and in turn should return a new COM object. The final object created from this list is passed the remaining arguments in the command. All intermediate objects are automatically destroyed.
Some COM objects may generate notifications when certain events occur. A callback script may be registered using the -bind subcommand on a COMOBJ object. This script is invoked for every notification event generated by the COM object. The event name and parameters provided by the COM event source are appended to the script.
The following example receives events from Internet Explorer and prints them.
proc print_event args {puts "Received: [join $args ,]"} set ie [comobj InternetExplorer.Application -enableaaa] $ie Visible true set bind_id [$ie -bind print_event] $ie Navigate http://www.tcl.tk after 2000 $ie -unbind $bind_id $ie Quit $ie -destroyNote that the script is unregistered using the -unbind subcommand when no longer needed.
-disablelog BOOLEAN | If specified as true, disables logging of failures. Corresponds to the flag CLSCTX_NO_FAILURE_LOG in the SDK. |
-download BOOLEAN |
If specified as true, allows downloading of code from the Internet or Directory
Service. This corresponds to setting the flag
CLSCTX_ENABLE_CODE_DOWNLOAD.
If specified as false, disallows downloading of code from the Internet or Directory
Service. This corresponds to setting the flag
CLSCTX_DISABLE_CODE_DOWNLOAD.
If this option is not specified, neither of the flags is set in the underlying call to CoCreateInstance. |
-enableaaa BOOLEAN |
If specified as true, enables activate-as-activator activations where
a server process is launched under the caller's identity.
This corresponds to setting the flag
CLSCTX_ENABLE_AAA.
If specified as false, disables activate-as-activator activations.
This corresponds to setting the flag
CLSCTX_DISABLE_AAA.
If this option is not specified, neither of the flags is set in the underlying call to CoCreateInstance. |
-model MODELLIST | Specifies which of the COM hosting models are acceptable. MODELLIST must be a list containing one or more of the symbols localserver, remoteserver, inprocserver, inprochandler, or any signifying any model is acceptable. |
-nocustommarshal BOOLEAN | If true, the object creation will fail if it uses custom marshalling. Corresponds to the flag CLSCTX_NO_CUSTOM_MARSHAL. |
Copyright © 2006 Ashok P. Nadkarni