dispinterface attribute

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).

[
    [attributes]
]
dispinterface dispinterface-name
{
    properties:
        property-list
    methods:
        method-list
};

[
  [attributes]
]
dispinterface dispinterface-name
{
    interface interface-name
};

Parameters

attributes

Specifies attributes that apply to the entire dispinterface. The following attributes are accepted: [helpstring], [helpcontext], [helpfile], [hidden], [nonextensible], [oleautomation], [restricted], [uuid], and [version].

dispinterface-name

The name by which the dispinterface is known in the type library. This name must be unique within the type library.

property-list

(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.

method-list

(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 type paramname (params);

The following attributes are accepted on a method in a dispinterface: [helpstring], [helpcontext], [propget], [propput], [propputref], [string], 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]

The type can be any declared or built-in type, or a pointer to any type. Attributes on parameters are:

[in], [out], [optional], [string]

interface-name

(Syntax 2) The name of the interface to declare as an IDispatch interface.

Remarks

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

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 identifier.

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 Automation. These applications can implement IDispatch::Invoke by examining the dispidMember parameter and directly calling the corresponding function.

Examples

[ 
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676), 
    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(1e123456-1f3c-1069-996b-00dd010fe676)
] 
dispinterface MyObject 
{ 
    properties: 
    methods: 
        [id(1), propget, bindable, defaultbind, displaybind] long x(); 
 
        [id(1), propput, bindable, defaultbind, 
         displaybind] HRESULT x(long rhs); 
}

See also

bindable

defaultbind

displaybind

helpcontext

helpfile

helpstring

hidden

in

interface

TYPEFLAGS

ODL File Syntax

ODL File Example

Generating a Type Library With MIDL

optional

out

nonextensible

propget

propput

propputref

oleautomation

restricted

string

uuid

vararg

version