async_uuid attribute

The [async_uuid] interface attribute directs the MIDL compiler to define both synchronous and asynchronous versions of a COM interface.

[ 
    object, 
    uuid(string-uuid1), 
    async_uuid(string-uuid2)[ [, interface-attribute-list] 
]
interface interface-name : base-interface
{
    interface-definition
}

Parameters

string-uuid1

A UUID string, generated by the Uuidgen utility, which identifies the synchronous version of the interface.

string-uuid2

A UUID string, generated by the Uuidgen utility, which identifies the asynchronous version of the interface.

interface-attribute-list

Other attributes that apply to the interface as a whole. You cannot use the [version] attribute in a COM interface.

interface-name

The name of the interface.

base-interface

The interface from which this interface derives. The base interface must be IUnknown or an asynchronous interface that derives, either directly or indirectly, from IUnknown.

interface-definition

Specifies IDL statements that form the definition of the interface.

Remarks

The use of this attribute requires Windows 2000 or later versions of Windows.

When you apply the [async_uuid] attribute to a COM interface (that is, an interface that has the [object] attribute), the MIDL compiler generates an asynchronous definition of the interface, in addition to the traditional, synchronous version. The asynchronous interface will have the same names as the synchronous interface, but with an "Async" prefix. The interface identifier (IID) will be the UUID specified as a parameter to the [async_uuid] attribute.

For the asynchronous interface, MIDL splits each method into separate begin and finish methods. The begin method has the synchronous method name with a "Begin_" prefix and includes all of the [in] parameters from the synchronous method. The finish method has the synchronous method's name with a "Finish_" prefix and includes all of the [out] parameters from the synchronous method. If the synchronous method has any [in, out] parameters they will be included in both the begin and finish asynchronous methods.

If an asynchronous interface method has the [call_as] attribute, MIDL will generate declarations for the begin and the finish methods. You must implement both methods.

Each asynchronous interface is a modifier on a synchronous interface and, as such, does not have a separate inheritance graph. This means that you cannot define a synchronous interface from an asynchronous interface (other than IUnknown). Nor can synchronous interfaces inherit from asynchronous interfaces. The MIDL compiler will issue an error message if you attempt either one.

Examples

[
    object, 
    uuid(0c733a30-2a1c-11ce-ade5-00aa0044773d),
    async_uuid(1c733a30-2a1c-11ce-ade5-00aa0044773d),
    pointer_default(unique)
]
interface IMyInterface : IUnknown
{
    /* Interface definition goes here*/
}

See also

Defining COM Interfaces

Interface Definition (IDL) File

call_as

iid_is

in

local

object

out

version