mircscripting.info Forum Index mircscripting.info
#mIRCscripting Forum
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

COM Tutorial

Post new topic   Reply to topic    mircscripting.info Forum Index -> Tutorials
View previous topic :: View next topic  
Author Message

Joined: 03 May 2008
Posts: 6

PostPosted: Sat May 03, 2008 3:10 pm    Post subject: COM Tutorial Reply with quote


Disclaimer: If your IQ is less than eighty and you're viewing this topic... you've wasted your time. You're probably not going to understand this tutorial in any way, shape, or form if the above sentence applies to you. Therefore, I ask you to stop reading before you strain your mind too much and injure yourself by trying to think to hard. I ask you this for your own benefit, as I am not liable for any injuries (mental or physical) that may occur.

A Guide to COM

COM stands for Component Object Model. It is best described as pieces of compiled code that execute tasks, and this is not to be confused with OOP (Object Oriented Programming). Applications can interact with COM through interfaces (Note: All OLE services are COM interfaces). Such interfaces have names that generally start with an "I" (IDispatch and IUnknown for example). Each COM object has it's own members (comprised of methods, properties, and constants). Each method is an "action" for lack of a better term whereas properties are for returning values and constants are well... constant. Luckily mIRC has COM support! This is because COM is the solution to the four basic problems that occur within component software (Basic Component Interoperability, Versioning, Language Independence, and Transparent Cross-Process Interoperability). Because we can use COM with mIRC we can provide it with greater functionality and create scripts that accomplish things that mIRC cannot on it's own.

mIRC Commands


:: /comopen name progid

Description: Opens a COM connection to specified programmatic identifier with assigned name.

Note: Extra tokens on the command will cause it to fail.

:: /comclose name

Description:  Closes the COM connection to which the specified name was assigned.

Note: COM identifiers may be used as trailing tokens with this command.

:: /comreg -u filename

Description: Registers/Unregisters a COM DLL with Windows.

mIRC Identifiers


:: $comerr

Description: Returns 1 if an error occurred during a com call, 0 if not.

Note: Should be checked often, especially after the initial /comopen command is used.

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

Description: Calls member of specified COM object with given method or property as well as passing any arguments you specify along with it.

$com(name/n) -> returns if $com(name) exists or the name of the nth com connection.
$com(name/n,var) -> returns the value of the variable for that com connection.

Method values:

1 -> DISPATCH_METHOD -> Call a member of an object
2 -> DISPATCH_PROPERTYGET -> Return a value
4 -> DISPATCH_PROPERTYPUT -> Set a property
8 -> DISPATCH_PROPERTYPUTREF -> Set a property by reference

Type values:

i1 -> single byte "signed" integer. (Works the same as ui1)
(0 to 225)

i2 -> two byte signed integer.
(-32768 to 32767)

i4 -> four byte signed integer.
(-2147483648 to 2147483647)

ui1 -> single byte unsigned integer.
(0 to 255)

ui2 -> two byte unsigned integer.
(0 to 65535)

ui4 -> four byte unsigned integer.
(0 to 4294967295)

int -> integer.
(-2147483648 to 2147483647)

uint -> unsigned integer.
(0 to 4294967295)

r4 -> real, 4-byte floating point number.
(1.17549435E-38 to 3.40282347E+38)

r8 -> double real, 8-byte floating point number.
(2.2250738585072014E-308 - 1.7976931348623157E+308 )

cy -> eight byte curreny number.
(-922337203685477.5625 to 922337203685477.5625)

date -> contains date and time, stored as an 8-byte floating-point number.
(0 through +/-79,228,162,514,264,337,593,543,950,335 with no decimal point)
(0 through +/-7.9228162514264337593543950335 with 28 places to the right of the decimal)

decimal -> this data type indicates numeric data with a fixed precision and scale.

bool -> can contain any string or numeric representation.

bstr -> basic string , this data type indicates a null-terminated unicode character string.

variant -> can contain string, date, time, boolean, or numeric values.

dispatch -> this data type indicates a pointer to an IDispatch interface.

unknown -> this data type indicates a pointer to an IUnknown interface.

error -> this data type indicates a 32-bit error code.


$com(r).result -> Returns the result after calling a COM member.
$com(r).error -> If an error occurs it returns it's value
$com(r).errortext -> If there was an error, returns a description.
$com(r).argerr -> mIRC Help File: "Nth argument that caused the error, if the error was due to an invalid variable type."
$com(r).dispatch > Boolean returned if dispatch pointer.
$com(r).unknown > Boolean returned if unknown pointer.

:: $comcall(name,alias,...)

Description: Calls the alias provided after the com call returns. The identifier is multi-threaded so your script will continue with or without a com result.

Note: The arguments of $comcall are the exact same as $com with the exception of the alias.

:: $comval(name,n,member)

Description: Returns the nth item of the enumerated collection.

Scripting Examples, Uses, and Applications

The following script shows the basic of opening/closing com connections and some of $com()'s uses.

alias basics {

  ; open com connection a with wscript.shell
  comopen a wscript.shell

  ; check if $com(a) exists
  if ($com(a)) {

    ; check $com(0) :: total # of com connections
    echo -a & COM connections: $com(0)

    ; check $com(1) :: value of first opened com connection
    echo -a & First COM connection: $com(1)

    ; use command and set a variable
    noop $com(a,sendkeys,1,bstr* variable,hello world!)

    ; echo variables value
    echo -a & Value of Variable "variable": $com(a,variable)

    ; close com a
    comclose a


  ; echo error message
  else echo -a * /basics: com error.


Here we have an example script outlining the uses of $com()'s multiple properties.

alias properties {

  ; open com e
  comopen e wscript.network

  ; check $com(e).progid
  echo -a & Programmatic Identifier: $com(e).progid

  ; pass invalid command to $com(e)
  noop $com(e,invalid,2)

  ; check for the error
  if ($comerr) {

    ; echo error information
    echo -a & ArgErr: $com(e).argerr
    echo -a & Error: $com(e).error
    echo -a & ErrorText: $com(e).errortext


  ; pass valid command and check $com(e).result
  noop $com(e,computername,2)
  echo -a & Result: $com(e).result

  ; open new com h
  comopen h htmlfile

  ; check that com connection h exists
  if ($com(h)) {

    ; pass command and arguments to com h and dispatch to com t
    noop $com(h,write,1,bstr,<html>&copy;hampagne</html>) $com(h,body,3,dispatch* t) $com(t,innerText,3)

    ; echo if dispatch or unknown pointers exist for com connection h
    echo -a & Dispatch: $com(h).dispatch
    echo -a & Unknown: $com(h).unknown


  ; close opened com connections
  tokenize 32 e h t
  comclose $*


An example of enumerating a collection.

alias enumeration {

  ; initial com connection names (unique)
  var %a $ticks, %b b $+  %a

  ; check that $com(%a) is not already open & $comerr
  if (!$com(%a)) .comopen %a wbemscripting.swbemlocator
  if (!$comerr) {

    ; enumerate the win32_process collection
    .comclose %a $com(%a,connectserver,3,dispatch* %b)
    .comclose %b $com(%b,execquery,3,bstr,select * from win32_process,dispatch* %a)

    ; while item %i exists in the collection, echo it's description
    var %i 1
    while ($comval(%a,%i,description)) {
      echo -a & $v1
      inc %i

  comclose %a



Retrieving data from an application from mIRC. (itunes in this example.)

alias itunes {
  var %a $1,%b $1b
  .comopen %a itunes.application

  ; dispatch to itunes current track interface
  ; invoke method $1
  .comclose %a $com(%a,currenttrack,3,dispatch* %b) $com(%b,$1,3)

  ; close com %b after the calling script ends
  .timer 1 0 .comclose %b

  ; return result
  return $com(%b).result


alias data {
  ; echo different types of itunes data for the currently playing track

  echo -a & $itunes(name)
  echo -a & $itunes(time)
  echo -a & $itunes(artist)
  echo -a & $itunes(album)
  echo -a & $itunes(genre)
  echo -a & $itunes(playedcount)


A more advanced example, referencing dispatched objects.

alias reference {
  if (!$com(ref.1)) .comopen ref.1 microsoft.xmldom
  if (!$comerr) {

    ; Create Element "root"
    echo -a & $com(ref.1,createElement,1,bstr,root,dispatch* ref.2)
    if ($com(ref.2)) {

      ; append element "root" to xml document
      echo -a & $com(ref.1,appendChild,1,dispatch,ref.2)

      .comclose ref.2
    .comclose ref.1
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic   Reply to topic    mircscripting.info Forum Index -> Tutorials All times are GMT - 5 Hours
Page 1 of 1

Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum

Powered by phpBB © 2001, 2005 phpBB Group