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 identifier must be unique or different from any type
names. It also must be 17 characters or less because it is used to form the
name of the interface handle. 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;
void 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.
See Also