|
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.
To store array results into a binary variable, use $comval(name, N, member, &binvar).result. If the array is a BSTR, it is stored using null bytes as separators.
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
}
}
|