Microsoft KB Archive/185726

{|
 * width="100%"|

SAMPLE: PingCtrl.exe Uses Winsock2 Features from Visual Basic

 * }

Q185726

-

The information in this article applies to:


 * Microsoft Windows NT Server version 4.0
 * Microsoft Windows NT Workstation version 4.0
 * Microsoft Windows 95
 * Microsoft Windows 95 OEM Service Release

-

SUMMARY
PingCtrl.exe is a sample source for an ActiveX control that demonstrates how to access complicated Winsock features from Visual Basic. PingCtrl.exe implements "ping-like" functionality so that you can test whether a particular workstation is running from a Visual Basic application. While a programmer can infer whether a workstation is running by calling some of the Lanman or WNet APIs, this is not a very flexible solution. In this case, Ping is a better solution. However, the steps involved in importing a large number of Winsock API calls required by Ping is daunting. PingCtrl.exe simplifies this process.

MORE INFORMATION
The following file is available for download from the Microsoft Download Center:

"PingCtrl.exe" For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

"Q119591 How to Obtain Microsoft Support Files from Online Services" Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

PingCtrl.exe demonstrates how to access complicated Winsock features from Visual Basic using an ActiveX control. The control was built in Visual C++ using the ActiveX project template. Most of the files generated by the template remain unchanged. The only changes are that the properties, methods, and events were added, which was easily accomplished through the Class Wizard. From there, a class named Winsock2 was added to encapsulate all Winsock calls, including the implementation of Ping itself. See the Source Files section for a discussion of each source file and its purpose.

Installation and Use

 * 1) Once you have extracted the files into a directory, start Visual C++ and load the project.
 * 2) Select Build, and then Rebuild All. This will compile the project and install the control into the system.
 * 3) From Visual Basic, add the control by going to the Project menu, clicking Components, and selecting "Ping ActiveX Control module."

Source Files
The following files are files associated with PingCtrl.exe:

Ping.mak:

The Visual C++ project makefile for building the Ping ActiveX Control.

Ping.h:

This is the main include file for the Ping ActiveX Control DLL. It includes other project-specific includes such as resource.h.

Ping.cpp:

This is the main source file that contains code for DLL initialization, termination and other bookkeeping.

Ping.rc:

This is a listing of the Microsoft Windows resources that the project uses. You can directly edit this file with the Visual C++ resource editor.

Ping.def:

This file contains information about the Ping ActiveX Control DLL that must be provided to run with Microsoft Windows.

Ping.odl:

This file contains the Object Description Language source code for the type library of your control.

Ping.ico:

This is the icon file for the application.

PingCtl.h:

This file contains the declaration of the CPingCtrl C++ class. This includes the definition of all control properties, events, and methods.

PingCtl.cpp:

This file contains the implementation of the CPingCtrl C++ class.

PingPpg.h:

This file contains the declaration of the CPingPropPage C++ class.

PingPpg.cpp:

This file contains the implementation of the CPingPropPage C++ class.

PingCtl.bmp:

This file contains a bitmap that a container uses to represent the CPingCtrl control when it appears on a tool palette. This bitmap is included by the main resource file Ping.rc.

stdafx.h and stdafx.cpp:

These files are used to build a precompiled header (PCH) file named stdafx.pch and a precompiled types (PCT) file named stdafx.obj.

resource.h:

This is the standard header file, which defines new resource IDs. The Visual C++ resource editor reads and updates this file.

WSAErrors.h:

This file contains textual strings for Winsock errors. The Win32 API FormatMessage does not work with Winsock errors.

Winsock2.h:

This file contains the Winsock2 class definition that contains the code to perform an ICMP request (Ping).

Winsock2.cpp:

This file contains the Winsock2 class implementation.

Properties, Methods, and Events
The Ping control has the following properties:

NumPackets:

Sets the number of ICMP packets to send to the remote host.

Timeout:

Specifies the timeout value (in milliseconds) for each ICMP packet.

RemoteHost:

Specifies the remote computer to ping.

AverageTime:

Read-only. Average response time for an ICMP packet sent to a host.

MaxTime:

Read-only. Maximum response time for an ICMP packet sent to a host.

MinTime:

Read-only. Minimum response time for an ICMP packet sent to a host.

The Ping control has the following methods:

Ping:

Initiates a ping request. This call will block for a maximum of NumPackets * Timeout seconds in order to wait for ICMP request completion.

The Ping control has the following events:

OnError:

This event is called when a Winsock error occurs in the Ping process.

OnEchoReply:

This event is called when an ICMP response packet is read. The response time (in milliseconds) for this packets is returned as a parameter.

OnEchoTimeout:

This event gets called when no ICMP response is received in the timeout period.

Sample
 Create a new Visual Basic project. Add the control by going to the Project menu, clicking Components, and selecting "Ping ActiveX Control module." Add the following controls to the form itself:  Text box (Text1). This is the remote host name. Text box (Text2). This is the timeout value used by Ping. Text box (Text3). This is the number of packets to send. Label (Label1). This is the minimum packet response time. Label (Label2). This is the maximum packet response time.</li> Label (Label3). This is the average packet response time.</li> Label (Label4). This is a packet count of the number of responses received.</li> Label (Label5). This is the number of timeouts received.</li> Command button (Command1). This executes the Ping request.</li> Ping control (Ping1). This is the Ping control.</li></ul> </li>  Add the following code to the form: <pre class="CODESAMP">     Private Sub Command1_Click

Label1.Caption = "0 ms" Label2.Caption = "0 ms" Label3.Caption = "0 ms" Label4.Caption = "0"

Ping1.RemoteHost = Text1.Text Ping1.Timeout = Text2.Text Ping1.NumPackets = Text3.Text

Form1.MousePointer = 11    ' Change the mouse to an hourglass. Ping1.Ping Form1.MousePointer = 0

Label7.Caption = Ping1.MinTime & " ms" Label8.Caption = Ping1.MaxTime & " ms" Label9.Caption = Ping1.AverageTime & " ms" End Sub

Private Sub Form_Load Label1.Caption = "0 ms" Label2.Caption = "0 ms" Label3.Caption = "0 ms" End Sub

Private Sub Ping1_OnError(ByVal Id As Integer, ByVal Description _                               As String) MsgBox Description End Sub

Private Sub Ping1_OnEchoReply(ByVal ResponseTime As Long) Label4.Caption = CStr(CLng(Label4.Caption) + 1) Debug.Print "Received an echo response: " & ResponseTime & " ms" End Sub

Private Sub Ping1_OnEchoTimeout Label5.Caption = CStr(CLng(Label5.Caption) + 1) End Sub </li> Run the Visual Basic application, and fill in Text1 with the remote computer that you want to ping. Fill in Text2 with the timeout value (a value of 1000 is good--this value is in milliseconds). Fill in Text3 with the number of packets to send to the remote host (a value of 5 to 10 is good). Click on Command1. After sending the appropriate number of packets, the labels will be filled in with the minimum response time, maximum response time, and average response time. If an error occurs, the OnError event handle sends a descriptive message.</li></ol>