IDispatch
Encyclopedia
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 were 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 Variant
s 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}.
Interface (computer science)
In the field of computer science, an interface is a tool and concept that refers to a point of interaction between components, and is applicable at the level of both hardware and software...
that exposes the OLE Automation
OLE Automation
In Microsoft Windows applications programming, OLE Automation , is an inter-process communication mechanism based on Component Object Model that was intended for use by scripting languages – originally Visual Basic – but now are used by languages run on Windows...
protocol. It is one of the standard interfaces that can be exposed by COM
Component Object Model
Component Object Model is a binary-interface standard for software componentry introduced by Microsoft in 1993. It is used to enable interprocess communication and dynamic object creation in a large range of programming languages...
objects. The I in IDispatch refers to interface. COM distinguishes between three interface types: custom, dispatch and dual interfaces.
IDispatch derives from IUnknown
IUnknown
In programming, the IUnknown interface is the fundamental interface in the Component Object Model . The published mandates that COM objects must minimally implement this interface...
and extends its set of three methods
Method (computer science)
In object-oriented programming, a method is a subroutine associated with a class. Methods define the behavior to be exhibited by instances of the associated class at program run time...
(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
Active Server Pages
Active Server Pages , also known as Classic ASP or ASP Classic, was Microsoft's first server-side script engine for dynamically-generated Web pages. Initially released as an add-on to Internet Information Services via the Windows NT 4.0 Option Pack Active Server Pages (ASP), also known as Classic...
server and JavaScript
JavaScript
JavaScript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. It is a multi-paradigm language, supporting object-oriented, imperative, and functional programming styles....
on Internet Explorer
Internet Explorer
Windows Internet Explorer is a series of graphical web browsers developed by Microsoft and included as part of the Microsoft Windows line of operating systems, starting in 1995. It was first released as part of the add-on package Plus! for Windows 95 that year...
, where calling conventions were not known at the time IIS
Internet Information Services
Internet Information Services – formerly called Internet Information Server – is a web server application and set of feature extension modules created by Microsoft for use with Microsoft Windows. It is the most used web server after Apache HTTP Server. IIS 7.5 supports HTTP, HTTPS,...
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 Variant
Variant type
Variant is a data type in certain programming languages, particularly Visual Basic and C++ when using the Component Object Model.In Visual Basic the Variant data type is a tagged union that can be used to represent any other data type except fixed-length string type and...
s containing the parameters. The GetIDsOfNames function can be used to get the appropriate DISPID from a property or method name that is in string
String (computer science)
In formal languages, which are used in mathematical logic and theoretical computer science, a string is a finite sequence of symbols that are chosen from a set or alphabet....
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
Late binding
Late binding is a computer programming mechanism in which the method being called upon an object is looked up by name at runtime. This is informally known as duck typing or name binding....
. This sort of capability was also supported by Dynamic Data Exchange
Dynamic Data Exchange
Dynamic Data Exchange is a technology for interprocess communication under Microsoft Windows or OS/2.- Overview :Dynamic Data Exchange was first introduced in 1987 with the release of Windows 2.0 as a method of interprocess communication so that one program can communicate with or control another...
(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
- IDispatch at MSDN
- DispHelper, an open-source library to help using an IDispatch from C or C++.
- IDispatchCodeGenerator, Code generator. Feature that adds IDispatch to an object. Language is C++.