COM Objects

mIRC allows you to call COM objects via scripts. You must have experience with COM objects in order to use this feature.

/comopen name progid

This opens a COM connection to object progid eg. Excel.Application, and assigns the connection a name.

You should check $comerr after making this call to confirm that the COM connection was successful.

/comclose name

This closes the specified COM connection.

/comreg -u filename

This registers/unregisters a COM DLL with windows.

example {

comopen name progid

; if comopen failed, maybe the DLL that came with the script isn't registered

if ($comerr) {

;register the DLL

comreg test.dll

;try to open it again

comopen name progid

; still failed, halt the script

if ($comerr) halt

}

}

$comerr

This should be checked after a call to any COM command or identifier. Returns 1 if there was an error, 0 otherwise.

$com(name,member,method,type1,value1,...,typeN,valueN)

This calls a member of an open COM connection with the specified method and parameters.

name - connection name.

member - member name.

method - Combination of the following values added together:

1 = DISPATCH_METHOD

2 = DISPATCH_PROPERTYGET

4 = DISPATCH_PROPERTYPUT

8 = DISPATCH_PROPERTYPUTREF

type - the variable type, can be: i1, i2, i4, ui1, ui2, ui4, int, uint, r4, r8, cy, date, decimal, bool, bstr, variant, dispatch, unknown, error.

VB equivalents are: boolean, byte, currency, date, double, integer, long, single, string, variant.

To make a variable by reference, use * in the type name, eg. i1*

To assign a name to a variable for later reference after a call, append it to the type, eg. i1* varname

When using a variant you must also specify the variable type after it, eg. variant bool.

value - the value assigned to the variable type.

Returns: 1 = ok, 0 = fail.

After you've opened a COM connection or made a call to $com() you can use the following forms of $com():

$comcall(name,alias,...)

$comcall() uses the same format as $com() apart from the alias. It is multi-threaded so it will not halt the script and will call the specified alias once the call returns.

Note: If $comcall() fails when calling an object and $com() does not, this means that object is not compatible with mIRC's threading model, so $com() must be used. You can check the $comerr value in the alias to determine if a $comcall() failed or not.

$com(name/N)

Returns name if connection is open, or name of Nth connection. N = 0 returns number of open connections.

Properties: progid, dispatch, unknown, result, error, errortext, argerr

progid - object name.

result - the value returned by the COM object member after the call.

error - error value, if there was an error.

errortext - error description associated with error.

argerr - Nth argument that caused the error, if the error was due to an invalid variable type.

$com(name/N,varname)

Returns value of the specified variable name.

$comval(name,N,member)

Returns member value for the Nth instantiation of the enumerated collection in name.

Dispatch and Unknown

The two variable types dispatch and unknown allow you to pass dispatch/unknown pointers as parameters in a $com() call, or retrieve dispatch/unknown pointers from a $com() call, by reference.

To pass a dispatch/unknown pointer as a parameter in $com(), specify the variable type as dispatch/unknown, and specify the name of an existing $com() connection as the value.

To retrieve a dispatch/unknown pointer through a call to $com(), specify a dispatch* item, with a variable name, as the last parameter in a $com() call, without assigning it a value. When $com() returns, mIRC will create a new $com() item with that variable name and assign it the dispatch or unknown pointer. See example script #2 below.

In the case of retrieving an unknown pointer, mIRC will extend it to a dispatch pointer if it can, allowing you to call it directly via $com().

You can use $com().dispatch or $com().unknown to see if a pointer exists for that $com() item.

Example Script #1

The following script is a simple example that connects to excel and then retrieves and sets the visible property.

excel {

comopen excel Excel.Application

if ($comerr) {

echo comopen failed

halt

}

; check if excel window is visible

if ($com(excel,Visible,3) == 0) {

echo $com failed

goto finish

}

echo Visible: $com(excel).result

; make excel window visible

if ($com(excel,Visible,5,i4,1) == 0) {

echo $com failed

goto finish

}

; check visibility again

if ($com(excel,Visible,3) == 0) {

echo $com failed

goto finish

}

echo Visible: $com(excel).result

:finish

comclose excel

}

Example Script #2

The following script retrieves information about your CPU. It displays debugging information so see you can see whether a call succeeded or not, the value it returned, and whether a new COM object was created.

cpu {

comopen Locator WbemScripting.SWbemLocator

if ($comerr) { echo comopen failed | halt }

echo com: $com(Locator, ConnectServer, 3, dispatch* Services)

echo result: $com(Locator).result

echo com(0): $com(0)

if ($com(Services)) {

echo com: $com(Services, Get, 3, string, Win32_Processor.DeviceID='CPU0', dispatch* More)

echo result: $com(Services).result

echo com(0): $com(0)

if ($com(More)) {

echo com: $com(More, Name, 3)

echo result: $com(More).result

echo com: $com(More, Caption, 3)

echo result: $com(More).result

echo com: $com(More, Manufacturer, 3)

echo result: $com(More).result

comclose More

}

comclose Services

}

comclose Locator

}

Example Script #3

The following script retrieves information about your hard drives. It does so by retrieving all drive instances in an enumerated collection and then accessing member values for each instance using the $comval() identifier.

drives {

comopen Locator WbemScripting.SWbemLocator

if ($comerr) { echo comopen failed | halt }

echo Com: $com(Locator,ConnectServer,3, dispatch* Services)

echo Result: $com(Locator).result

comclose Locator

if $com(Services) {

echo com: $com(Services, InstancesOf,3,string,Win32_LogicalDisk,dispatch* Instances)

echo result: $com(Services).result

comclose Services

}

if $com(Instances) {

echo com: $com(Instances,Count,3)

var %n = $com(Instances).result

echo result: %n

var %m = 1

while (%m <= %n) {

echo 4 disk: %m

echo 3 Com: $comval(Instances, %m, Name)

echo 3 Com: $comval(Instances, %m, FileSystem)

echo 3 Com: $comval(Instances, %m, FreeSpace)

echo 3 Com: $comval(Instances, %m, Description)

inc %m

}

comclose instances

}

}