30 November 2013

Using OLE/COM Object Viewer

Ever wondered how to get information about all properties and methods of the GFA-BASIC 32 OCX COM-objects?

To view GFA-BASIC OCX type library information, you can use the Microsoft OLE/COM Object Viewer utility that is included with the Microsoft Windows SDK kits.

image

The figure displays information from the GfaWin23.Ocx type library, a resource found in this DLL. More specifically, it shows the details for the Form Ocx and the CurrentX Get Property. You use the OLE-COM Object Viewer to view compiled type library information. The object viewer presents the COM classes in C/C++ syntax.

To view a type library with the OLE/COM Object Viewer:

  1. Find the OLE/COM Object Viewer application in the bin directory of the installation path.
  2. On the File menu, click View TypeLib, and browse to locate the type library you want to view (GfaWin23.Ocx)

Like the Object Browser that VB and Microsoft VBA use, the OLE/COM Object Viewer lists all the classes exposed in a type library, along with the methods and properties those classes support. For the programmer, the OLE/COM Object Viewer provides important information, such as function return types, argument types, and DISPIDs (which will be discussed shortly). You can use the information that the viewer provides in conjunction with the GB32 object model documentation.

 

Download SDK
The latest Windows Software Development Kit for Windows 8 (Windows SDK) contains headers, libraries, and a selection of tools that you can use when you create apps that run on Windows operating systems.
Download:
The Windows Development Kit (SDK)

I also advise to read Automating Microsoft Office 97 and Microsoft Office 2000 to refresh your memory on the binary layout of COM objects. You may take a look at the section “How an object can exposes its methods and properties”. It does so in two ways: by means of a dispatch interface and in its vtable. Also take a look at my blogs Build a COM object in GB32 (1) and    CreateObject.

A COM object exposing its functions through a vtable only, provide clients with early binding only. The compiler binds methods and property invocations to the vtable-function-pointers directly for more direct access and faster execution. An object that exposes its methods through both a dispinterface and its vtable supports a dual interface.

The DispID
You can examine type libraries in the OLE/COM Object Viewer to determine if an object provides a dual interface. An object that provides a dual interface specifies the dual attribute in its interface declaration. All GB32 OCX objects implement the IDispatch interface. It is this IDispatch interface that provides Automation clients with access to an object's content and functionality. An object's methods and properties collectively make up its dispatch interface (or dispinterface). Within the dispinterface, each method and property is identified by a unique member. This member is the function's dispatch identifier (or DispID).

A COM object can provide clients access to its functions using a dispinterface, an array of function names, and an array of function pointers that are indexed by DispIDs. In GB32 the execution of methods and properties through the dispatch interface is hidden behind the COM dot-operator on an Object data type. First see how GB32 executes properties and methods through early binding.

' Create new instance of the ImageList OCX.
' The Iml variable is of COM type (I)ImageList.
Dim Iml As New ImageList
' Access through early bindings; call the
' ImageHeight and ImageWidth directly through
' a function pointer.
Iml.ImageHeight = 16
Iml.ImageWidth = 16
Iml.Add  , "comp", LoadPicture(":MyComp")

See also: Dim As New

As you can see from OLE-VIEW, the IImageList interface is declared dual. So, the properties and methods are available at runtime as well (late binding). The GB32 compiler doesn’t put a reference to a function address, but stores the name of the method or property and the values of the parameters that must be passed. The compiler than inserts a call to Invoke() to have the program call the method or property at runtime by looking up the name of the function through GetIDsOfNames(). You may want to read the section on Binding in the same article Automating Microsoft Office 97 and Microsoft Office 2000

Note It is a VB/VBA convention to use the name of an interface a a new user-defined type and than skip the capital I from an interface name. So, IImageList in OLEVIEW becomes ImageList type in BASIC.

Now let us see how the method and properties of the ImageList type can be executed at runtime through late binding. The general BASIC Object data-type is an object consisting only of the IDispatch functions. The Object variable oIml doesn’t know about other interface functions ImageList supports. The compiler inserts code to execute the function .Count at runtime through the IImageList functions GetIDsOfNames and Invoke.

Dim oIml As Object      // An IDispatch object
Set oIml = Iml          // Assign to Object
Print oIml.Count        // late binding

To execute the Count property of the oIml object must call GetIDsOfNames to "look up" the DispID for the property. Subsequently, oIml calls Invoke to execute the property by using the DispID to locate the Count function address in the IImageList’s array of function pointers.

Next blog: GFA-BASIC 32 supports syntax and functions to look up the DispID and use Invoke.