Structure

Summary

• Purpose
• IDL Structure
• Building a Proxy/Stub DLL
• Interface Definitions, Type Libraries, and oleautomation attribute
• Local Attribute
• Importing Other Files
• Importing Files in the Library Block
• CoClasses
• Sample IDL Structure

PURPOSE

IDL files serve two (and only two) purposes only:

1. Providing marshalling information to the COM remoting layer.
2. Providing information about component capabilities for development tools and COM+ runtime.

IDL STRUCTURE

OVERALL STRUCTURE

An IDL file is typically divided into two parts:

1. Definitions inside the library block.
2. Definitions outside the library block.

INSIDE LIBRARY BLOCK

• If a library block is present in the IDL file, the MIDL compiler will generate a type  library file, <IDL file name>.tlb. 
  
• All interfaces defined inside the library block should have the [oleautomation] attribute, which tells COM runtime to use the Universal Marshaler when marshalling  instances of this interface (note that this implies that the interface supports only  automation-compatible data types). If [oleautomation] was not defined then  COM runtime will not know how to marshal the interface. 
  
• In general, the generated type library should be registered. Stand alone type libraries can be registered with regtlib.exe, while type libraries embedded within DLLs (as  in ATL) are automatically registered. Type libraries with oleautomation interfaces  then serve the full purpose of an IDL file by 1) providing marshalling information for  the Universal Marshaler, and 2) providing information about component capabilities  for COM development tools like Visual Basic 
  
• The only attribute that a library block requires is the [uuid]. Typically, a library block should also have the [version (x.y)] attribute, where x is the major  version number and y is the minor version number. The version number allows for  multiple versions of the type library to coexist with each version having the same uuid but a different version number .

// IDL: library block requires only the uuid attribute

[
    uuid(A8A71511-D4B8-11D4-8053-00D0B79F36F8),
    version( 1.0 )
]
library AtomLib
{
    // Interfaces inside the library block should have [oleuatomation] (or [dual] for IDispatch interfaces)
    // attributes to enable the Universal Marshaler
    [
        uuid(51C3382C-D4D1-11d4-8053-00D0B79F36F8),
        oleautomation,
        ...
    ]
    interface IAtom : IUnknown
    {
        ...
    }
    ...
};

OUTSIDE LIBRARY BLOCK

Interfaces whose methods require data types that are not automation compatible  must be declared outside the library block and run with the /Oicf MIDL compiler  switch (in VC++, this equivalent to checking the stubl-ess Proxies check box in the  MIDL tab of Project Settings). Therefore, declare an interface outside the library block  only if its methods deal with non-automation compatible data types. This means that  proxy/stub DLL must be built and registered.

BUILDING A PROXY/STUB DLL

• MIDL generates all the required files for building interception code (proxy/stub DLL)  when compiling an MIDL with interfaces declared outside the library block.
  
• Once a proxy/stub DLL is built, it must be registered just like any COM object.  Whenever COM needs an interceptor (proxy/stub) for an interface, it consults  HEKY_CLASSES_ROOT\Interface using the IID of the interface as the key and  extracts the CLSID stored in ProxyStubClsid32 key. This is the CLSID of the  Proxy/Stub DLL.

INTERFACE DEFINITIONS, TYPE LIBRARIES, AND OLEAUTOMATION ATTRIBUTE

Interfaces declared outside the library block will not appear in the type library. No interface information will be available to development environments like VB. To force  an interface defined outside the library block to appear in the type library, add a  reference to it in the library section.

// IDL: Forcing an 'outside the library block' interface to appear in the type library

[ ... ]
interface INeutron : IUnknown
{
    ...
};

[ ... ]
library AtomLib
{
    ...
    interface INeutron;     // Reference to INeutron
    
    [
        oleautomation,
        ...
    ]
    interface IAtom : IUnknown
    {
        oleautomation,
        ...
    }
    ...
};

The following table summarizes interface location and interaction with oleautomation:

LOCAL ATTRIBUTE

• Some interfaces may never need interception code (Universal Marshaler or Proxy/Stub code) or may contain method signatures for which interception code  cannot be generated. In other words, the interface is non-remotable. Use the  [local] attribute to signify that no interception code is required. [local] is often  applied to interfaces used for private communication between two objects, provided of course, the two object are always in the same context.
• [oleautomation] overrides [local]. Therefore, an interface can contain one but not the other.
• [local] interfaces need not return HRESULT.

IMPORTING OTHER FILES

• A given interface definition may contain method signatures taking a variety of parameter types. Those parameter types must be available to the MIDL compiler to correctly compile the IDL file. When types are defined in an external file never use the  #include directive but use the import keyword. The import keyword may appear anywhere in the IDL file, including inside the library block (although not recommended – see Importing Files in the Library Block section)
  
• It is perfectly legal to use import keyword to import a particular IDL file more than once. This leads to the following usage pattern: Place import statements  immediately inside interface definitions that use the imported types. If the interface definition is moved to another file (the IDL may grow too large), the required imports  move with it automatically.
  

// IDL: using import within interface definitions

[ ... ]
interface INeutron : IUnknown
{
    import "atom.idl";
    HRESULT AddAtom( [in] IAtom* pAtom );
};

[ ... ]
interface IElectorn : IUnknown
{
    import "atom.idl";
    HRESULT AddAtom( [in] IAtom* pAtom );
};

• The resulting header file for any IDL file that uses the import statement will have a corresponding #include statement to bring in the appropriate header file when  building the proxy/stub DLL. However, avoid placing import statements in the library block; no corresponding #include statement appears in the generated header file.

IMPORTING FILES IN THE LIBRARY BLOCK

• Types referenced inside the library block will appear in the type library. This includes system types such as IUnknown which will result in duplication of information. Use importlib keyword to bring in an external type library. Therefore, inside a library block do no use import, instead use importlib.
  
• IUnknown is defined in stdole2.tlb and the first statement in the library block should import this type library. stdole32.tlb is an older version of stdole2.tlb.  Note that only the most recent type library is needed.
  
• importlib must come before any reference to types defined in the imported type library.

COCLASSES

• A coclass statement can appear inside or outside the library block. If it appears inside the library block, the type information for the coclass will appear in the type  library. 
  
• Inside the coclass, all interfaces that a specific class implements should be listed.
  
• The coclass is also used by MTS/COM+ to determine which interfaces to list in the catalogue. Interfaces that do not appear in coclass will still get interception code; it is only the interface and method level declarative attributes that will be unavailable.
  
• The [default] attribute on an interface in the coclass statement cause VB to hide the interface in the Object Browser and make the methods of that interface accessible through the class name. If the [default] attribute is not specified, MIDL will choose the first interface in the list.

SAMPLE IDL STRUCTURE

/****************************************************************** 
Structure of a model IDL file
******************************************************************/

// Use 'import' to bring in data types defined in external files
import "oaidl.idl";
import "ocidl.idl";


/*******************************************************************
Outside the library block. Interfaces will use Proxy/Stub DLL as 
long as /Oicf MIDL flag is defined. No type library information will 
be generated, unless the interface is referenced in the library block .
*******************************************************************/

[
    uuid(51C3382C-D4D1-11d4-8053-00D0B79F36F9),
    object,
    helpstring("Some meaningful description please"),
    pointer_default(unique)
]
interface INeutorn : IUnknown
{
    // Use 'import' to import externally-defined types used by this interface
    import "atom.idl"

    HRESULT AddAtom( [in] IAtom* pAtom );
};

[
    uuid(51C3382C-D4D1-11d4-8053-00D0B79F36FA),
    object,
    helpstring("Another meaningful description please"),
    pointer_default(unique)
]
interface IPositron : IUnknown
{
    // Use 'import' to import externally-defined types used by this interface
    import "atom.idl"

    HRESULT RemoveAtom( [in] IAtom* pAtom );
};


/**************************************************************************
Library block. MIDL will generate a .tlb file. If registered, IAtom will be 
marshaled with the Universal Marshaler. Development tools can also query for
capabilities of the component.

Recall that 'import' statements should not be placed in the library block
**************************************************************************/
[
    uuid(A8A71511-D4B8-11D4-8053-00D0B79F36F8),
    version (33.3)
]
library AtomLib
{
    // Importing stdole2.tlb should be the first statement in the library block. stdole32.tlb is an older 
    // version and should not really be added
    importlib( "stdole2.tlb" );

    // Force INeutron, a non-automation compatible, to appear in the type library to enable development tools 
    // like VB to get information on it
    interface INeutron;

    // Interfaces inside the library block should have [oleuatomation] or [dual] attributes (if IDispatch-derived) 
    // to use the Universal Marshaler
    [
        uuid(51C3382C-D4D1-11d4-8053-00D0B79F36F8),
        object,
        oleautomation,
        helpstring("Another meaningful description please"),
        pointer_default( unique )
    ]
    interface IAtom : IUnknown
    {
        HRESULT Explode( [out, retval] long *pTeraJoules );
    }

    // Always define a default interface for VB. If not defined, MIDL will make the first interface the default one.
    coclass Atom
    {
        [default] interface IAtom;
        interface INeutorn;
        interface IPositron;
    }
};