Visio-Enabled Solution: COM-Free Visio Automation in C++ (Using the Visio Wrapper Classes)

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Tim Wittwer and Alan Delwiche
Fluke Networks

April 2001

Applies to:
   All Microsoft Visio 2002 Editions
   All Microsoft Visio 2000 (SR-1) Editions
   All Microsoft Visio 5.0 Editions

****Summary:****Learn how Fluke Networks applies Microsoft Visio Automation technology to the automatic discovery and mapping of switched networks as you examine the C++ source code examples in this document. (9 printed pages)

Contents

Introduction
Visio Enabled Solution: LAN MapShot
C++ Source Code Examples
Conclusion
For More Information

Introduction

The recent growth of switched networks has outpaced the development of tools needed to provide vision into those networks. The lack of visibility into the flat switched network topology has resulted in reduced performance, elevated complexity, and increased strain on the IT professional. This white paper discusses Fluke Networks application of Microsoft® Visio® Automation technology to the automatic discovery and mapping of switched networks.

The Switched Network Vision Problem

In switched networks, the internal forwarding table of each switch contains entries for every other switch, server, router, printer, host, and managed hub it sees on the network. Since every switch can know of the existence of every other networked device, the hierarchy inherent in routed network architectures is absent in switched networks. This lack of hierarchy causes switched networks to be referred to as flat. These flat networks are difficult to document since the actual physical location of connected devices is hard to determine by just reviewing the switch forwarding tables. Furthermore, visiting equipment closets to note actual port connections is time consuming, tedious, and subject to error. To make matters worse, once the data is finally collected, it must then be translated into some meaningful map or report. Exasperation results when the map or report is complete, only to be rendered obsolete a few days later by constant network change.

Why Switched Network Vision Is Needed

The constant change in network topology increases the probability of failure, configuration error, and performance degradation. More than ever, there is a need to:

• Troubleshoot effectively
• Locate equipment
• Communicate network design changes to colleagues
• Plan for expansion

IT professionals managing switched networks require tools that are optimized for their particular needs, are easy to use, and yet produce fast, detailed, and reliable results.

Visio Enabled Solution: LAN MapShot

Fluke Networks has migrated its handheld network test instrument expertise to the Microsoft Windows desktop and partnered with Microsoft Visio to create LAN MapShot™. This solution realizes powerful, switched network vision by combining detailed discovery with exceptional ease of use.

IT personnel can now:

• Discover switched network with a single mouse click
• Map switches, servers, routers, printers, hosts, and even hubs
• View device connectivity down to slot:port level detail
• Drill down from the broadcast domain to a single switch port

As shown in Figure 1, the LAN MapShot application interface is well laid out and easy to understand and use. When the Start Discovery button is clicked, the application begins looking for devices on the network. Once discovery is complete, a default map is drawn. You can then select from six different maps on the Network Maps menu.

Figure 1. LAN MapShot main application interface

Using Visio Automation to Create Network Maps

Fluke Networks utilizes the Visio Automation interface to programmatically draw the results of its network discovery as detailed, port level, topology maps. Automation is the means by which a program written in VBA, Microsoft Visual Basic, C/C++, or another programming language that supports Automation can incorporate the functionality of an application simply by using its objects. Visio objects can range from a high level Application object that represents an instance of the Visio application to a simple Cell object that may only control the color of an item.

Programming Visio objects with Microsoft C++ is greatly simplified by using the VisiWrap.h interface. VisiWrap.h describes the Visio object model as familiar C++ classes. The use of wrappers also minimizes the burden of managing the COM interface reference pointers. With wrappers, the adding and releasing of interface reference pointers is handled seamlessly, thus offloading this more error-prone COM housekeeping task.

C++ Source Code Examples

The following section shows C++ source code examples for common Visio Automation tasks.

Initializing COM

You must initialize COM prior to utilizing the Visio Automation objects. This is usually done in the client application constructor, and needs to be done only once.

::OleInitialize(NULL);

Launching Visio

Calling the vaoGetObjectWrap function and initializing a CVisioApplication object opens Visio. If Visio is not running at the time the call is made, this automatically opens Visio and initializes the given CVisioApplication object. If Visio is running, the CVisioApplication object is initialized to talk to the currently running instance of Visio.

//Launch Visio...
CVisioApplication app;
int result = vaoGetObjectWrap(app); 
if( result != VAO_SUCCESS ) 
  return false;

As shown in Figure 2, the Visio application is launched without any open stencils or documents.

Figure 2. Opening the Visio application

Retrieving the CVisioDocuments Collection

The Visio Application object owns the Documents collection. The code below calls the CVisioDocuments object from the Application.

//associate CvisioDocuments to CVisioApplication...
HRESULT hr= NOERROR;
CVisioDocuments visioDocs;
hr= app.Documents(visioDocs);
if ( !SUCCEEDED(hr) )
  return false;

Adding Stencils (*.vss)

Next, an existing stencil file will be used to create a new CVisioDocument object, and that object will be added to the CVisioDocuments collection.

//Open an existing stencil, add to CVisioDocuments
CVisioDocument stencilDoc;
hr= visioDocs.Add(VBstr("teched.vss"), stencilDoc);
if ( !SUCCEEDED(hr) )
  return false;

As shown in Figure 3, a new stencil document with three masters now appears in the Visio window.

Figure 3. Visio stencil document with three masters

Creating a CVisioDocument from a Template (*.vst)

Now it is time to create a CVisioDocument using an existing template (*.vst) file. In this example, a template file named teched.vst is used. The template contains default text and page setting information that will be used as a starting point for the new document. Once the new CVisioDocument is created, it will be added to the CVisioDocuments collection.

//Create a new document from a template, then add to CvisioDocuments…
CVisioDocument doc;
hr= visioDocs.Add(VBstr("teched.vst"), doc);
if ( !SUCCEEDED(hr) )
  return false;

Using the template file to create the starting document saved some work. Behind the scenes, the CVisioPages object was obtained from the CVisioDocument object. Then, the newly created CVisioPage was added to the CVisioPages collection. Next, the CVisioShapes collection was obtained from the CVisioPage object, and a CVisioShape was added to the CVisioShapes collection.

In this case, the new CVisioShape object contains the text shown in Figure 4.

Figure 4. Creating a CVisioDocument using an existing template

**Note   **The previously created stencils are still open and available; they have simply been hidden behind the newly added CVisioPage object.

Using CVisioMaster Objects

The following code gets the CVisioMaster collection from the stencil document, and then reads the three CVisioMaster objects.

//Get the CVisioMasters collection from the stencils document…
CVisioMasters visioMasters;
hr= stencilDoc.Masters(visioMasters);
if ( !SUCCEEDED(hr) )
  return false;

//Get the Fluke Logo master (stencils)....
CVisioMaster flukeMaster;
hr= visioMasters.Item(VVariant("Fluke"), flukeMaster);
if ( !SUCCEEDED(hr) )
  return false;

//Get the Visio Logo master (stencils)....
CVisioMaster visMaster;
hr= visioMasters.Item(VVariant("Visio"), visMaster);
if ( !SUCCEEDED(hr) )
  return false;

//Get the connector master (stencils)....
CVisioMaster connectMaster;
hr= visioMasters.Item(VVariant("connector"), connectMaster);
if ( !SUCCEEDED(hr) )
  return false;

Creating CVisioShape Objects from CVisioMaster Objects

Dropping a CVisioMaster object on to a CVisioPage results in the creation of a CVisioShape object. The following code gets the active page from the Application object, and then adds three shapes to the page at the specified (x,y) coordinates. Note location (0,0) is in the lower left corner of a Visio page.

//get the active page...
CVisioPage page;
hr = app.ActivePage(page);
if ( !SUCCEEDED(hr) )
  return false;

//Drop a Fluke logo shape on the page..
CVisioShape flukeShape;
hr= page.Drop(flukeMaster, 2.5, 5.0, flukeShape);
if ( !SUCCEEDED(hr) )
  return false;

//Drop a Visio logo shape on the page..
CVisioShape visShape;
hr= page.Drop(visMaster, 8.0, 2.0, visShape);
if ( !SUCCEEDED(hr) )
  return false;

//Drop a connector shape on the page..
CVisioShape connectShape;
hr= page.Drop(connectMaster, 5.0, 3.5, connectShape);
if ( !SUCCEEDED(hr) )
  return false;

As shown in Figure 5, the page now shows the three newly added CVisioShapes. Notice that the connector shape has not yet been attached to the other shapes.

Figure 5. Creating CVisioShape objects from CVisioMaster objects

Connecting Shapes

Connecting these shapes requires obtaining one connection point from each logo shape, and both the beginning and ending connection points for the line shape. A connection is made when a line shape is glued to a logo shape.

First, a Fluke Networks logo connection point and a line connection point are retrieved from the shapes, and then stored in CVisioCell objects. Next, the cells are glued together forming the connection.

//Get the 'BeginX cell' of the connector shape...
CVisioCell beginCell;
hr = connectShape.Cells(VBstr("BeginX"), beginCell);
if ( !SUCCEEDED(hr) )
  return false;

//Get a Fluke Networks Logo connections cell...
CVisioCell flukeCell;
flukeShape.Cells( VBstr("PinX"), flukeCell);

//connect the beginning of line to the fluke cell...
hr = beginCell.GlueTo(flukeCell);
if ( !SUCCEEDED(hr) )
  return false;

As shown in Figure 6, notice that the line is now connected to the Fluke Networks logo; however, the Visio logo remains detached.

Figure 6. Connecting shapes

Completing the Connection

Now, a Visio logo connection point and a line connection point are retrieved from the shape and stored in CVisioCell objects. Gluing the cells together completes the connection.

//Get the 'EndX cell' of the line shape...
CVisioCell endCell;
hr = connectShape.Cells(VBstr("EndX"), endCell);
if ( !SUCCEEDED(hr) )
  return false;

//Get the Visio logo connection cell…
CVisioCell visCell;
visShape.Cells( VBstr("PinX"), visCell);

//connect the end of line to the visio cell...
hr = endCell.GlueTo(visCell);
if ( !SUCCEEDED(hr) )
  return false;

As shown in Figure 7, notice that the Visio logo attachment completes the connection. By requesting different connection cell names like PinY, one can control where shape connections are made.

Figure 7. Gluing the cells together

Conclusion

The Microsoft Visio Automation interface affords Fluke Networks a powerful, reliable, and easy-to-use drawing platform for their network mapping products. Utilizing active and passive discovery techniques and sophisticated analysis, LAN MapShot provides detailed (slot:port) connectivity vision into switched networks.

Figure 8 illustrates a sample output from Fluke Networks LAN MapShot mapping product.

Figure 8. Single switch detail map (click to view larger image)

For More Information

Consult the Visio Developers Reference included in Microsoft Visio Help, or see the MSDN and TechNet Web sites for more code samples and automation tips.

You can also visit the Fluke Networks Web site.

Tim Wittwer and Alan Delwiche are Senior Software Engineers at Fluke Networks, where they are key members of the LAN MapShot and Network Inspector development teams.

All product names mentioned in the Visio Automation examples or the LAN MapShot application report are trademarks of their respective manufacturers. The network map in this document was created using a laboratory test network, and any mention of a third party company or product does not imply nor suggest endorsement.