|
|
| INT IcmpEcho(
|
|
|
LPCTSTR
lpszHostName, |
|
|
|
|
UINT
nIterations, |
|
|
|
|
UINT
nPacketSize, |
|
|
|
|
DWORD
dwTimeout, |
|
|
|
|
DWORD
dwReserved, |
|
|
|
|
LPICMPTIME
lpTime |
|
|
| );
|
The IcmpEcho function 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 null-terminated 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 32 bytes and the maximum
size is 65,535 bytes. It is recommended that most applications use
the miniumum size of 32 bytes for this parameter.
- dwTimeout
- An unsigned integer which specifies the number of milliseconds
the function will wait for a response to an echo datagram. A value
of zero causes the function to wait indefinitely.
- dwReserved
- A reserved parameter. This value should always be zero.
- 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 function succeeds, the return value is the number of
replies received from the remote host. If the function fails, the
return value is ICMP_ERROR. To get extended error information, call
IcmpGetLastError.
Remarks
The IcmpEcho function sends a series of ICMP echo
datagrams to the specified host, providing a simplified interface
for pinging a remote system. If the function 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 function 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 echo datagrams is limited to privileged
users. Non-administrator users will receive an error if they
attempt to use this function. On Windows NT it is possible to
disable this security check by creating or modifying the system
registry. Microsoft Knowledge Base article 195445 has additional
information and instructions for making this change.
Requirements
Client: Requires Windows Vista, Windows XP or Windows
2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or
Windows 2000 Server.
Header: Include cstools6.h.
Library: Use csicmav6.lib.
See Also
IcmpCreateHandle, IcmpGetTripTime, IcmpRecvEcho, IcmpSendEcho, IcmpTraceRoute
|
|