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.

 

/comlist

This lists all open COM connections.

 

/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 is not 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 have 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 the object is not compatible with the threading model of mIRC, 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.

 

Binary Variables

The $com() identifier allows passing parameters in from, and results out to, binary variables. To pass parameters in from binary variables, prefix the variable type with & to indicate the parameter is a binary variable eg. $com(name, member, method, &bstr, &binvar). To retrieve a result into a binary variable, use $com(name, &binvar).result.

 

Note: $com() also allows you to pass/retrieve one dimensional single-byte arrays from/into binary variables.

 

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 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

 }

}