Sinking COM Events in APG Scripts

Connecting to Event Handlers

Both Script.CreateObject() and Script.ConnectEvents() can be used to connect an object to script event handlers. Both functions take a strHandlerPrefix argument, which specifies the prefix used in the script event handlers. That is, script functions named strHandlerPrefix + EventName are called when the object fires events.

For example, if strHandlerPrefix is "Conn_" and the object fires an event named "ConnectComplete", APGen calls a function in the script named "Conn_ConnectComplete" if one can be found.

<%#

' ConnectComplete event handler
Sub Conn_ConnectComplete(oError, adStatus, pConnection)
    ...
End Sub

' Disconnect event handler
Sub Conn_Disconnect(adStatus, pConnection)
    ...
End Sub

' Handle events for this Connection object
Dim conn
Set conn = Script.CreateObject("ADODB.Connection", "Conn_")
conn.Open"Provider=SQLOLEDB;Server=(local);Initial Catalog=Pubs;User ID=sa;"

'...

#%>

Script.ConnectEvents() only works for objects that implement the IProvideClassInfo or IProvideClassInfo2 interfaces. If you receive the run-time error:

Object is not connectable because TypeInfo for the default event interface could not be obtained.

it means the object does not implement IProvideClassInfo(2), and Script.ConnectEvents() can not be used with this object. In such cases, try using Script.CreateObject() to connect script event handling for the object - Script.CreateObject() does not require the IProvideClassInfo(2) interface, and is able to connect to more objects than Script.ConnectEvents() can.

Disconnecting Event Handlers

Script event handling for an object can be disabled by calling Script.DisconnectEvents() and passing in the object:

Script.DisconnectEvents conn

In-Process Components vs. Out-of-Process Components

When connecting to an in-process COM component (a DLL), script event handlers are called while an object method is being executed. This example uses the ADODB.Connection component, which is an in-process component. The Conn_ConnectComplete event handler is called before the conn.Open() method returns. In-process components can only call event handlers while executing one of the component's methods.

<%#

' ConnectComplete event handler
Sub Conn_ConnectComplete(oError, adStatus, pConnection)
...
End Sub

' Handle events for this Connection object
Dim conn
Set conn = Script.CreateObject("ADODB.Connection", "Conn_")

' The "ConnectComplete" event is called before conn.Open returns
conn.Open"Provider=SQLOLEDB;Server=(local);Initial Catalog=Pubs;User ID=sa;"

'...

#%>

When connecting to an out-of-process COM component (an EXE), script event handlers are called asynchronously. For out-of-process components, use Script.Wait() to pause execution and let the event handlers be called.

Example

This example uses the "InternetExplorer.Application" component, which is an out-of-process COM component. This component fires a number of COM events, including DocumentComplete and OnQuit. Script.Wait() is used to pause script execution while waiting for events. Script.Waiting and Script.StopWait() are used inside the event handlers to enable the script to continue executing.

<%# Option Explicit #%>
<%#
' ------------------------------------------------------------------------
' run_IE.apg
'
' Grabs web files using IE, saves them locally
' ------------------------------------------------------------------------

' This array contains the web pages to grab, and the files to save them as
Dim rgURLs
rgURLs = Array("http://msdn.microsoft.com/default.asp", "msdn.htm", _
                "www.webgecko.com", "webgecko.htm", _
                "www.yahoo.com", "yahoo.htm")

Sub IE_DocumentComplete(objIE, sURL)
     ' Write the doc's contents to the local file
     Output.Path = g_sLocalPage
     Output.Write(objIE.document.documentElement.outerHTML)
     Output.Close

     ' If waiting, stop the wait so execution can continue
     If (Script.Waiting) Then
          ' Stop the wait
          Script.StopWait()
     End If
End Sub


Sub IE_OnQuit()
     Script.DisconnectEvents(oIE)

     ' If waiting, stop the wait so execution can continue
     If (Script.Waiting) Then
          ' Stop the wait
          Script.StopWait()
     End If

     ' Abort script execution
     Script.Abort()
End Sub


' Global Internet Explorer object
Dim oIE
Set oIE = Script.CreateObject("InternetExplorer.Application", "IE_")
oIE.Visible = true

' Global path for the current page
Dim g_sLocalPage

' Walk through all the docs, saving each
Sub Main()
    stop

    ' How many elts in the array?
    Dim nPages
    nPages = (UBound(rgURLs) + 1)/2

    ' Loop through all the pages
    Dim i
    For i = 0 to nPages-1

        ' Extract the URL and filename
        Dim sURL
        sURL = rgURLs(i*2)
        g_sLocalPage =  Script.Dir & rgURLs(i*2 + 1)

        ' Tell IE to go to the URL
        oIE.Navigate(sURL)

        ' Wait until Script.StopWait() is called
        ' This occurs after the doc is loaded.
        Script.Wait()
    Next

End Sub

#%>