Creating type libraries using IDL

In this topic

About type libraries

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, although type libraries can also be embedded into other files, for example, object libraries (.olb) or DLLs. Throughout this section, the term type library may refer to either a .tlb file or to a library contained in another file.
ArcObjects object libraries
Type information for ArcObjects components is contained in a number of object libraries. Each area of ArcObjects functionality is contained in a different object library—for example, the ArcMap user interface classes, interfaces, and enumerations are defined in the esriArcMapUI.olb object library.

Why are type libraries necessary?

You need to reference a type library to declare variables or implement interfaces using the types defined in the library. The type library is then used when your component is compiled to check the type information to allow early binding of types.
Type libraries also allow type-dependent design-time features to function correctly, such as VB's intellisense and parameter information.

How are type libraries created?

When you create a component, type library information should be created too. The VB compiler automates the process of creating a type library, embedding type library information within your compiled DLL or EXE file.
If you are developing in VC++, however, you create Interface Definition Language (IDL) files to define the contents of the type library, which are compiled into a separate .tlb file when the project is compiled.

Why should I use IDL to create a type library?

Type libraries are aimed at allowing development to cross programming language boundaries. However, certain incompatibilities exist between the type library information that is created by default and that can be implemented by different development environments.
Although COM components are accessible from any language, a type library may be required to make the information contained in the component accessible to other developers.
Regardless of the environment you are using, you can ensure your type library is standardized by writing your type library information in IDL and compiling this into a type library.
You can create an external type library, regardless of the development environment you are using.
This could be necessary if you expect your component to be called by or implemented in other environments by other developers within or outside your development team. Multiple type libraries may also be used as an organizational tool to separate interfaces, structures, and enumerations from coclass definitions or to separate public from private information.
This section covers how you can create a type library by writing IDL, both for a VB and a VC++ project, and the reasons why you might decide to do this. It covers certain issues of writing IDL that can help you ensure your components can act as a server to a variety of development environments.
The instructions in this section include the use of the Microsoft Interface Definition Language (MIDL) compiler, and optionally the OLE COM Object Viewer utility (OLE View).

Viewing a type library

You can investigate the contents of a type library in many ways.
Type libraries can be viewed in many different ways, for example, the Microsoft OLE View utility, the ESRI Object Browser, and the developer help system.
The ESRI libraries are described in VC++, C#, and VB.NET syntax in the ArcObjects component help system.
The Microsoft OLE View utility can be used to view the contents of a type library and unpack the IDL code it contains. As well as .tlb files, this utility can view the type library information inside a DLL or EXE, an ActiveX control, or an object library file (.olb).
The ESRI Object Viewer can also be used to view the contents of type libraries in these files. The declarations can be viewed as IDL, as they would appear on an object diagram, or using VB syntax.
If you are a VB developer, you may be most familiar with the VB Object Browser, which shows a VB interpretation of a type library—for more information on what this implies, see the following section on defining interfaces in IDL.

About IDL files

IDL is a language that can be used to describe COM interfaces and other data types. Although based on the C language, it can only be used to define data types—it cannot be used to implement interfaces or create classes. For more information on IDL, see the bibliography. Essential IDL by Martin Gudgin may be particularly useful for programmers working in VB.
The basic 'unit' of IDL is composed of two parts. First, a section within square brackets contains attributes, which define things such as a Globally Unique IDentifier (GUID), a version number, helpstring, and help context ID number.
[
  uuid(764EDFE5-09A7-11D6-8A8E-00104BB6FCCB),
  version(1.0),   helpcontext(16),
  helpstring("DisplayCommands 1.0 Type Library")
]
This section is directly followed by a named entity to which these attributes apply. The section begins with the entity name, followed by a section within curly brackets, which defines the entity in detail.
library DISPLAYCOMMANDSLib
{
  importlib("stdole32.tlb");    // Import libraries containing
  importlib("stdole2.tlb");     // standard COM API calls.
  importlib("C:\Program Files\ArcGIS\Com\esriFramework.olb");
  [
    object,
    uuid(764EDFF1-09A7-11D6-8A8E-00104BB6FCCB),
    helpstring("IZoomIn Interface"),
    pointer_default(unique)
  ]
  interface IZoomIn : IUnknown
In the following pages, you can find more information about issues you may face when creating type libraries in VC++ and how you can create more language-independent type libraries for your components.

Creating a type library for a VC++ component

As a VC++ programmer you should already be familiar with the process of creating external type libraries by using IDL to define an interface and the MIDL compiler to compile the IDL to a type library file.
If you have experience with Active Template Library (ATL), you may have set MIDL compiler options via the Project Settings dialog box; although as IDL is integrated into the project environment, you may not have been specifically aware of using it.
The MIDL compiler is used by the VC++ environment to create a type library; the MIDL tab of the Project Settings dialog box is used to adjust MIDL compiler settings.
This section presents a brief review of the steps to turn IDL into a type library for your project.

Creating an IDL file

The basic creation and editing of an IDL file using the ATL COM AppWizard is described in Development Environments, COM, Visual C++ section of the developer help system.
In summary, there are two steps. First, create a new project using the ATL COM AppWizard. Then use the ATL Object Wizard to add objects to the project, choosing Simple Object as the template. The interface type you choose, dual or custom, will depend on the intended usage of the component—see the Coding Interfaces topic earlier in this section for more information. At this point, you have a project containing a basic IDL file defining a library.

Adding members to the IDL file

You can easily add interfaces and implement members on your new class by using the context menus on the Visual C++ ClassView. However, you should check the IDL file to make sure it matches what is defined in your C++ code. In particular, check the following.
  • After using the Implement Interface Wizard to implement interfaces on your new class, add these interfaces to the definition of the class in the IDL file.
  • If the interfaces you implemented are defined in another library, for example, the esriFramework object library, import the library using the importlib directive.
  • Ensure that any enumerations are defined in your IDL if they may be used by clients.

Editing IDL for client neutrality

If you are creating a component in VC++ that may be used in other environments, for example, the ArcGIS VBA environment or VB, you should be aware that not every environment supports all the items you can define in VC++ and IDL.
First, you will need to restrict the data types publicly used in your component to those supported in the target environment. Other issues you may want to consider include:
  • Interface inheritanceVB cannot implement an interface inherited from another custom interface.
  • Attributes—various IDL interface, method, and parameter attributes are not supported by VB. This may also affect the way your VC++ method calls are structured.
  • Multiple outbound interfacesVB only supports a single outbound interface to be sinked. You can provide a solution for this problem purely in IDL.
  • Return types—only error HRESULTS can be converted by VB into errors, positive HRESULT information will be lost in VB.
For more information on how to make these changes, read the Editing IDL appendix. You may also want to refer to the IDL references included in the bibliography.

Compiling the IDL to a Type Library

When you build your VC++ project, referenced IDL files are compiled to a .tlb file. The compiler switches used can be modified, if necessary, from the MIDL tab of the Project Settings dialog box.

Removing type library information from the DLL

By default, type information is also included in the DLL as a resource. This can be removed. ArcObjects DLLs contain no type information, which is instead contained centrally in the object libraries. You may want to remove type library information from your DLL if you have a particular requirement to reduce the size of the DLL, or to keep type information separate from your implementation code.
You can compile a DLL without type information by ensuring the type library is not included as a resource. From the View menu in Visual Studio, open the Resource Includes dialog box and remove the type library directive. It will look something like the following:
1 TYPELIB "ZoomInSample.tlb"
You can also remove this line directly from the resource (.rc) file if you open it up as a text file.
Alternatively, you can leave type information in your DLL, but prevent that information from being entered to the system registry when the DLL is registered. You can do this by changing the RegisterSever call in the DllRegisterServer function of your project to pass a parameter of FALSE.
Type libraries are not always needed at runtime, and therefore, are not always present on an install to a user machine. However, if your component is dual interface, the type library is needed at runtime to turn IDispatch calls into v-table calls. For this reason, if your component is dual interface, you should not remove the type library information from the component DLL.