Dispatch Class

By far the most common way to access COM object from within Carapace is via this Dispatch class.

Dispatch Creation

The following creates a Dispatch interface onto Microsoft's browser:

    (create Dispatch "InternetExplorer.Application")

    (create Dispatch "{0002DF01-0000-0000-C000-000000000046}")

An optional third String argument the machine name for remote execution e.g.

    (create Dispatch "InternetExplorer.Application" "RemoteServer" "myserver.com")

Dispatch Properties

The actual properties depend on the particular dispatch interface you are using. For example, the default dispatch interface for InternetExplorer is IWebBrowser2 and this has many properties, a few of which are:

Once you have the Dispatch interface, you access the properties using the dot operator eg.

    (global (::browser Dispatch))
    (set ::browser (create Dispatch "InternetExplorer.Application"))
    
    # make it visible - ie. set the 'Visible' property
    #
    # This is a boolean property, so set with the Symbol
    # true or false
    #
    (::browser.Visible (quote true))

    # set the width to 400 pixels
    (::browser.Width 400)

    # print the height
    (print "Height is" ::browser.Height)

Dispatch Methods

The actual methods depend on the particular dispatch interface you are using. For example, the default dispatch interface for InternetExplorer is IWebBrowser2 and this has many methods, a few of which are:

Once you have the Dispatch interface, you access the properties using the dot operator eg.

    (global (::browser Dispatch))
    (set ::browser (create Dispatch "InternetExplorer.Application"))
    
    # navigate to a file
    (::browser.Navigate "file://carapace.htm")

    # refresh this page
    (::browser.Refresh)

    # quit the browser
    (::browser.Quit)

If the COM server has an error, this gets translated to an Error object of class 9 (COM) being thrown within the Carapace script.

For example, if we now try to use the browser after a Quit the following error is thrown:

    (::browser.Visible (quote true))
    Error: [9.264] COM error: [1:1:264] GetIDsOfNames failed for 'visible' (The 
    object invoked has disconnected from its clients.  )