IDL

[ interface-attribute-list ] interface interface-name
{
    [ import import-file-list ; ... ]
    [ cpp_quote("string") ... ]

    [ const const-type identifier = const-expression ; ... ]

    [ [ typedef ] [ [type-attribute-list] ] type-specifier declarator-list; ...]

    [    [ [function-attr-list] ] type-specifier [pointer-declarator] function-name(
            [ [parameter-attribute-list] ] type-specifier [declarator]
            , ...
        );
    ...
    ]
}

interface-attribute-list: Specifies either the attribute uuid or the attribute local and other optional attributes that apply to the interface as a whole. The attributes endpoint, version, and pointer_default are optional. When you compile with the /app_config switch, either implicit_handle or auto_handle can also be present. Separate multiple attributes with commas. The interface-attribute-list does not have to be present for imported IDL files, but must be present for the base IDL file.
interface-name: Specifies the name of the interface. The name cannot be that of any other identifier (for example a type name or another interface). The same interface name must be supplied in the ACF, except when you compile with the /acf switch.
import-file-list: Specifies one or more IDL files to import. Separate filenames with commas.
string: Specifies a string that is emitted in the generated header file.
const-type: Specifies the name of an integer, character, boolean, void *, byte, or string (char *, byte *, wchar_t *) type. Only these types can be assigned const values in the IDL file.
identifier: Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.
const-expression: Specifies a constant declaration. The const-expression must evaluate to the type specified by const-type. For more information, see const.
type-attribute-list: Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, ignore, and string. Separate multiple attributes with commas.
type-specifier: Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
declarator and declarator-list: Specify standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter declarator in the function declarator, such as the parameter name, is optional.
function-attr-list: Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.
pointer-declarator: Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C and is is constructed from the * designator, modifiers such as far and the qualifier const.
function-name: Specifies the name of the remote procedure.
parameter-attribute-list: Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Examples

[ uuid(12345678-1234-1234-1234-123456789ABC), 
  version(3.1), 
  pointer_default(unique) 
] interface IdlGrammarExample 
{ 
import "windows.idl", "other.idl"; 
const wchar_t * NAME = L"Example Program"; 
typedef char * PCHAR; 
 
HRESULT DictCheckSpelling( 
     [in, string] PCHAR   word,     // word to look up 
     [out]        short * isPresent // 0 if not present 
); 
}

Remarks

The IDL file contains the specification for the interface. The interface includes the set of data types and the set of functions to be executed from a remote location. Interfaces specify the function prototypes for remote functions and for many aspects of their behavior from the point of view of interface users.

Another file, the application configuration file (ACF), contains attributes that tailor the application for a specific operating environment. For more information, see ACF.

An interface specification consists of an interface header followed by an interface body. The interface header includes an attribute list describing characteristics that apply to the interface as a whole. The interface body contains the remote data types and function prototypes. The interface body also contains zero or more import lists, constant declarations, general declarations, and function declarators.

In Microsoft RPC, an IDL file can contain multiple interfaces and these interfaces can be forward declared (within the IDL file that defines them). For example:

interface ITwo; //forward declaration
interface IOne {
...uses ITwo...
}
interface ITwo {
...uses IOne...
}

Type definitions, construct declarations, and imports can occur outside of the interface body. All definitions from the main IDL file will appear in the generated header file, and all the procedures from all the interfaces in the main IDL file will generate stub routines. This enables applications that support multiple interfaces to merge IDL files into a single, combined IDL file.

As a result, it requires less time to compile the files and also allows MIDL to reduce redundancies in the generated stubs. This can significantly improve object interfaces through the ability to share common code for base interfaces and derived interfaces. For non-object interfaces, the procedure names must be unique across all the interfaces. For object interfaces, the procedure names only need to be unique within an interface. Note that multiple interfaces are not permitted when you use the /osf switch.

The syntax for declarative constructs in the IDL file is similar to that for C. MIDL supports all Microsoft C/C++ declarative constructs except:

Older style declarators that allow a declarator to be specified without a type specifier, such as:
```
x (y) 
short x (y) 
 
```
Declarations with initializers (MIDL only accepts declarations that conform to the MIDL const syntax).

The import keyword specifies the names of one or more IDL files to import. The import directive is similar to the C include directive, except that only data types are assimilated into the importing IDL file.

The constant declaration specifies boolean, integer, character, wide-character, string, and void * constants. For more information, see const.

A general declaration is similar to the C typedef statement with the addition of IDL type attributes. Except in /osf mode, the MIDL compiler also allows an implicit declaration in the form of a variable definition.

The function declarator is a special case of the general declaration. You can use IDL attributes to specify the behavior of the function return type and each of the parameters.

IDL

Examples

Remarks

See Also