To get a peek on all objects currently installed on your system, the "OLE/COM Object Viewer" is a very helpful tool. This tool will be explained in a separate section below.

Let's do another example.  We would like to get a HTML source code from a certain web page.  You could use the internal InetGet() function to save the result to a file and retrieve it back again with FileRead(). But these lines of code do the same:

$oHTTP = ObjCreate("winhttp.winhttprequest.5.1")
$oHTTP.Open("GET","http://www.AutoItScript.com")
$oHTTP.Send()
$HTMLSource = $oHTTP.Responsetext

The (string) variable $HTMLSource now contains the complete HTML code of the AutoItScript.com home page (that is, the top HTML-Frame).

(Information about the "winhttp.winhttprequest" object can be found at:
http://msdn.microsoft.com/library/en-us/winhttp/http/winhttprequest.asp )

Please mind this: The existence of Objects depend on the computer's operating system and installed programs.  For example, the winhttp.winhttprequest.5.1 object only exists on computers that have at least Internet Explorer version 5 installed. When you are sharing scripts that use COM objects, be sure the objects exist on all computers.

Object variables behave a bit different than other types of AutoIt variables. An Object is not a real value, but a 'pointer' to something outside the script. So you can't perform arithmetic's, nor equations on Object variables. When you assign an Object variable a different value, the 'pointer' will automatically be released.  You can, for instance, force deletion of an Object by assigning it any number or any text value.

$oHTTP = ObjCreate("winhttp.winhttprequest.5.1")  ; Object is created
$oHTTP=0                                          ; Object is deleted 

You don't need to delete Objects when you are finished. If a script exits, AutoIt tries to release all active references to Objects that had been created in the script. Same thing happens when you had defined a local Object variable inside a function, and the function ends with a return.

Automation using COM

A very popular application of COM is to 'automate' programs.  Instead of using the regular AutoIt functions like Send() or WinActivate(), you can make use of the Objects that are defined inside the program.

Here is an example that 'automates' Microsoft Excel:

$oExcel = ObjCreate("Excel.Application")                   ; Create an Excel Object
$oExcel.Visible = 1                                        ; Let Excel show itself
$oExcel.WorkBooks.Add                                      ; Add a new workbook
$oExcel.ActiveWorkBook.ActiveSheet.Cells(1,1).Value="test" ; Fill a cell
sleep(4000)                                                ;See the results for 4 seconds
$oExcel.ActiveWorkBook.Saved = 1                           ; Simulate a save of the Workbook
$oExcel.Quit                                               ; Quit Excel 

The complexity of controlling other programs depends on that specific program, not on the AutoIt script.  If something does not work as expected you might need to consult the applications' documentation and not the AutoIt help.

Special Statements

In AutoIt, two special statements are designed for COM usage:

WITH/ENDWITH and the FOR/IN/NEXT loop.

WITH..ENDWITH

The WITH/ENDWITH statement does not add functionality, but it makes your script easier to read.  For instance, the previous example using Excel can also be written as:

$oExcel = ObjCreate("Excel.Application")                ; Create an Excel Object

WITH $oExcel
    .Visible = 1                                        ; Let Excel show itself
    .WorkBooks.Add                                      ; Add a new workbook
    .ActiveWorkBook.ActiveSheet.Cells(1,1).Value="test" ; Fill a cell
    sleep(4000)                                         ;See the results for 4 seconds
    .ActiveWorkBook.Saved = 1                           ; Simulate a save of the Workbook
    .Quit                                               ; Quit Excel
ENDWITH

This example does not save you a lot of text, but when your object uses long lines of properties/methods, you can shorten it heavily within a WITH statement.

FOR..IN

The FOR...IN loop is required when using Collections.  Collections are a special type of Object, that exist out of multiple sub-Objects. You could see them as Arrays (Actually, the FOR..IN statement also works on Array-type variables).

FOR..IN loop using an Array

Below is an example of an FOR..IN loop.  This example uses a normal AutoIt array, so it has nothing to do with COM. It's just to show you the principle:

$String = ""               ; A string for displaying purposes

$aArray[0]="a"             ; We fill an array
$aArray[1]=0               ; with several
$aArray[2]=1.3434          ; different
$aArray[3]="testestestest" ; example values.

FOR $Element IN $aArray    ; Here it starts..
   $String = $String & $Element & @CRLF
NEXT

; Now Show the results to the user
Msgbox(0,"For..IN Arraytest","Result: " & @CRLF & $String)

FOR..IN loop using an Object

In most cases you can't use 'normal' Object methods to retrieve the elements of a collection.  In 'COM'-terms they say you have to 'enumerate' them.  This is where the FOR..IN loop comes in.

The Excel example below loops on cells A1:O16 on the current active sheet. If one of the cells has a value less than 5, the code replaces the value with 0 (zero):

$oExcel = ObjCreate("Excel.Application") ; Create an Excel Object

$oExcel.Visible = 1               ; Let Excel show itself
$oExcel.WorkBooks.Add             ; Add a new workbook

dim $arr[16][16]                  ; These lines
for $i = 0 to 15                  ; are just
  for $j =  0 to 15               ; an example to
   $arr[$i][$j] = $i              ; create some
  next                            ; cell contents.
next

$oExcel.activesheet.range("A1:O16").value = $arr ; Fill cells with example numbers

sleep(2000)                       ; Wait a while before continuing

For $cell in $oExcel.ActiveSheet.Range("A1:O16")
   If $cell.Value < 5 Then
       $cell.Value = 0
   Endif
Next

$oExcel.ActiveWorkBook.Saved = 1 ; Simulate a save of the Workbook
sleep(2000)                      ; Wait a while before closing
$oExcel.Quit                     ; Quit Excel

Advanced COM usage

The following features of AutoItCOM requires profound knowledge of COM Events and COM Error handling.

If you are a newbie to COM programming, please read some good COM documentation first.

The bible of COM is the book called "Inside OLE 2" by Kraig Brockschmidt (Microsoft Press).

You can also find some COM resources on the internet (not AutoIt related):

http://msdn.microsoft.com/archive/en-us/dnarolegen/html/msdn_aboutole.asp (introduction)

http://www.garybeene.com/vb/tut-obj.htm (about Objects in Visual Basic)

http://java.sun.com/docs/books/tutorial/java/concepts/     (Using objects in Java)

http://msdn.microsoft.com/archive/en-us/dnarguion/html/drgui082399.asp (Object Events in C++)

http://www.garybeene.com/vb/tut-err.htm (Error handling in Visual Basic)

COM Events

Normal COM Automation mainly uses one-way communication.  You 'ask' the Object for any properties or results from a Method.  However a COM Object can also 'talk back' to your script when it suits it.

This could be very handy in cases you need to wait for some COM-related action to happen. 

Instead of writing a kind of loop, asking the Object if something interesting has happened, you can let the Object itself call a specific UDF in your script.  Meanwhile you can do other things in your script (almost) simultaneously.

Not all Object to support events. You have to read the Object documentation carefully whether it supports events or not.

If it does, the second thing to know is the type of Events it supports. AutoItCOM can only receive 'dispatch' type events.

Finally you have to know the names of the Events the Object could generate, including their arguments (if any).

Only when you have all this information, you can start building an AutoIt script using COM Events.

Below is a snippet from a script that demonstrates how to receive Events from the Internet Explorer:

Click here to view the complete script.

The main line in this script is: $EventObject=ObjEvent($oIE,"IEEvent_",...).
This function takes the object $oIE and reroutes it's events to AutoIt functions whose names start with MYEvent_.  The third parameter is optional. It is used when an Object has multiple Event interfaces and you don't want AutoIt to choose one automatically.

The Object responsible for the continuous rerouting is $EventObject. This variable does not require any further attention, unless you want to stop the events.

To stop rerouting Events, you can not just delete the variable like $EventObject="". The reason is that the 'calling' Object is still holding a reference to this variable, and it won't loose it until the Object itself quits. You could solve this problem by killing the 'calling' Object, but you can also tell the Object that you don't want to receive any events by using: $EventObject.Stop.  Then you can (but not really necessary) kill the Event by assigning it any value, like: $EventObject=""

If you know the names of the Events $oIE fires, you can implement the Events you are interested in by creating AutoIt UDF's with the name IE Event_Eventname(optional arguments). Be sure you use the correct number of arguments and in their correct order as specified for THAT Event function.  Otherwise you might end up with unexpected values. 

If you don't know (for some reason) the names of the events, you can add a UDF with only the prefix. In this example: Func IEEvent_($Eventname).
When an event is received and no IEEvent_ Eventname UDF exists, this function will be called instead and the name of the event will be placed in the variable $Eventname.

You don't have to implement ALL event functions. Those not implemented will just be ignored.

More script examples using COM Event functions can be found in the tests directory in the AutoIt 3.1.1.xx beta ZIP distribution file, downloadable from: http://www.autoitscript.com/autoit3/files/beta/autoit/

Limitations on COM Events in AutoIt

Some Objects (like the 'WebBrowser') pass arguments to their Event Functions 'by reference'. This is intended to allow the user change these arguments and passing it back to the Object.  However, AutoIt uses it's own variable scheme, which is not compatible to COM variables.  This means that all values from Objects need to be converted into AutoIt variables, thus loosing the reference to the original memory space.  Maybe in the near future we can solve this limitation for you !

COM Error Handling

Using COM without proper error handling can be very tricky. Especially when you are not familiar with the Objects in your script.

An AutoIt script will immediately stop execution when it detects a COM error.  This is the default and also the safest setting.  In this case you have to take measures in your script to prevent the error from happening.

Only if there is no way to prevent a COM error, you could install an "Error Handler" in which you take action after the error has happened. It is not a solution to make a buggy script work properly. Neither does it catch non-COM related script errors (e.g. declaration and syntax errors).

Error handling is implemented in the same way as a normal COM Event, using ObjEvent() and a user defined COM Event Function. The only difference is the usage of the fixed string "AutoIt.Error" as the name of the object.

An example:

$oMyError = ObjEvent("AutoIt.Error","MyErrFunc") ; Install a custom error handler

; Performing a deliberate failure here (object does not exist)
$oIE = ObjCreate("InternetExplorer.Application")
$oIE.visible = 1
$oIE.bogus
if @error then Msgbox(0,"","the previous line got an error.")

Exit


; This is my custom error handler
Func MyErrFunc()
   $HexNumber=hex($oMyError.number,8)
   Msgbox(0,"","We intercepted a COM Error !" & @CRLF & _
                "Number is: " & $HexNumber & @CRLF & _
                "Windescription is: " & $oMyError.windescription )

   SetError(1) ; something to check for when this function returns
Endfunc