SAMPLE: PingCtrl.exe Uses Winsock2 Features from Visual Basic

ID: Q185726

The information in this article applies to:

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 Software Library: 

 ~ PingCtrl.exe (size: 46599 bytes)
For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base: 

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services
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

1. Create a new Visual Basic project.

2. Add the control by going to the Project menu, clicking Components, and 

   selecting "Ping ActiveX Control module."
3. 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.
   - Label (Label3). This is the average packet response time.
   - Label (Label4). This is a packet count of the number of responses
     received.
   - Label (Label5). This is the number of timeouts received.
   - Command button (Command1). This executes the Ping request.
   - Ping control (Ping1). This is the Ping control.
4. Add the following code to the form: 

      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
5. 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.

Notes

To implement Ping from a Winsock 2 application, you need to use raw sockets (that is, calling WSASocket with SOCK_RAW and IPPROTO_ICMP). Because of security concerns under Windows NT, only members of the Administrators group may create raw sockets. This also means that only members of the Administrators group may use the Ping control. If the error text "The requested address is a broadcast address, but the appropriate flag was not set" or error number 10013 is returned they indicate that the user does not have the proper credentials to create the raw socket. Windows 95 (with the Winsock 2 update) and Windows 98 do not have this limitation because they do not address the user security issue.

Additional query words: ping 

Keywords          : kbnetwork kbAPI kbNTOS400 kbSDKPlatform kbWinOS95 kbWinsock kbGrpNet 
Issue type        : kbinfo

Last Reviewed: July 31, 1998