To really drive home the mechanics of the COM Type Information description interfaces, I've prepared a little browser for the world's greater benefit.   This program isn't perfect.  Oh certainly not.  However, keep in mind that Microsoft's OLEViewer is in version 57.  My viewer is in version 1  :)  You can download the source and the executable here.  Windows 98 users, beware.  The type browser is built from the common control tree view.  This tree view is subject to Windows 98's "Animate windows, menus and lists" enhancement.  With this setting enabled, the tree view will not be responsive when being expanded or collapsed.  You can turn this very annoying feature off through control panel-> display-> effects-> Animate windows, menus, and lists.

Recall from Part II that the type description structures FUNCDESC, VARDESC, TYPEATTR, and TLIBATTR (not covered in Part II) need to be freed with the appropriate ReleaseXXXX method in ITypeInfo or ITypeLib.  Because it's convienent to be able to break out of a stack frame without having to explicitly release all resources in that frame, I've defined some thin wrappers for these four structures.   Note that they throw an exception EVeryBadThing when their initialization function fails.  This saves us from having to check error codes.   However, note that I am not using any exception-throwing COM interface wrappers.  Those would clean the program up even more.  This will be left as an exercise to the reader (and if you do write a wrapper that throws exceptions on failed return codes, why don't you email it to me? :)

Enter the source code.  This first part includes definitions for the type description structures.  I'll break the source into chunks and make comments on each one.

These are very simple wrappers.  When the appropriate initialization method fails, the constructor throws an EVeryBadThing exception to prevent the object from existing in an undefined state.  The next method, stringifyParameterAttributes, simply returns a string holding the parameter attributes gleaned from the PARAMDESC structure.

stringifyParameterAttributes iterates through each bit of PARAMDESC::wParamFlags (well, at least the bits we care about), and concatenates the parameter's attributes between two brackets - just like MIDL.  The PARAMFLAG_FHASDEFAULT bit should draw your attention.   Methods exposed through IDispatch::Invoke can have default values.   Because the parameters of a dispatch method are oleautomation compliant, the default values can be stored in VARIANTARG structures.   PARAMDESC::pparamdescex points to a PARAMDESCEX structure which holds the default value of the parameter.  stringifyParameterAttributes uses VariantChangeType to coerce the default parameter to a Basic String, which is then inserted into the character stream.

Figure 1

Figure 1 shows stringifyParameterAttributes at work.  Exhilarating, isn't it.

These next functions do most of the low-level type description interface work.  I'll forgo the comments, as these procedures have been explained in Part II:

Because stringifying an entire COM method prototype is one of the more complex tasks in the realm of type information, I've constructed two helper functions to make this simpler.  The first, stringifyFunctionArgument, concatenates the result of stringifyParameterAttributes with the result of stringifyTypeDesc.  stringifyCOMMethod builds the entire prototype as seen in Figure 1.  It streams first the return type, then the method name, and finally the stringifyFunctionArgument result for each of the method's parameters.  These arguments are enclosed in parantheses (just like an IDL function prototype).

Each method is either invoked through a vtable interface or through IDispatch::Invoke.   The method's offset in the object's virtual table is displayed for interface methods, and the method's DISPID is displayed for dispinterface methods. 

With the six functions functions posted above, the core functionality of the type browser is complete.  What we now need to do is provide a way for the user to select a type library, and navigate the type library's contents through a tree view hierarchy.  Naturally, this is easier said than done.  I've whipped up a number of classes to accomplish this task.  Check out the class view:

Figure 2

Looks nasty?  It isn't actually that bad - four of the classes are just our type description wrappers, and EVeryBadThing is the trivial exception structure.  To keep the app fast and prevent excessive memory usage, I've taken a "wait and find out" approach to expanding the items on the tree view.  The children for a node are constructed not when the parent node is constructed, but when the parent node is expanded.  The only problem with this is that the parent doesn't know how many children it has until it is actually expanded.  And to get expanded, it needs to have children.  All non-terminal nodes (like structures, interfaces, and containers of structures, interfaces, etc) add a single child node upon construction.  This is encapsulated in the CExpansionNode class.   When the parent node is expanded, the child node is deleted, and the legitimate child nodes are added.  Of course if there are no child nodes, then expanding the parent node will only cause the expansion button to disappear.  While this may seem problematic, it really isn't.  Microsoft's OLE Viewer (now in version 57) uses the same scheme.

CExpansionNode is a very simple class.  The template argument is the name of the derived class (which in this program will always be a node object).  T::treeItem returns the parent node's HTREEITEM.  T::treeView returns the HWND of the tree view.  The CExpansionNode's this pointer is static_casted to T* (which thunks if necessary) producing a pointer to the start of the derived object.  Notice that CExpansionNode's constructor does not insert the dummy node.  Why not?  The derived class T will also inherit CTypeBrowserBase.  The CTypeBrowserBase constructor must be invoked before the dummy node is built (to initialize the data for treeView and treeItem).  For this reason, construction of the dummy node has been relegated to CExpansionNode::BuildExpansionNode.  This method is called from the body of the node class's constructor.  This will all make more sense when you see CTypeBrowserBase, so here it is:

CTypeBrowserBase is a class with a lot of functionality.  It is a base for all node class in the type browser program.  CTypeBrowserBase does two things: it manages node data and serves as a base class for the window procedure to send expand and collapse events.  CTypeBrowserBase::GetParentNode returns a pointer to the CTypeBrowserBase slice of the parent node.  This is a protected method so it can only be invoked by the derived class.  How does this function actually work?  It surely isn't returning any cached pointer: TVITEM::lParam is cast to CTypeBrowserBase* and returned to the caller.  Curious.  The lParam is four free bytes that the tree view control gives the programmer, to store any sort of information (akin to the GWL_USERDATA entry, but for individual nodes instead of windows).   Because the HTREEITEM handles are not nice indices into an array of nodes (as list view item handles would be) but pointers to opaque data, they aren't much help in associating the actual tree view item with corresponding type information object.  What we do is store the address of the type info object as the node's lParam.  Given an HTREEITEM handle to a node, the corresponding type info object can be accessed by dereferencing the pointer stored in TVITEM::lParam by calling the TreeView_GetItem macro.

The CTypeBrowserBase constructor creates the actual tree view node for the type information item.  The name of the node (the string that appears next to the node's button), the HWND of the tree view, and the HTREEITEM of the parent node are all passed as arguments.  The constructor initializes a TVINSERTSTRUCT structure using with the HWND and HTREEITEM parameters.  TVINSERTSTRUCT::item::pszText points to the node's display name.  When this value is LPSTR_TEXTCALLBACK, the tree view sends a TVN_GETDISPINFO message to its parent's window's procedure.  Our message handler casts the node's lParam to a CTypeBrowserBase pointer and invokes CTypeBrowserBase::displayName.  This displayName text is the CTypeBrowserBase constructor's first parameter.  The tree view can similarly retrieve an item's edit box text (displayed when the node is selected and the TVN_SELCHANGED message is fired).

Sounds like a great scheme, doesn't it!  Use the node's lParam to store the location of the corresponding type info object.  But wait...  What happens if the object changes location?  The pointer stored in the lParam then refers to garbage.  While an object obviously can't just pick up and move to a different place in memory, it can be copied.  These objects are often part of an STL vector, so they are created on the stack before being pushed to their container.  This sequence will invoke the object's copy constructor or assignment operator at least once.  So how do we handle this?  Recall the functionality of the Standard Library auto_ptr.  An auto_ptr has a single data member: a pointer to the data it wraps.  The auto_ptr's destructor deletes this memory if the pointer is non-zero.  Invoking the copy constructor or assignment operator on an auto_ptr will set the source's pointer to the argument object's pointer, and then clear the argument object's pointer.  This effectively transfers "ownership" of the memory to the most recently created auto_ptr.  We employ a similar strategy here. 

CTypeBrowserBase "owns" a tree view node.   Like auto_ptr, CTypeBrowserBase transfers ownership of its _treeItem member during copy construction and assignment operations.  The copy constructor grabs the TVITEM structure of the argument's node and writes its own pointer to TVITEM::lParam.  Here's the kicker: it sets the argument's _treeItem member to zero.  This means that the object has "lost ownership" over its node, and the object's death will not cause the destructor to remove its node from the tree.  To allow the copy constructor and assignment operator to fiddle with its argument's HTREEITEM, CTypeBrowserBase::_treeItem is defined as mutable.

CTypeBrowserBase also serves as the common base class for all nodes.  The virtual methods collapse, expand, and editBoxText are overridden by the derived class to perform operations specific to the type information object.  These methods, along with CTypeBrowserBase::displayName (which is non-virtual), are invoked from the parent window's message procedure.  The methods treeView and treeItem provide the derived class (and CExpansionNode) with access to the HWND of the tree view and the HTREEITEM of the node. 

Here come the first two node classes.

Shamefully simple.  These two classes are terminating nodes; they don't inherit CExpansionNode, so they can't be expanded.  CComEndNode's constructor merely passes its parameters to CTypeBrowserBase and provides trivial implementations of collapse and expand.  The class inherits CTypeBrowserBase's implemention of editBoxText, which returns the string " COM Owns You."  CComMessageEndNode is identical to its base, CComEndNode, except it lets you override the edit box message with whatever you want. 

Obviously these terminating nodes aren't too helpful by themselves.  These end nodes are children of "container nodes," that is, nodes that are expandable.  Examples of these nodes include structures, enums, unions, interfaces, dispinterfaces, and typedef "containers."  Typedefs have no child values, so they are actually end nodes.  The following template class serves as a container for union values, structure values, or enum values, depending on the template argument.

CComVariableGroup contains any number of CComEndNode objects.  This class derives from CExpansionNode, meaning it is expandable.  The expand and collapse methods also have nontrivial implementations.  In addition to the parameters it sends to CTypeBrowserBase, CComVariableGroup's constructor is passed an ITypeInfo pointer.  This is a type description pointer for one of the type library's variable types, namely a structure, a union, or an enum.  The name of this variable type is passed to the constructor as the name parameter. TYPEATTR::cVars (initialized with the CComTypeAttr constructor) specifies the number of values for the type.  On expand, CComVariableGroup for loops through each of these variables and invokes stringifyVarDesc to produce a string version of the value.  Remember that for constants (i.e. enumerated values) stringifyVarDesc will append an equals sign and the constant value.  A CComEndNode is constructed from this string, and added to the variable group's vector.  Upon collapse, CComVariableGroup clears its vector, destroying all end nodes.  This invokes CTypeBrowserBase's destructor for each end node, which removes the node from the tree view.  Finally, CComVariableGroup's expansion node is built again to enable another expansion.

Figure 3

Figure 3 shows the relationships between the CComVariableGroup objects and their CComEndNodes.  In addition to the "Enums" node, expanding the "Structs" node and "Unions" node will expose more CComVariableGroups as well, each with a set of CComEndNodes.  So CComVariableGroup supplies functionality for three different types of variables.  That's a pretty flexible class.  CComInterfaceJoint is also a flexible class; it manages both interface and dispinterface nodes.

Like CComVariableGroup, CComInterfaceJoint is a container for end nodes.  In addition to the CTypeBrowserBase constructor parameters, CComInterfaceJoint::CComInterfaceJoint is passed an ITypeInfo pointer.  This is a type description for the interface in question, be it dispatch or virtual.  TYPEATTR::cFuncs (retrieved with the CComTypeAttr constructor) specifies the number of functions of the interface.  expand enters a for loop which iterates through each function.  ITypeInfo::GetNames returns the function's name, and a FUNCDESC::invkind switch stringifies the invoke kind of the function.  Together, these strings comprise the end node display names, as shown in Figure 4. 

Notice that CComInterfaceJoint manages not a vector of CComEndNodes, but of CComMessageEndNodes.  The latter class allows overriding of the edit box text.  In the case of CComInterfaceJoint's end nodes, the edit box displays the full function prototype, procured from stringifyCOMMethod.   We certainly are getting a lot of mileage from the functions presented in Part II and early in Part III.  Another interesting aspect of CComInterfaceJoint is its overridden editBoxText method.  When selected, the interface joint displays its IID and interface name in the edit box.  It might loook something like this: "IID: {35053A20-8589-11D1-B16A-00C0F0283628} IProgressBar."  One nice thing about the edit control is that you can select an arbitrary portion of its contents and copy it to the clipboard through the popup menu.  Quite helpful for dropping IIDs into your own projects.

Figure 4

Figure 4 shows the relationship between the CComInterfaceJoint and its CComMessageEndNode children.  By relying on stringifyCOMMethod, the CComMessageEndNode edit box text displays the DISPID for dispatch methods and the vtable offsets for virtual methods.  Now onto the containers!

CComVariableGroupContainer objects contain CComVariableGroups (how aptly named).  This is a templated class, where the template argument, tk, holds a value of the TYPEKIND enum.  Because the contained objects, CComVariableGroups only handle enums, unions, and structures, tk must only be TKIND_ENUM, TKIND_UNION, or TKIND_RECORD (why not TKIND_STRUCTURE I do not know).  The class's constructor takes a name parameter, which is "Enums," "Unions," or "Structs" depending on the TYPEKIND.  More importantly, the constructor is passed an ITypeLib pointer, which describes the type library in question. 

On expand, CComVariableGroupContainer retrieves the number of described types through ITypeLib::GetTypeInfoCount.   It then loops through each type, querying ITypeLib::GetTypeInfoType and comparing the returned TYPEKIND to the template argument TYPEKIND.  When the two match, the type's name is retrieved through ITypeLib::GetDocumentation and the ITypeInfo pointer describing the type is retrieved.  The type's name and type description pointer are passed to the CComVariableGroup constructor, which is pushed to the vector.  None of this is very complicated - with good design, building a type info browser isn't that painful.

I'm sure your eyes have wandered down to the editBoxText definition.  "What ht hell..." you must be thinking.  It returns no value.  In fact, it doesn't do anything.  CComVariableGroupContainer::editBoxText will not compile.  Why then did I define it this way?  To allow for specialization.  The three specializations that follow send customized messages to the edit box.  The name of the type library is glued to the stringified typekind ("Enumerations", "Structures", or "Teamsters" (Hoffa lives!)) and returned from editBoxText.  Yippie.  Download the executable and see for yourself.

CComInterfaceGroupContainer is very similar to CComVariableGroupContainer.  The TYPEKIND template argument specifies which sort of interface the object describes: TKIND_INTERFACE or TKIND_DISPATCH.  The name of the interface is passed to the class's constructor, as is the type library pointer.  The expand method iterates through each of the library's types, comparing ITypeLib::GetTypeInfoType to the template argument tk.  On a match, the interface's name and ITypeInfo description pointer are passed to the CComInterfaceJoint constructor.  The resulting object is pushed to the vector.  The editBoxText specializations send a helpful messages to the application's edit control.

If you were really paying attention in Part II, you'd already have identified a problem with CComInterfaceGroupContainer::expand.  So let me clue you in: dual interfaces are always exposed as type TKIND_DISPATCH.  To quote the Automation Programmer's Reference, "For dual interfaces, ITypeLib::GetTypeInfo returns only the TKIND_DISPATCH type information.  To get the TKIND_INTERFACE type information, ITypeInfo::GetRefTypeOfImplType can be called on the TKIND_DISPATCH type information, passing an index of –1.   Then, the returned type information handle can be passed to ITypeInfo::GetRefTypeInfo."  This is easily taken care of with an expand specialization:

Fairly beefy function; I'm getting paid by the line.  On second consideration, I'm not getting paid at all.  Anyways, this specialization has two cases: TKIND_INTERFACE (vtable interface) and TKIND_DISPATCH (dual or dispatch).  If ITypeLib::GetTypeInfoType returns TKIND_DISPATCH, GetRefTypeOfImplType is invoked on the corresponding ITypeInfo pointer to procure the vtable interface's HREFTYPE (if there is one).  ITypeInfo::GetRefTypeInfo produces the ITypeInfo pointer describing the vtable interface.  ITypeInfo::GetDocumentation produces the interface's name.  We ship these two pieces of informations off to CComInterfaceJoint's constructor, and add the resulting object to the vector.  If the initial ITypeLib::GetTypeInfoType call produces a TKIND_INTERFACE, we can skip all this nonsense and just take the straightforward approach.

We've reached the homestretch (well, in the same sense that a marathon runner who enters the fourteenth mile is in the homestretch).  How are typedefs added to the browser?  Check out CComTypedefContainer:

CComTypedefContainer manages a vector of CComEndNodes.  Each end node's display value is a typedef statement.  This statement is the concatenation of "typedef", stringifyTypeDesc, and the type's name.  CComTypedefContainer adds typedefs to our type browser.  The only type left is the coclass (I am neglecting TKIND_MODULE types, as they are evil). 

Expanding a coclass node displays a list of the interfaces implemented by the coclass.  These terminating nodes are managed by CComEndNode objects.  For a breakdown of the interface's methods, the user can look in the "Interfaces" and "Dispinterfaces" containers.  CComCoClassNode::editBoxText provides some useful information to the user.  A CComTypeAttr object is created, and the CLSID is gleaned from it.  This CLSID plus the name of the coclass is displayed in the edit control when the coclass node is selected.  The CComCoClassNode object is managed by (yes, you guessed it) CComCoClassContainer.  And here it is:

CComCoClassContainer behaves in the spirit of the other containers.  It constructs CTypeBrowserBase by passing the string "CoClasses," which sets "CoClasses" as the display name.   On expand, each type in the library is tested against TKIND_COCLASS.  For those that match, the name of the coclass is retrieved with ITypeLib::GetDocumentation.  CComCoClassNode objects are created for each coclass, and are initialized with the name of the coclass.  It's very consistent with the classes we've already covered.

Guess what?  There are only two classes left to cover.   But before we work on those, take a look at Figure 5 and make sure you understand where each class fits into the tree view.

Figure 5

This program looks a lot simpler after seeing Figure 5, doesn't it!  Or maybe not.  There are two classes remaining: CComTypeLibrary manages the actual type library pointer and serves as the parent node for the six container classes.  From Figure 5, "Microsoft XML 1.0 <1.0>," "Active Setup Control Library <1.0>," and "PStore 1.0 Type Library <1.0>" are CComTypeLibrary objects.  All of these type library objects are children of the root object, CComTypeLibraryContainer.  While CComTypeLibrary is a very simple class (it just has a few auto_ptrs and statements to initialize them), CComTypeLibraryContainer does some nontrivial work.  CComTypeLibraryContainer::expand iterates through all the keys in HKEY_CLASSES_ROOT\TypeLib and pulls out the type libraries.  It then instantiates CComTypeLibrary objects from this registry information.