4.12 The OLE-AUTOMATION module

create-dispatch

Function

Summary

Invokes or connects to an Automation server, as specified by its COM Class ID.

Signature

create-dispatch class-ID #key context interface-ID => 
                disp-interface

Arguments

class-ID: An instance of <string> or <REFGUID>.
context: An instance of <integer>. Default value: $CLSCTX-ALL.
interface-ID: An instance of <REFCLSID> or <string>. See Description.

Values

disp-interface: An instance of <LPDISPATCH>.

Description

Invokes or connects to an Automation server, as specified by its COM class-ID. This is a function for use by Automation controllers.

Normally, this function returns the server's primary dispinterface, but you can use the interface-ID option to select a specific interface.

You should call Release on the returned interface when finished using it.

The class-id argument and interface-ID option may be either an instance of <REFCLSID> (such as returned by make-GUID) or a string of 32 hexadecimal digits in the following format

  "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"

That is, where each x is a hexadecimal digit. For example:

  "{e90f09e0-43db-11d0-8a04-02070119f639}"

The context option takes one of the following values, constraining which implementation of the server to use:

$CLSCTX-INPROC-SERVER

An in-process server (DLL running in the container's process).

$CLSCTX-LOCAL-SERVER

A server running in its own process (EXE file).

$CLSCTX-REMOTE-SERVER

Server running on a remote machine.

$CLSCTX-SERVER

Any of the above.

$CLSCTX-INPROC-HANDLER

An in-process handler.

$CLSCTX-ALL

Any of the above. This is the default value.

If the Class ID is not found in the Windows registry, or there is no server that matches the requested context, the function will signal an <ole-error>, with status code of $REGDB-E-CLASSNOTREG.

If an interface matching the interface-ID is not found, the function will signal an <ole-error> with status code $E-NOINTERFACE.