Visual Basic s COM Language Mapping

---

Visual Basic's COM Language Mapping

In the dark days of Visual Basic, developers were only able to access a COM server's functionality through a standard interface named IDispatch. IDispatch provides an alternative way for clients who cannot directly reference our object's vTable interfaces (such as IDraw and IShapeEdit) to access the functionality of a COM object. IDispatch is most commonly used in scripting environments (such as VBScript); we will have much more to say about this interface in Chapter 10.

These days, Visual Basic developers may directly access our COM object's set of custom (vTable) interfaces as well as IDispatch. Before VB developers can do so, however, they must set a reference to the server's type information using the References dialog, accessed from the Project | References menu. Figure 4-8 illustrates how to include the shapes library into a VB project (notice the custom [helpstring] in action):

Figure 4-8: The VB References dialog.

As you may suspect, the VB References dialog box will scan HKCR\TypeLib for all registered type libraries on your machine, and present them in a list box. Also notice the Browse... button. If we did not add the necessary TypeLib information to our server's REG file, the VB developer could make use of this button to manually navigate to the location of the *.tlb file. Be a thoughtful COM developer, however, and get in the habit of going that extra step. Register your type information.

Once a reference has been set to the type library, VB developers may examine the contents of a server using the VB Object Browser utility (F2 is the hot key). Figure 4-9 shows the type information VB extracted from our shapes.tlb file. As you can see, CoHexagon, IShapeEdit, and our custom FILLTYPE enum all come through. Notice we do not see an IDraw interface, as we declared it to be the [default] interface of CoHexagon:

Figure 4-9: The VB Object Browser.

Creating Coclasses in VB

Visual Basic developers are free to make instances of our COM classes using the New keyword. The VB New keyword does quite a bit on your behalf under the hood. Here is what really happens when a VB programmer creates a new coclass like so:

' Once a reference to the Shapes.tlb file has been set, ' a VB developer may make use of CoHexagon as so. ' Dim hex as New CoHexagon    ' Declare a new object type. hex.Draw                    ' Access methods of [default] interface.

The code above wraps up all the steps we, as C++ developers, go through by hand:

1. VB reads the type information in our server and discovers the [default] interface.

2. VB calls CoCreateInstance() for CLSID_CoHexagon.

3. VB asks for the default interface, resulting in an AddRef() on CoHexagon.

4. VB stores the default interface in the CoHexagon variable.

At this point, the VB developer holds onto an IDraw* variable, although this is completely hidden from the VB language mapping. To unknowing VB developers, it looks as if they are holding onto an object reference. You know better. COM is all about interfaces. Even when it looks as if you don't have one, you do.

When a VB developer is finished with an interface pointer, the VB runtime will automatically call Release() on the interface when it falls out of scope. If you wish to call Release() before that time, you may explicitly set a reference to Nothing:

' An explicit Release(). ' Set hex = Nothing               ' The VB equivalent of pDraw->Release()

Calling QueryInterface() from Visual Basic

Now, if VB automatically grants access to the default interface of a coclass, the next logical question is "how can we query for the others?" Visual Basic 5.0 introduced the ability to navigate a coclass's set of supported custom interfaces using the Set = syntax. Here is how a VB client may query for interfaces beyond the default (note the implicit AddRef() calls):

' First create the coclass and grab the [default] interface. ' Dim hex as New CoHexagon hex.Draw                    ' AddRef has been called. [refcount = 1] ' Declare a variable of type IShapeEdit (can't 'New' interfaces!) Dim itfSH as IShapeEdit ' Query hex for IID_IShapeEdit (e.g., hex.QueryInterface(IID_IShapeEdit, itfSH) ) Set itfSH = hex               ' AddRef has been called again. [refcount = 2]

The above code is great, but what if we wish to ensure the above QueryInterface() call succeeded before calling off the IShapeEdit pointer? In order to test if a QueryInterface() call succeeded, we may make use of the following VB syntax:

' Test before calling interface methods ' Set itfSH = hex If Not itfSH Is Nothing Then          ' Do we have the IShapeEdit interface?      itfSH.Inverse      itfSH.Stretch 20      itfSH.Fill POLKADOT End If 

Again, the itfSH and the hex variable will eventually drop out of scope of the given function which calls Release() on the interfaces automatically. In VB we can force a Release() of an interface pointer as soon as possible by using the Nothing keyword:

' Explicitly releasing interfaces in VB. ' Set itfSH = Nothing              ' Release() called.      [refcount = 1] Set hex = Nothing                ' Object destroyed.      [refcount = 0]

AddRef() and Release() are so well hidden by the VB runtime, we seldom have to think about it at all. QueryInterface() in Visual Basic can be summed up with the following pseudo-code:

Dim CoClassVariable as New <CoClassYouWant>  ' Get the [default] Dim InterfaceVariable as < InterfaceYouWant >          ' Declare interface variable Set InterfaceVariable = CoClassVariable ' Get another interface

This information is just enough to make you dangerous in the VB COM universe. In the next set of labs, you will be given a step-by-step VB client example, so don't panic if you are unfamiliar with VB syntax. The point here is not to develop professional VB applications, but to understand the basics of using VB to access our C++ COM servers. Next, let's see what it would take to use CoHexagon from within the Java language.

---