FAQ 34.25 When should a class expose a Dispatch interface?

When its callers say so.

The most obvious reason for implementing dispatch interfaces is that certain tools (such as VBScript, JScript, and older versions of Visual Basic) can interact with COM objects only through dispatch interfaces. Furthermore, ActiveX Controls (see FAQ 34.33) are required to expose their properties and methods through dispatch interfaces.

Dispatch interfaces define both dispatch methods and dispatch properties. Because COM interfaces can define only COM methods and dispatch interfaces are implemented using the IDispatch interface, dispatch properties are "virtual properties": they are manipulated indirectly by calling the methods of the IDispatch interface (see FAQ 34.27). Note that the programming language used by the caller may make it appear as if the property is being manipulated directly, but underneath it is still using COM methods. This illustrates, once again, that dispatch interfaces are at a higher level of abstraction than vtable interfaces and that Automation is a protocol that is implemented in terms of COM.

Dispatch interfaces can be declared using IDL. Here is the Microsoft IDL definition of the IStack dispatch interface.

 [ uuid(FC3B3F51-BCED-11D1-91FE-E1CBED988F66) ] library StackLib {     importlib("stdole32.tlb");     [ uuid(FC3B3F31-BCEC-11D1-91FE-E1CBED988F66) ]     dispinterface IStack     {         properties:             [id(1), propget] boolean Empty;         methods:             [id(2)] void Push(long value);             [id(3)] long Pop();     }; }; 

The dispinterface statement is used to create type information for a dispatch interface. For this reason, dispatch interfaces must be declared inside library declarations. Dispatch interfaces, like all other COM interfaces, must have an IID, and it is declared using the [uuid] attribute.

Dispatch interfaces are derived from IDispatch (the dispinterface statement implicitly derives the interface from IDispatch). The declarations for the IDispatch interface are loaded from the Automation type library using the statement importlib("stdole32.tlb");.

The dispinterface statement has two sections; one for declaring properties and one for declaring methods. Each property must have an Automation-compatible type (see FAQ 34.32). The types of the parameters and return value for each method must also be Automation-compatible. Every method and property has a DISPID, which is assigned using the [id] attribute.

You may have noticed that the syntax for the dispinterface statement is unlike other IDL statements. This is because the dispinterface statement was originally part of an earlier tool called the Object Definition Language (ODL), which has been merged into Microsoft IDL.

Dispatch interfaces use Type Library Marshaling (see FAQ 34.29) using the built-in Automation Marshaler; therefore the MIDL compiler does not need to generate proxy/stub code.

The best way for COM classes to expose dispatch interfaces is as dual interfaces. As discussed in FAQ 34.31, this allows a COM class to have its cake and eat it, too.