Ping and Traceroute control documentation

Front Peaks Consulting
Ping and Traceroute ActiveX Control

Version 4.4.1
November 7, 2001
(Documentation last updated November 7, 2001)

License Agreement	Methods	Properties (Read-Write)	Properties (Read-Only)
Events	Examples	Release Information
Front Peaks Consulting website

License Agreement

This agreement is a legally binding agreement between you and Front Peaks Consulting, the developer of the software program, which you are about to use. Use of this software is subject to the following software license agreement and the terms set forth below. Using this software indicates your acceptance of these terms. If you do not accept these terms in their entirety please uninstall the program.

This software is not "freeware" or considered in the "public domain". This program is Copyright 2000-2001 by Front Peaks Consulting. All Rights Reserved.

This software is being distributed as "trialware". You are granted a limited license to use this software for a "trial" period not to exceed thirty days. After the trial period, the program will become inoperable. If you wish to continue using this software, you must make a registration payment to the developer. Details about registration can be found at http://www.FrontPeaks.com/

You may freely distribute this program (or control) for evaluation to other persons, provided that no fees are charged for this service and that the product is distributed in the original, unaltered format.

You may not use, copy, rent, lease, sell, modify, de-compile, disassemble, otherwise reverse engineer, or transfer the licensed program except as provided in this agreement. Any such unauthorized use shall result in immediate and automatic termination of this license.

If this program is to be used on more than 1 computer system, or for distribution with a commercial software product, a corporate/development license must be purchased. Details about licensing can be found at http://www.frontpeaks.com/

Disclaimer
The developer, suppliers, distributors, or agents of this program will not be held responsible or liable in any way for hardware, software, or any damage related or unrelated to use, installation or presence of this program. No responsibility will be assumed for any financial loss as a result of use of this program. This software is distributed as-is without any expressed or implied warranties. The developer, suppliers, distributors, or agents cannot be held responsible for any damages before, after or during the use of this software, whether or not such damages were foreseeable and even if Front Peaks Consulting was advised that such damages were likely or possible.

Warranty
Front Peaks Consulting makes no representation or warranty of any kind with respect to this software or the results obtained or to be obtained from its use. Front Peaks Consulting does not warrant that your use of this software will be uninterrupted, error-free or virus-free. All warranties, expressed or implied, including the implied warranties of merchantability, fitness for a particular purpose and non-infringement are hereby expressly disclaimed. Front Peaks Consulting expressly disclaims any implied warranty that any other product (including without limitation any copy of the software you may subsequently use or purchase) will conform to the software provided to you under this agreement.

Methods
Method name	Description/Purpose
Ping	This method starts pinging the host specified in the InetHostname property, for the number of times specified in the PingNumberOfPackets property, or until cancelled. See the PingOutputReceived event for information on canceling.
PingContinuous	This method starts indefinitely pinging the host specified in the InetHostname property. See the PingOutputReceived event for information on canceling the pinging.
Traceroute	This method starts executing a traceroute to the host specified in the Hostname property. The operation will complete when the host specified has been reached, the operation has been canceled (see the TracerouteOutputReceived event for information on canceling), or if there have been hop failures equal to the number specified in the TracerouteMaximumHopFailures property.
ResolveIPAddressToHostname	This method will resolve the Internet IP addressed that is passed with it to an Internet hostname.
ResolveHostnameToIPAddress	This method will resolve the hostname that is passed with it to an Internet IP address.

Properties:Read-Write
Property name	Type	Description/Purpose	Default value	Allowed values
RegistrationCode	String	This property in conjunction with the RegistrationIdentification property need to be set with either a "trial" key, or a "permanent" key. These keys can be requested and/or purchased at www.FrontPeaks.com/software	Null	Valid "trial" or "permanent" keys.
RegistrationIdentification	String	This property in conjunction with the RegistrationCode property need to be set with either a "trial" key, or a "permanent" key. These keys can be requested and/or purchased at www.FrontPeaks.com/software	Null	Valid "trial" or "permanent" keys.
InetHostname	String	This contains the hostname or IP address that is to be used in the Ping, PingContinuous, or Traceroute methods.	127.0.0.1	Any valid hostname or IP address
InetMaximumHops	Integer	This is the maximum number of hops that will be allowed for a Ping, PingContinuous or Traceroute operation.	119	2 - 119
PingNumberOfPackets	Long	This is the number of times that the specified host will be pinged with the Ping method.	1	1 - 2147483647
TracerouteNumberOfPackets	Integer	This is the number of times that each host along the route will be pinged with the Traceroute method.	3	1 - 20
InetPacketSize	Integer	This is the number of bytes that will be sent in each ping that is sent out from the Ping, PingContinuous or Traceroute methods.	32	1 - 5000
InetTimeoutInMilliseconds	Long	This is the length of time that will be allowed before a timeout condition will occur from the Ping, PingContinuous or Traceroute methods.	2000	1 - 2147483647
DebugMode	Boolean	This is used for debugging purposes only on the direction of the vendor.	False	True/False
DebugFile	String	This is used for debugging purposes only on the direction of the vendor.	"C:\FPTRxxx.txt"	Any valid filename.
TracerouteResolveIPAddresses	Boolean	This determines if the IP addresses will be resolved to hostnames during a Traceroute operation.	True	True/False
TracerouteMaximumHopFailures	Integer	This is the maximum number of retries that a particular host in the path to the destination will be tried before determining a failure in a Traceroute operation.	5	1 - 32767
InetDelayBetweenPacketsInMilliseconds	Long	This is the number of milliseconds that will be waited between pings in a Ping, PingContinuous, or Traceroute operation.	100	100 - 2147483647
ASPMode	Boolean	This should be set to True if being used in a web (ASP) environment, as it will translate any vbCrLf (carriage return line feed) combinations to <BR> which serve as a line break for an HTML/web environment.	False	True/False

Properties: Read-Only
Property name	Type	Description/Purpose
ErrorText	String	This is a text representation of the Error property.
InetHostIPAddress	String	This contains the IP address of InetHostname which is resolved at the time of a Ping, PingContinuous, or Traceroute operation.
Error	Integer	This is the error code returned from the last operation. 1 - WINSOCK is not responding 2 - Unsupported WINSOCK version 3 - Minimum number of sockets not available 4 - Error closing the ICMP file handle 5 - Unable to resolve hostname 6 - Error cleaning up WINSOCK 7 - Error creating ICMP file handle
ExtendedError	Long	This contains an extended error code which may be returned from the last operation.
PingResults	String	This is a text representation of the results from a Ping operation. This is similar to the output of a DOS ping command. This is actually a combination of the PingResultsHeader + PingResultsBody + PingResultsFooter properties.
TracerouteResults	String	This is a text representation of the results from a Traceroute operation. This is similar to the output of a DOS tracert command. This is actually a combination of the TracerouteResultsHeader + TracerouteResultsBody + TracerouteResultsFooter properties.
PingResultsHeader	String	This is a text representation of the results from a Ping operation. This is similar to the beginning output of a DOS ping command.
PingResultsBody	String	This is a text representation of the results from a Ping operation. This is the detail of each packet sent, similar to the middle portion of a DOS ping command.
PingResultsFooter	String	This is a text representation of the results from a Ping operation. This is similar to the ending output of a DOS ping command.
TracerouteResultsHeader	String	This is a text representation of the results from a Traceroute operation. This is similar to the beginning output of a DOS tracert command.
TracerouteResultsBody	String	This is a text representation of the results from a Traceroute operation. This is similar to the detail of each hop between the source and destination, similar to the middle portion of a DOS tracert command.
TracerouteResultsFooter	String	This is a text representation of the results from a Traceroute operation. This is similar to the ending output of a DOS tracert command.
PingMinimum	Long	This is the lowest response time that was received from a single ping in a Ping or PingContinuous operation.
PingMaximum	Long	This is the highest response time that was received from a single ping in a Ping or PingContinuous operation.
PingAverage	Integer	This is the average response time that was received from all ping operations when the Ping or PingContinuous method was called.
PingsSent	Long	This is the number of pings that have been sent when the Ping or PingContinuous method was called.
PingsSuccessful	Long	This is the number of pings that have been successful when the Ping or PingContinuous method was called.
PingsFailed	Long	This is the number of pings that have not been successful when the Ping or PingContinuous method was called.
PingsFailedPercent	Integer	This is the percentage of pings that have not been successful when the Ping or PingContinuous method was called.
PingsSuccessfulPercent	Integer	This is the percentage of pings that have been successful when the Ping or PingContinuous method was called.
PingLastResponse	String	This is the single line of output from the last single ping when the Ping or PingContinuous method was called.
PingLastResponseTime	Long	This was the response time, in milliseconds, from the last single ping when the Ping or PingContinuous method was called.
PingFullySuccessful	Boolean	If all pings from a Ping or PingContinuous operation were successful, the value will be True. If even a single ping failed, the value will be False.
PingPartiallySuccessful	Boolean	If at least one ping from a Ping or PingContinuous operation was successful, the value will be True. If all pings failed, the value will be False.
TracerouteSuccessful	Boolean	If the Traceroute operation was successful, the value will be True. If the destination was not reached, the value will be False.
Version	String	This returns the version of this control.
TracerouteLastResponse	String	This returns the single line of output from the last hop that was returned when the Traceroute method was called.
RegistrationStatus	String	This contains information regarding the status of registration of this control. The combination of the RegistrationCode and RegistrationIdentification determine if this control will work or not. These keys can be requested and/or purchased at www.FrontPeaks.com/software

Events
Event name	Description/Purpose
PingOutputReceived	This event is fired whenever a single ping has been received from the Ping or PingContinuous methods. The first parameter sent to this event is strPingOutput which is the same as PingLastResponse and is read-only. The second parameter in this event is blnCancel and is read-write. If this value is set to True before returning from this event, the Ping or PingContinuous method will be stopped.
TracerouteOutputReceived	This event is fired whenever a single hop has been completed when using the Traceroute method. The first parameter sent to this event is strTracerouteOutput which is the same as TracerouteLastResponse and is read-only. The second parameter in this event is blnCancel and is read-write. If this value is set to True before returning from this event, the Traceroute method will be stopped.

Examples
Method	Example
Ping	PingTraceroute1.InetHostname = "www.cisco.com" PingTraceroute1.Ping If PingTraceroute1.PingsSuccessful Then Debug.Print "Ping was successful!" Debug.Print PingTraceroute1.PingResults Else Debug.Print "Ping failed" Debug.Print "Error(" & PingTraceroute1.Error & ") " & PingTraceroute1.ErrorText End If
PingContinuous	PingTraceroute1.InetHostname = "www.cisco.com" PingTraceroute1.PingContinuous Debug.Print "done!" Private Sub PingTraceroute1_PingOutputReceived(ByVal strPingOutput As String, blnPingCancel As Boolean) Static intCounter As Integer Call subRegistrationInformation intCounter = intCounter + 1 If intCounter > 4 blnPingCancel = True Debug.Print strPingOutput End Sub
Traceroute	PingTraceroute1.InetHostname = "www.cisco.com" PingTraceroute1.Traceroute If PingTraceroute1.TracerouteSuccessful Then Debug.Print "Traceroute was successful!" Debug.Print PingTraceroute1.TracerouteResults Else Debug.Print "Traceroute failed" Debug.Print "Error(" & PingTraceroute1.Error & ") " & PingTraceroute1.ErrorText End If
ResolveIPAddressToHostname	strIP = "198.133.219.29" Debug.Print strIP & " is " & PingTraceroute1.ResolveIPAddressToHostname(strIP)
ResolveHostnameToIPAddress	strHost = "www.cisco.com" Debug.Print strHost & " is " & PingTraceroute1.ResolveHostnameToIPAddress(strHost)
Download examples (Included is a Visual Basic project, an example VBScript file, and an ASP file)

Release Information
Version/Date	Information
4.1.1 Feb 17, 2001	Initial public release
4.3.4 Jun 19, 2001	BUG FIX: This version corrected problems in the processing of trial keys. The date routines would not process trial keys correctly if the Windows Regional Date settings were not set to English (United States). NOTE: If you have a permanent registration key for 4.1.1, there is no reason to use version 4.3.4 as there is no change in functionality other than the processing of trial keys.
4.4.1 Nov 7, 2001	BUG FIX: If specifying a InetPacketSize ~> 135 the control could receive a runtime error or a Buffer too small error message in the Ping/Traceroute output. BUG FIX: During a Traceroute function, if one hop was fully unsuccessful, the control tried the same hop again. This was an inappropriate assumption on our part. There are some reasons that a router along the way may not respond such as improper implementations of ICMP functions on routers and gateways. The net effect of this inappropriate assumption would be that if a single router doesn't reply to an ICMP request for whatever reason, the traceroute will entirely fail even though a valid path exists to the host. The control has been corrected to go on to the next hop regardless of the success or failure of the previous hop. Thanks to the information at Arachnaut's Lair for clearing this up. BUG FIX: A run-time error could occur when resolving an IP to a hostname. This was only reported when running in the VB IDE, but it could occur under other circumstances as well. CHANGE: Reduced the maximum allowed InetPacketSize to 5000 due to programming constraints and to reduce the usefulness of this tool as a vehicle for DOS (denial of service) attacks.

Go here for the most up to date documentation