---------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Windows NT 4.0
 - Microsoft Windows 95
 - Microsoft Windows 95 OEM Service Release version 2
---------------------------------------------------------------------

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

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. 