Ping ActiveX COM Object, Version 1.2

Programmers Guide and Reference

Features

SPing is a light weight ActiveX COM object which can be used in Windows-based applications on Windows-NT and Windows-95.

A new feature in version 1.1 is Resolve method and richer error handling.

It can be used to:

The size of the binary object: 109K, no dependencies on other dlls.

Properties

PropertyTypeRead/WriteDefault ValueDescription
RemoteHost BSTR R/W 127.0.0.1 Remote Host to connect to
Blocking Bool R/W False Boolean set to true if blocking operation for name resolution required This property can be only bet set to True in the demo version of Ping ActiveX.
PacketSize Long R/W 64 Size of the request packet sent to the host
DoHostResolutionBool R/W False Boolean which determines if reverse name resolution should be done for IP-style address
Timeout Long R/W 1000 Timeout for non-blocking host resolution and waiting for the reply to a packet.
RemoteHostIP BSTR R IP String resolved from the property RemoteHost
RemoteHostName BSTR R Symbolic Host Name resolved from the property RemoteHost
Delay Long R Delay in reply received from host.
State Short R Current state of object.
ErrorString BSTR R Error String corresponding to the parameter passed.

Methods

MethodDescription
void DoPing() Perform a Ping operation, i.e. send an echo request to the remote host.
void Resolve() Resolve hostname or reverse resolve IP address, depending on the value of RemoteHost property. If RemoteHost is dot delimited format, such as 156.15.15.15, reverse host name resolution is done, otherwise hostname resolution is performed. .
void Cancel() Cancel a host resolution or Ping operation. Host resolution can be canceled only in non-blocking mode
void Reset() Reset the state of the control. Current operation is canceled and WSACleanup and WSAStartup are called internally. Usage is similar to cancel.

How DoPing works

If the RemoteHost property changed since last DoPing request, host resolution may be initiated.

The DoPing method initiates Host resolution or Reverse host resolution first depending on DoResolveHost and RemoteHost properties. If RemoteHost is an IP address, no host resolution happens, unless DoResolveHost is true. If RemoteHost is a symbolic name, host resolution is initiated in either case.

After DoPing returns, ReplyCode property reflects wheter the ping was successful (reply received, value 0) or not:
ReplyValueDescription
destUnreachable 3 Destination unreachable. This happens if wrong IP string is specified: e.g.: "127" (incomplete string)
timeExceeded 11Time exceeded
paramError 12 Error in passed parameter, e.g. when IP = "127.0.0."
retCantResolveAddress 100 Cannot resolved address (host doesn't exist or DNS is not available
retTimedOutResolving 101 Specified timeout expired while attempting to resolve name or do reverse name resolution on an IP address.
retTimedOut 102 Specified timeout expired (given in Timeout property), without receiving reply to request.
retNotInit 103 Control not initialized (this indicates an internal error)
retCantSend 104 Can't send an echo request
retCanceled 105 Canceled by the user

Non-blocking mode (Supported only in full release, not in demo version)

When calling ping in non-blocking (asynchronous mode), before proceding with echo request, this method waits for host resolution if it was initiated while peeking messages and therefore yielding CPU to the current thread.

Blocking mode

When calling ping in blocking (synchronous mode), before proceding with echo request, this method blocks on host resolution. The current thread is blocked until the resolution is finished. This may cause delays with non-responsive UI mainly if the host can't be resolved due to wrong symbolic address or unavailability of DNS server.

How Cancel works

Cancel method is effective only in non-blocking mode when host resolution happens. for the "waiting of echo part" of DoPing request, Cancel is effective in both blocking and non-blocking mode.

Interaction with Java

A Java Wrapper called Pinglet for this class was developed using Visual J++. This java applet has identical functionality with the COM object except for non-blocking support, which is not really needed in Java's multithreading model. Blocking property is not available in Pinglet and is forced to be true, opposite to the SPing's default value.

Differences with COM object:

  • Only blocking mode supported. Async mode causes crashes with Java.
  • Since Pinglet is running in a separate thread, it is possible to enquire the State at any time from VB script, e.g. from a timer event.
  • Pinglet has minimal user interface, it displays result of the request in the standard command-line based ping format. Properties of Pinglet can be used, however, to provide graphics-based display or the store the information from multiple requests.
  • Pinglet has a property Interval which determines interval at which echo requests will be performed. This is different from Timeout, which determines how long the object will wait for a reply.

    • Registration


    Before your download ShineSoft ping, please give us your e-mail and specify if you'd like to receive notification about updates and bug fixes.
    E-mail:
    I'd like to be notified about future updates to this product

    Sample Code

    Error Handling

    Errorhandling is done via error return codes in HRESULT, which in VB is translated into an exception, with error code and string information.

    The following errors may be returned:
    Error (winerror.h)ValueDescription
    ERROR_INVALID_PARAMETER 87 Invalid param passed to the function. E.g. for PacketSize, only up to 2048 is allowed
    ERROR_BUSY 170A method was called when it was inappropriate because another method was executing. In the Java wrapper, automatic synchronization is done, so this error never occurs.

    Additional error information may be retrieved from ReplyCode property after DoPing successfully returned (BUSY exception wasn't raised).

    System Requirements.

    The Ping ActiveX control, sping.dll requires Win32 (Windows 95 or Windows NT), it works only with ActiveX capable browser. It was tested with IE 3.01 and 3.02. It doesn't need additional files or dlls, only wsock32.dll for name resolution and icmp.dll for ICMP requests and replies.

    The Java Applet (pinglet.class) requires ping.dll. Ping ActiveX needs to run Java Typelib conversion utility: "Java Type Library Wizard" (JT.EXE) that comes with VJ++. The applet has to be "trusted" in order to use a COM object.

    Known Problems

  • ping.dll does not have a certified signature at this point, so you'll get warning from IE when the object is loaded.
  • Timer resolution is not 1ms, so the times indicating delay of the reply of the host in Delay property are inaccurate.
  • Direct and reverse name resolution is done only when the value of RemoteHost property changes. That way if you change DoHostResolution property, name may still not be resolved.

    • Licensing

    Please read the license before using the product. The trial release of SPing can be used for non-commercial purposes. For other purposes, you need to purchase the final release after a 30-day trial period expires.

    To order a full-featured release version of SPing or other products of ShineSoft Systems, please e-mail your request to info@shinesoft.com

    Please e-mail comments and suggestions on components to support@shinesoft.com