Associates a user-defined function or subroutine with a COM object event.
ObjectEventAdd( object-reference, event-name, UDF-name )
(i) object-reference variable containing an object reference
(s) event-name name of event to be handled
(s) UDF-name name of UDF/UDS event handler
(i) result 1 on success, 0 on failure
ObjectEventAdd binds a user-defined function or subroutine to a COM object event. COM object events are notifications sent to a script in response to some action or object state change. Events can even be fired in response to an action taken by your script. Once your event handling user-defined function or subroutine is bound to an event, the COM object calls your UDF/UDS whenever the event occurs.
For many events, your script must pause execution long enough to receive the event. You can pause your script by placing the TimeDelay function in a While or For loop. You can also use a WIL dialog, one of the built-in dialogs or one of the "wait" functions to pause script execution. If you do choose a TimeDelay or "wait" loop, remember to include logic for loop termination.
Note: While you can pause your script in a user-defined function or even a nested call to a user-defined function, a user-defined subroutine event handler's variable scope is always the outer most scope of the script. This means that variables created from within the "pausing" user-defined function are not available to event handling user-defined subroutine.
object-reference
The first parameter is a reference to the object whose event you wish to handle. The parameter must be a variable containing an object reference. Object references can be obtained by calling the ObjectCreate, ObjectGet, or DialogObject function.
event-name
This is the name associated with the event you wish to handle. Consult a COM object's documentation to find the names of events supported by an object.
UDF-name
The third parameter is the name of the User-defined function or subroutine that will handle the event. The UDF/UDS must be defined before you call the ObjectEventAdd function. The UDF/UDS definition must also contain the number of parameters specified for the event handler by the object's documentation. If the event supports "out" parameters, you can assign values to these parameter variables inside your handler and the values will be passed back to the COM object. Consult the object's documentation to determine if any of the parameters can return values to the object.
;This example uses the ObjectEventAdd function and a WMI event to monitor the
;Run registry key. The script uses the WaitForKeyEx function in a loop to
;pause while waiting for a registry change. Script processing completes when
;the key change event fires or the user presses the Esc key.
bNoEvent = @TRUE ; Initialize loop control variable
; WMI event OnObjectReady subroutine handler
#DefineSubRoutine OnObjectReady(objWbemObject, objWbemAsyncContext)
Message("Registry Key Change", objWbemObject.GetObjectText_())
bNoEvent = @FALSE ; Causes loop to exit
Return
#EndSubRoutine
; Need the WMI service and sink objects
objWmiServices = ObjectGet("winmgmts:root/default")
objWmiSink = ObjectCreate("WbemScripting.SWbemSink")
; Bind the event handler to the WMI event
ObjectEventAdd(objWmiSink, "OnObjectReady", "OnObjectReady")
; Create the WMI query to check for modifications to the Run key
sHive = "Hive='HKEY_LOCAL_MACHINE'"
sKey = "KeyPath='SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run'"
sQuery = "SELECT * FROM RegistryKeyChangeEvent"
sQuery = StrCat(sQuery, " WHERE ", sHive, " AND ", sKey)
; Start the registry monitor
objWmiServices.ExecNotificationQueryAsync( objWmiSink , sQuery)
; Loop until the registry changes
BoxOpen("Waiting for a registry key to change.", "Press ESC key to quit")
While bNoEvent
If WaitForKeyEX("{ESC}", 1) == 1
Break ; Esc key pressed
EndIf
EndWhile
BoxShut()
; Remove the event.
ObjectEventRemove(objWmiSink, "OnObjectReady")
; To be safe shut down the WMI event sink
objWmiSink.Cancel()
objWbemObject = 0
objWbemAsyncContext = 0
objWmiSink = 0
objWmiServices = 0
Exit