dispinterface
[attributes]dispinterface intfname { properties:proplist methods: methlist};
[attributes]dispinterface intfname { interface interfacename};
attributes
Specifies
attributes that apply to the entire dispinterface. The following
attributes are accepted: helpstring, helpcontext, helpfile,
hidden, nonextensible, oleautomation, restricted,
uuid, version.
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, bindable, defaultbind, displaybind,
propget, propput, propputref, and 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, string
The MIDL
compiler accepts the following parameter ordering (from left-to-right):
1. Required parameters (parameters that do not
have the defaultvalue or optional attributes),
2. optional parameters with or without the defaultvalue
attribute,
3. parameters with the optional attribute and without the defaultvalue
attribute,
4. lcid parameter, if any,
5. retval parameter
Examples
[ uuid(. . .), 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(. . .)]
dispinterface MyObject
{
properties:
methods:
[id(1), propget, bindable, defaultbind, displaybind]
long
x();
[id(1), propput, bindable, defaultbind, displaybind]
void
x(long rhs);
}
Remarks
The dispinterface
statement defines a set of properties and methods on which you can call IDispatch::Invoke.
A dispinterface may be defined by explicitly listing the set of supported methods
and properties (Syntax 1), or by listing a single interface (Syntax 2).
Method
functions are specified exactly as described in the reference page for module except that the entry
attribute is not allowed. Note that STDOLE32.TLB (STDOLE.TLB on 16-bit systems)
must be imported, because a dispinterface inherits from IDispatch.
You can
declare properties in either the properties or methods lists. Declaring
properties in the properties list does not indicate the type of access the
property supports (that is, get, put, or putref). Specify the readonly
attribute for properties that don t support put or putref. If you declare the
property functions in the methods list, functions for one property all have the
same ID.
Using the
first syntax, 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 likewise invalid for dispinterfaces, because IDispatch::Invoke passes
an LCID. However, it is possible to redeclare an interface that uses these
attributes.
Using the
second syntax, interfaces that support IDispatch and are declared
earlier in an ODL script can be redeclared as IDispatch interfaces as
follows:
dispinterface helloPro {
interface
hello;
};
The preceding
example declares all the members of hello and all the members that hello inherits
as supporting IDispatch. In this case, if hello were 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 retval parameter.
The
properties and methods of a dispinterface are not part of the VTBL of the
dispinterface. Consequently, CreateStdDispatch17P1FKP and DispInvoke cannot be used to implement
IDispatch::Invoke. The dispinterface is used when an application needs
to expose existing non-VTBL functions through OLE Automation. These
applications can implement IDispatch::Invoke by examining the dispidMember
parameter and directly calling the corresponding function.
See Also