| |
| INT Echo( |
| |
LPCTSTR lpszHostName, |
|
| |
UINT nIterations, |
|
| |
UINT nPacketSize, |
|
| |
DWORD dwTimeout, |
|
| |
LPICMPTIME lpTime |
|
| ); |
| INT Echo( |
| |
LPCTSTR lpszHostName, |
|
| |
LPICMPTIME lpTime |
|
| ); |
The Echo method sends one or more ICMP echo datagrams,
collecting information about the reliability and latency of a
connection between the local and remote host.
Parameters
- lpszHostName
- A pointer to a string which specifies the fully
qualified domain name of the remote host, or the IP address in
dotted notation.
- nIterations
- An unsigned integer value which specifies the number of echo
datagrams that will be sent to the remote host. The minimum value
for this parameter is 1 and the maximum value is 512.
- nPacketSize
- An unsigned integer value which specifies the size of the echo
datagram in bytes. The minimum size is 1 byte and the maximum
size is 65,535 bytes. It is recommended that most applications use
the minimum size of 32 bytes for this parameter.
- dwTimeout
- An unsigned integer which specifies the number of milliseconds
the method will wait for a response to an echo datagram.
- lpTime
- A pointer to an ICMPTIME structure
which will contain the minimum, maximum and average round trip
times for the echo datagrams sent and received.
Return Value
If the method succeeds, the return value is the number of replies
received from the remote host. If the method fails, the return value
is ICMP_ERROR. To get extended error information, call
GetLastError.
Remarks
The Echo method sends a series of ICMP echo datagrams to
the specified host, providing a simplified interface for pinging a
remote system. If the method returns the same value as the number of
iterations, then replies were received for all of the echo datagrams
that were sent. This would typically indicate that the client can
establish a reliable connection to the server; the values returned in
the ICMPTIME structure provide information on the latency between the
two hosts. Higher average time values would indicate greater latency
and reduced throughput between the systems. If the method returns a
value less than the specified number of iterations, this indicates
that replies were not received for one or more of the echo datagrams.
This may indicate that there are problems routing data between the
local and remote host. A return value of zero indicates that there
was no response to the echo datagrams. The remote host may not exist
or may not be available.
The failure for a host to respond to an ICMP echo datagram may not
indicate a problem with the remote system. In some cases, a router
between the local and remote host may be malfunctioning or discarding
the datagrams. Systems can also be configured to specifically ignore
ICMP echo datagrams and not respond to them; this is often a security
measure to prevent certain kinds of Denial of Service attacks.
The ability to send ICMP datagrams may be restricted to users with
administrative privileges, depending on the policies and configuration
of the local system. If you are unable to send or receive any ICMP
datagrams, it is recommended that you check the firewall settings and
any third-party security software that could impact the normal
operation of this component.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csicmv11.lib
See Also
CreateHandle,
GetTripTime,
RecvEcho, SendEcho,
TraceRoute
|
|