Writing Type Libraries

A type library is a compiled script written in the Object Definition Language (ODL) containing descriptions of the data types and and objects exposed by a dll, ocx, or exe, typically for use in OLE Automation. ActiveX clients (such as Visual Basic) use this information to access the objects. Information about type libraries can be obtained from the Platform SDK, under 'Object Services / Automation'.

In the case of this type library, the library contains declarations of data types and functions exported from several system dlls, namely gdi32.dll, user32.dll, and the opengl dlls. The source code for the type library is produced by translating the relevant header files in the SDK. The code is then compiled with the MIDL compiler. The resulting '.tlb' file must be registered (using regsrv.exe or Visual Basic) and a reference to the type library must be added to any Visual Basic project which will use it. After a reference is added, all the information in the type library is available in the Visual Basic design environment. For more information on writing a type library, see B. McKinney's 'Hardcore Visual Basic', which includes the source code for his Win32 type library. The VBOpenGL type library was modeled on his.

---

Writing a type library

Writing a type library for an Automation server is beyond the scope of this discussion. I will focus instead on creating a type library for a simple C dll for which you have a header file. I also assume the tlb is to be used with VB5.

1. The first step is to translate the header file to ODL. This is simple but tedious. It basically consists of declaring a 'library' and generating a GUID for it, declaring any modules the library will contain and generating GUIDs for them, then modifying the header file's declarations. Modifying the header declarations entails moving all the 'typedef' statements to the top of the file, converting all the '#define' statements to 'const' declarations, and adding '[entry ..]' declarations around all the function prototypes. The resulting file looks something like this:

  //library attributes:
  [ uuid(03644881-8010-11d1-95AA-000000000000),
    helpstring("VB OpenGL API 1.1 (ANSI)")
  ]
  library VBOpenGL
  {
    
    //typedefs ...
    
    //module attributes:
    [
    uuid(1D15DCA0-802D-11d1-95AA-000000000000),
    helpstring("OpenGL gl functions"),
    dllname("OPENGL32")
    ]
    module GL 
    {
      //constants:
      const int GL_BYTE = 0x1400;

      //function prototypes:
      [entry("glColor3f"),
      helpstring("Sets the current color"),]
      void APIENTRY glColor3f (GLfloat red, 
                GLfloat green, GLfloat blue);
    }

    //more typedefs ...

    //more modules ...
    
  }

2. Add enumerations and helpstrings. Helpstrings are displayed in the VB Object Browser (or other type browser, such as OLEView) and provide quick descriptions of functions and types. Enumerations allow VB to display function parameters in a popup list in the design environment. Enumerations are useful when a function accepts a limited set of defined values. The following code shows how to provide enumerated parameters for a function:

Create the enumeration:

  /* GetMaterial */
  [ helpstring("Specifies which of the two 
            materials is being queried") ]
  typedef enum glGetMaterialConstants{
    gmFront = 0x0404,
    gmBack = 0x0405
  }glGetMaterialConstants;

Then change the function prototype to use the enumeration:

  [entry("glGetMaterialfv"),
  helpstring("returns material parameters"),]
  void APIENTRY glGetMaterialfv (
      glGetMaterialConstants face, 
      glMaterialParameterConstants pname, 
      GLfloat *params);

3. Fix the declarations so that they can be used from VB. Some C function prototypes cause VB to interpret the function parameter 'As Any' and to issue the runtime error 'Type not supported by Automation' when the function is called. Some struct fields are also not supported by VB. Several factors must be considered, including the data types supported by OLE, the differences in data storage of C and Basic, and the runtime behavior of VB. Most of these problems can be fixed by modifying the function prototype or the struct declaration. Typical problems include:

• Function parameters VB refuses to recognize, such as pointers to functions and pointers to pointers. These problems can usually be fixed by changing the function parameter to a simple long and adjusting the value passed from VB code (using ByRef, ByVal, and VarPtr). Using LPVOID instead of long may work in some cases.
  
  
• Strings. A few API structs contain variable-length strings. These cannot be declared in a type library and must be declared in VB code.

Be aware that calling C code from VB has always been problematic, and one of the purposes of COM technology is to provide a protocol for these kind's of communications. You may be able to get help on intractable functions by consulting newsgroups devoted to COM or OCX programming.

---

More information:

You need the midl compiler - midl.exe - to compile an ODL file into a '.tlb' file. The midl compiler can be downloaded from Microsoft as part of the Platform SDK.

Platform SDK - includes the compiler and documentation.

You can view the source of many type libraries with OLEView, included in Visual Studio, the SDK, and available at the MS web site.

Hardcore Visual Basic, Second Edition - by Bruce McKinney
The most extensive discussion of writing type libraries for VB that I know of.

Patrice Scribe's type libraries - see the COM section for a discussion of writing type libraries for VB.

Inside COM - by Dale Rogerson

Essential COM for VB Programmers
A white paper from a vbits conference.

OLE Automation for C++ programmers - A paper containing a discussion of type libraries.

Some pages at the Microsoft site:

Designing COM Interfaces

MS article on Type libraires

MS article on Type libraires

MSJ sometimes discusses type libraries.