IDispatch

IDispatch is the interface that exposes the OLE Automation protocol. It is one of the standard interfaces that can be exposed by COM objects. The I in "IDispatch" refers to interface. COM distinguishes between three interface types: "custom", "dispatch" and "dual" interfaces.

IDispatch derives from IUnknown and extends its set of three methods ("AddRef", "Release" and "QueryInterface") with an additional four methods – "GetTypeInfoCount", "GetTypeInfo", "GetIDsOfNames" and "Invoke".

The Automation (IDispatch) interface allows a client application to find out what properties and methods are supported by an object at run-time. It also provides the information necessary to invoke these properties and methods. Client applications do not need to be aware of the object members when they are compiled. This allows COM and ActiveX objects to be called by scripting programs platforms such as the ASP server and JavaScript on Internet Explorer, where calling conventions are not known at the time IIS or IE were built. By contrast, a simple object library is compiled and linked into a program, while a DLL call also needs to know a function name and parameters at compile time.

Each property and method implemented by an object that supports the IDispatch interface has what is called a Dispatch ID, which is often abbreviated DISPID. The DISPID is the primary means of identifying a property or method and must be supplied to the "Invoke" function for a property or method to be invoked, along with an array of Variants containing the parameters. The "GetIDsOfNames" function can be used to get the appropriate DISPID from a property or method name that is in string format.

A script writer can ask the COM object for a method or property it already knows about from documentation. Then, the client can execute the function with Invoke provided by the IDispatch interface, a form of late-binding. This sort of capability was also supported by Dynamic Data Exchange (DDE), which never became popular due to being too low-level.

It is flexible, but suffers from the overhead of checking validity of method and parameters at run time.

interface IDispatch : public IUnknown { virtual ULONG GetTypeInfoCount(unsigned int FAR* pctinfo) = 0; virtual HRESULT GetTypeInfo(unsigned int iTInfo, LCID lcid, ITypeInfo FAR* FAR* ppTInfo ) = 0; virtual ULONG GetIDsOfNames(REFIID riid, OLECHAR FAR* FAR* rgszNames, unsigned int cNames, LCID lcid, DISPID FAR* rgDispId ) = 0; virtual ULONG Invoke(DISPID dispIdMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS FAR* pDispParams, VARIANT FAR* pVarResult, EXCEPINFO FAR* pExcepInfo, unsigned int FAR* puArgErr ) = 0; };The IDispatch interface ID is {00020400-0000-0000-C000-000000000046}.

External links

* [http://msdn2.microsoft.com/en-us/library/ms221608.aspx IDispatch at MSDN]
* [http://disphelper.sourceforge.net/ DispHelper] , an open-source library to help using a IDispatch from C or C++.