| |
| INT WINAPI IcmpTraceRoute(
|
| |
LPCTSTR lpszHostName, |
|
| |
UINT nMaxHops, |
|
| |
DWORD dwTimeout, |
|
| |
DWORD dwReserved, |
|
| |
LPICMPTRACE lpTrace, |
|
| |
LPDWORD lpdwSize |
|
| );
|
The IcmpTraceRoute function sends a series of ICMP echo
datagrams to trace the route taken from the local system to the
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.
- nMaxHops
- An unsigned integer which specifies the maximum number of
routers the datagram will be forwarded through (the number of hops)
to the remote host. The minimum value is 1 and the maximum value is
255. It is recommended that most applications specify a value of at
least 30.
- dwTimeout
- An unsigned integer which specifies the number of milliseconds
the function will wait for a response to an echo datagram.
- dwReserved
- A reserved parameter. This value should always be zero.
- lpTrace
- A pointer to an array of ICMPTRACE
structures which will contain information about each intermediate
host between the local and remote system. The number of structures
must be at least the same as the maximum number of hops specified
by the nMaxHops parameter. To determine the total number of
bytes that must be allocated for the structure array, this
parameter can be passed as NULL and the total size will be returned
in the lpdwSize parameter.
- lpdwSize
- A pointer to an unsigned integer which should be initialized to
the size of the ICMPTRACE array passed to the function. If the
lpTrace parameter is NULL, the function will calculate the
size of the array buffer that must be allocated and return that
value. If both the lpTrace and lpdwSize parameters
are NULL, no statistical information about the intermediate hosts
will be collected.
Return Value
If the function succeeds, the return value is the number of
intermediate hosts between the local and remote system. If the
function fails, the return value is ICMP_ERROR. To get extended
error information, call IcmpGetLastError.
Remarks
The IcmpTraceRoute function sends a series of ICMP echo
datagrams to the specified host, adjusting the time-to-live value
to determine the intermediate hosts that route the packet. The
function returns the number of hops to the remote host.
It is important to note that the failure of an intermediate host
to respond to an ICMP echo datagram may not indicate a problem with
the remote system. Systems can 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
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csicmav7.lib.
See Also
IcmpCreateHandle, IcmpEcho, IcmpRecvEcho, IcmpResolveAddress, IcmpSendEcho, IcmpSetTimeToLive
|
|