# Function Reference

# ObjEvent

Handles incoming events from the given Object.

ObjEvent ( $ObjectVar, "functionprefix" [, "interface name"] )
ObjEvent ( "AutoIt.Error" [, "function"] )

## Parameters

$ObjectVar | A variable containing an Object from which you want to receive events
"functionprefix" | The prefix of the functions you define to handle receiving events. The prefix is appended by the Objects method name.
"interface name" | [optional] name of an Event interface to use. Note: It must be a supported as outgoing for the Object AND it must be of type DISPATCH.

## Return Value

Success: | an object or a function name.
Failure: | sets the @error flag to non-zero.

## Remarks

The first format is used to receive Events from the given Object.
To receive a specific event, create an AutoIt function name using the given prefix appended with the event name.
The second format is used for COM Error Handling.
If any COM error occurs, the given function is called. First parameter for the function will be the error object.
You can use it to access different properties of this object.
If the second parameter is omitted, it will return a string containing the name of the current Error handler function. If no Error handler function has been set, it will return an empty string.
You must assign the return, from the ObjEvent call, to a variable or the error handler function will not be called in the event of a COM error.
Properties of the AutoIt Error Object:

.number | The Windows HRESULT value from a COM call
.windescription | The FormatWinError() text derived from .number
.source | Name of the Object generating the error (contents from ExcepInfo.source)
.description | Source Object's description of the error (contents from ExcepInfo.description)
.helpfile | Source Object's helpfile for the error (contents from ExcepInfo.helpfile)
.helpcontext | Source Object's helpfile context id number (contents from ExcepInfo.helpcontext)
.lastdllerror | The number returned from GetLastError()
.scriptline | The script line on which the error was generated

Common HRESULT errors:

Name | Description | Value
$S_OK | Operation successful | 0x00000000
$S_FALSE | Operation Succeed with extra condition | 0x00000001
$E_ABORT | Operation aborted | 0x80004004
$E_ACCESSDENIED | General access denied error | 0x80070005
$E_FAIL | Unspecified failure | 0x80004005
$E_HANDLE | Handle that is not valid | 0x80070006
$E_INVALIDARG | One or more arguments are not valid | 0x80070057
$E_NOINTERFACE | No such interface supported | 0x80004002
$E_NOTIMPL | Not implemented | 0x80004001
$E_OUTOFMEMORY | Failed to allocate necessary memory | 0x8007000E
$E_POINTER | Pointer that is not valid | 0x80004003
$E_UNEXPECTED | Unexpected failure | 0x8000FFFF

See the Obj/COM Reference for a detailed explanation.

## Related

GUICtrlCreateObj, IsObj, ObjCreate, ObjGet

## Example

### Example 1

    #include <MsgBoxConstants.au3>

    Example()

    Func Example()
        ; Error monitoring. This will trap all COM errors while alive.
        ; This particular object is declared as local, meaning after the function returns it will not exist.
        Local $oErrorHandler = ObjEvent("AutoIt.Error", "_ErrFunc")

        ; Create Internet Explorer object
        Local $oIE = ObjCreate("InternetExplorer.Application")
        ; Check for errors
        If @error Then Return

        $oIE.Visible = True ; set visibility

        ; Custom sink object
        Local $oIEEvents_1 = ObjEvent($oIE, "_IEEvent_1_", "DWebBrowserEvents2")
        Local $oIEEvents_2 = ObjEvent($oIE, "_IEEvent_2_", "DWebBrowserEvents2")

        ; Navigate somewhere
        $oIE.navigate("http://www.google.com/")
        ; Check for errors while loading
        If @error Then
            $oIE.Quit()
            Return
        EndIf

        ; Wait for page to load
        While 1
            If $oIE.readyState = "complete" Or $oIE.readyState = 4 Then ExitLoop
            Sleep(10)
        WEnd

        ; Deliberately cause error by calling non-existing method
        $oIE.PlayMeARockAndRollSong()

        ; Check for errors
        If @error Then MsgBox($MB_SYSTEMMODAL, "COM Error", "@error is set to COM error number." & @CRLF & "@error = 0x" & Hex(@error))

        ; Wait few seconds to see if more events will be fired
        Sleep(3000)

        ; Nothing more to do. Close IE and return from the function
        $oIE.Quit()

        #forceref $oErrorHandler, $oIEEvents_1, $oIEEvents_2
    EndFunc   ;==>Example

    ; BeforeNavigate2 method definition
    Func _IEEvent_1_BeforeNavigate2($oIEpDisp, $sIEURL, $iIEFlags, $sIETargetFrameName, $sIEPostData, $iIEHeaders, $bIECancel)
        ConsoleWrite("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!--_IEEvent_1_BeforeNavigate2() fired--!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! " & @CRLF & _
                "$oIEpDisp = " & $oIEpDisp() & "  -  " & ObjName($oIEpDisp) & @CRLF & _ ; e.g. default property and name for the object
                "$sIEURL = " & $sIEURL & @CRLF & _
                "$iIEFlags = " & $iIEFlags & @CRLF & _
                "$sIETargetFrameName = " & $sIETargetFrameName & @CRLF & _
                "$sIEPostData = " & $sIEPostData & @CRLF & _
                "$iIEHeaders = " & $iIEHeaders & @CRLF & _
                "$bIECancel = " & $bIECancel & @CRLF & _
                "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! " & @CRLF & @CRLF)
    EndFunc   ;==>_IEEvent_BeforeNavigate2

    Func _IEEvent_2_BeforeNavigate2($oIEpDisp, $sIEURL, $iIEFlags, $sIETargetFrameName, $sIEPostData, $iIEHeaders, $bIECancel)
        ConsoleWrite("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!--_IEEvent_2_BeforeNavigate2() fired--!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! " & @CRLF & _
                "$oIEpDisp = " & $oIEpDisp() & "  -  " & ObjName($oIEpDisp) & @CRLF & _ ; e.g. default property and name for the object
                "$sIEURL = " & $sIEURL & @CRLF & _
                "$iIEFlags = " & $iIEFlags & @CRLF & _
                "$sIETargetFrameName = " & $sIETargetFrameName & @CRLF & _
                "$sIEPostData = " & $sIEPostData & @CRLF & _
                "$iIEHeaders = " & $iIEHeaders & @CRLF & _
                "$bIECancel = " & $bIECancel & @CRLF & _
                "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! " & @CRLF & @CRLF)
    EndFunc   ;==>_IEEvent_BeforeNavigate2

    ; User's COM error function. Will be called if COM error occurs
    Func _ErrFunc($oError)
        ; Do anything here.
        ConsoleWrite(@ScriptName & " (" & $oError.scriptline & ") : ==> COM Error intercepted !" & @CRLF & _
                @TAB & "err.number is: " & @TAB & @TAB & "0x" & Hex($oError.number) & @CRLF & _
                @TAB & "err.windescription:" & @TAB & $oError.windescription & @CRLF & _
                @TAB & "err.description is: " & @TAB & $oError.description & @CRLF & _
                @TAB & "err.source is: " & @TAB & @TAB & $oError.source & @CRLF & _
                @TAB & "err.helpfile is: " & @TAB & $oError.helpfile & @CRLF & _
                @TAB & "err.helpcontext is: " & @TAB & $oError.helpcontext & @CRLF & _
                @TAB & "err.lastdllerror is: " & @TAB & $oError.lastdllerror & @CRLF & _
                @TAB & "err.scriptline is: " & @TAB & $oError.scriptline & @CRLF & _
                @TAB & "err.retcode is: " & @TAB & "0x" & Hex($oError.retcode) & @CRLF & @CRLF)
    EndFunc   ;==>_ErrFunc

### Example 2

    Global $__g_oTemplateCOMErrorHandler = 0

    Local $oShell = ObjCreate("Shell.Application")

    ; Wrap calls that are likely to fatal error

    ; This won't fatal error, it will set @error as in 3.3.11.0
    Template_COMErrorRegister()
    $oShell.InvalidFunction()
    If @error Then MsgBox(4096, "COM Error Detected", @error)
    Template_COMErrorUnregister()

    ; This will fatal error, the 2nd line will not be reached.
    $oShell.InvalidFunction()
    If @error Then MsgBox(4096, "COM Error Detected", @error)

    Func Template_COMErrorRegister()
        $__g_oTemplateCOMErrorHandler = ObjEvent("AutoIt.Error", "Template_COMErrFunc")
    EndFunc   ;==>Template_COMErrorRegister

    Func Template_COMErrorUnregister()
        $__g_oTemplateCOMErrorHandler = 0
    EndFunc   ;==>Template_COMErrorUnregister

    Func Template_COMErrFunc()
        ; Do nothing special, just check @error after suspect functions.
    EndFunc   ;==>Template_COMErrFunc