Basics of an IDL file

Introduction

MIDL (Microsoft Interface Definition Language) is used for describing COM objects. A file that contains interface and type library definitions is called an IDL file, and has a .idl file name extension.

The Interface Definition Language (IDL) is not a programming language, but a descriptive language to describe the interfaces being implemented by objects. IDL files are similar to C++ header files.

Contents of an IDL file

In any IDL file, there can be one or more interface definitions defined as part of a module. Each interface definition is composed of an interface header and an interface body. The IDL interface header specifies information about the interface as a whole.

The IDL interface body contains data types used in remote procedure calls and the function prototypes for the remote procedures. The interface body can also contain imports, pragmas, constant declarations, and type declarations. (Each interface body may contain methods, properties, variables/constants, enums etc. In other words, everything which needs to be exposed from the interface will be there in the IDL file.)

Structure of an IDL file

[ //header

  //Interface attributes go here.

]
interface INTERFACENAME //body

{
//The interface body goes here.

}
library TyeLibraryFileName
{
  //Type library Information

}

Interface header example

[
    object,
    uuid(C0E20128-DB19-4DB3-BCA1-24595E5E24A8),
    dual,
    nonextensible,
    helpstring("IConfig Interface"),
    pointer_default(unique)
]

An iInterface header contains attributes that are platform-independent. Attributes in the interface header are global to the entire interface. These attributes are enclosed in square brackets at the beginning of the interface definition. Each attribute has its own meaning:

• Object: This indicates that it is a COM interface.
• Uuid: Represents a universally unique identifier (UUID) that is assigned to the interface and that distinguishes it from other interfaces. Each interface, class, and type library must be identified with its own unique identifier.
• Dual: The dual attribute identifies an interface that exposes properties and methods through IDispatch and VTBL.
• Nonextensible: This specifies that the IDispatch implementation includes only the properties and methods listed in the interface description, and that it cannot be extended with additional members at runtime.
• Helpstring: A character string that is used to describe the element to which it applies.
• Pointer_default: Specifies the default pointer attribute for all pointers except the top-level pointers that appear in the parameter lists.

For more information: MSDN.

Interface body example

interface ILogManager : IDispatch
{
    [id(1), helpstring("Initializes ILogManager")] HRESULT Initialize([in] IConfig* Config);

    [id(2), helpstring("Logs MemberClaims")] HRESULT LogMemberClaims([in] IMember* Member);

    [id(3), helpstring("Logs ILogData to specified destination")] 
            HRESULT Log([in] ILogData* LogData);

};

• ILogManager – The interface name.
• IDispatch – The COM base class.
• Id(1) – The unique ID of the method.
• Helpstring - The character string which describes this method.
• HRESULT – Returns the error code.
• Initialize – Method name.
• In – Specifies the parameter to be passed from the calling procedure to the called procedure.
• Out - The parameter that specifies data that is passed back to the caller. Using both directional attributes on one parameter specifies that the parameter is used both to send data to the method and to pass data back to the caller.

Type library

A type library is an essential part of a component, providing information to the compiler about the classes, interfaces, enumerations, and so on, included in the component. Type library files have the extension .tlb.

Example of a type library

library MyTypeLibraryFileLib
{
 [
  uuid(B3F6C9C4-26AE-451B-9788-75F6C648DBF4),
  helpstring("LogManager Class")
 ]
 coclass LogManager
 {
  [default] interface ILogManager;
 }; 
}

The library statement defines the MyTypeLibraryFileLib type library, which has its own uuid, helpstring, and version attributes. The coclass statement defines an entirely new component class, LogManager, that includes a previously defined interface, ILogManager.

MIDL compiler

An MIDL compiler processes the IDL file and creates a type library, a header, and proxy files.

A type library is a binary file that describes the COM object or COM interfaces, or both.

Creating a TLB file from an IDL file

Save the IDL file and then use the MIDL compiler to generate the TLB file. From the command line, enter:

midl myfilectl.idl /tlb myfilectl.tlb

The "/h" switch will produce a C/C++ header file as well.

History

• Version 1.0 - created on 07-15-2007.