FAQ 34.26 How does Automation work?

The IDispatch interface is what makes Automation work.

The IDispatch interface is a regular COM interface and is declared as follows.

 interface IDispatch : public IUnknown { public:     virtual HRESULT GetTypeInfo(....) = 0;     virtual HRESULT GetTypeInfoCount(....) = 0;     virtual HRESULT GetIDsOfNames(....) = 0;     virtual HRESULT Invoke(         /* [in] */ DISPID dispIdMember,         /* [in] */ REFIID riid,         /* [in] */ LCID lcid,         /* [in] */ WORD wFlags,         /* [out][in] */ DISPPARAMS *pDispParams,         /* [out] */ VARIANT *pVarResult,         /* [out] */ EXCEPINFO *pExcepInfo,         /* [out] */ UINT *puArgErr) = 0; }; 

When a caller wants to call a dispatch method defined by an Automation server, it first calls the server's implementation of IDispatch::GetIDsOfNames, supplying it with the string name of the dispatch method it wants to call. The result returned by GetIDsOfNames is the Dispatch Identifier (DISPID) for that dispatch method. The caller then calls the dispatch method by calling IDispatch::Invoke, supplying it with the DISPID for the dispatch method, the type of each parameter, and the values of each parameter. The implementation of IDispatch::Invoke performs a table lookup using the DISPID and executes the dispatch method.

When a caller wants to access a dispatch property, it first calls the server's implementation of IDispatch::GetIDsOfNames, supplying it with the string name of the dispatch property it wants to access. The result returned by GetIDsOfNames is the DISPID for that dispatch property. The caller then calls IDispatch::Invoke and supplies it with a flag indicating whether it wants to get the value of the dispatch property or set a new value for the dispatch property. The implementation of IDispatch::Invoke performs a table lookup using the DISPID and accesses the corresponding dispatch property.

Once a caller obtains a DISPID for a particular dispatch method (or property), it can cache it and use it repeatedly for calling the same method (or accessing the same property) without having to bother calling GetIDsOfNames again for that dispatch method (or dispatch property).

The good news is that most callers never call Invoke directly (the calls to Invoke are usually hidden behind a layer of abstraction). In the case of environments like Visual Basic, the Visual Basic syntax hides all the interactions with IDispatch. In the case of programming languages like C++, the development environment should automatically generate "automation proxy classes" that hide all the interactions with IDispatch. If your development environment cannot automatically generate automation proxy classes, you can always build them yourself.