dispinterface
A version of this page is also available for
4/8/2010
This statement defines a set of properties and methods on which IDispatch::Invoke can be called. A dispinterface can be defined by explicitly listing the set of supported methods and properties (Syntax 1) or by listing a single interface (Syntax 2).
Syntax
[attributes]
dispinterface intfname {
properties:
proplist
methods:
methlist
};
Syntax
[attributes]
dispinterface intfname {
interface interfacename
};
Elements
- attributes
The helpstring, helpcontext, hidden, uuid, and version attributes are accepted before dispinterface. Attributes (including the brackets) can be omitted, except for the uuid attribute, which is required.
- intfname
The name by which the dispinterface is known in the type library. This name must be unique within the type library.
- interfacename
(Syntax 2) The name of the interface to declare as an IDispatch interface.
- proplist
(Syntax 1) An optional list of properties supported by the object, declared in the form of variables. This is the short form for declaring the property functions in the methods list. See the comments section for details.
methlist
(Syntax 1) A list comprising a function prototype for each method and property in the dispinterface. Any number of function definitions can appear in methlist. A function in methlist has the following form:[ attributes ] returntype methname**(params)**;
The following attributes are accepted on a method in a dispinterface:
- helpstring
- helpcontext
- string (for compatibility with the Interface Definition Language)
- bindable
- defaultbind
- displaybind
- propget
- propput
- propputref
- vararg
If vararg is specified, the last parameter must be a safe array of VARIANT type.
The parameter list is a comma-delimited list, each element of which has the following form:
[ attributes ] type paramname
The type can be any declared or built-in type, or a pointer to any type. Attributes on parameters are in, out, optional, and string.
If optional is specified, it must only be specified on the right-most parameters, and the types of those parameters must be VARIANT.
Remarks
Method functions are specified exactly as described in a module statement except that the entry attribute is not allowed.
Stdole2.tlb must be imported, because a dispinterface inherits from IDispatch.
Properties can be declared either in the properties or methods lists. Declaring properties in the properties list does not indicate the type of access the property supports (get, put, or putref).
Specify the readonly attribute for properties that do not support put or putref.
If the property functions are declared in the methods list, functions for one property will all have the same ID.
Using Syntax 1, the properties: and methods: tags are required. The id attribute is also required on each member. For example:
properties:
[id(0)] int Value; // Default property.
methods:
[id(1)] void Show();
Unlike interface members, dispinterface members cannot use the retval attribute to return a value in addition to an HRESULT error code. The lcid attribute is also invalid for dispinterfaces because Invoke passes a locale ID (LCID). However, it is possible to declare an interface again that uses these attributes.
Using Syntax 2, interfaces that support IDispatch and are declared earlier in an Object Definition Language (ODL) script can be redeclared as IDispatch interfaces as follows.
dispinterface helloPro {
interface hello;
};
This example declares all of the members of the Hello sample and all of the members that it inherits to support IDispatch.
In this case, if Hello was declared earlier with lcid and retval members that returned HRESULTs, MkTypLib would remove each lcid parameter and HRESULT return type, and instead mark the return type as that of the base type of the retval parameter.
The properties and methods of a dispinterface are not part of the VTBL of the dispinterface. Consequently, CreateStdDispatch and DispInvoke cannot be used to implement Invoke.
The dispinterface is used when an application needs to expose existing non-VTBL functions through Automation. These applications can implement Invoke by examining the dispidMember parameter and directly calling the corresponding function.
Example
[uuid(BFB73347-822A-1068-8849-00DD011087E8), version(1.0), helpstring("Useful help string."), helpcontext(2480)]
dispinterface MyDispatchObject {
properties:
[id(1)] int x; // An integer property named x.
[id(2)] BSTR y; // A string property named y.
methods:
[id(3)] void show(); // No arguments, no result.
[id(11)] int computeit(int inarg, double *outarg);
};
[uuid 00000000-0000-0000-0000-123456789012]
dispinterface MyObject
{
properties:
methods:
[id(1), propget, bindable, defaultbind, displaybind]
long x();
[id(1), propput, bindable, defaultbind, displaybind]
void x(long rhs);
}