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)] HRESULT 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] 
        HRESULT 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)] HRESULT 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, CreateStdDispatch 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

interface, TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL