|
The Internet Control Message Protocol (ICMP) library enables
your application to send and receive ICMP echo datagrams. These are
a special type of IP datagram which can be used to determine if a
remote host is reachable, as well as determine the amount of time
it takes for data to be exchanged with the local system. The ICMP
library can also be used to trace the route that data takes from
the local system to the remote host, which can be useful in
determining why a connection to a particular system may be
experiencing higher latency than normal.
The first step that your application must take is to initialize
the library and then create a handle for the client session. Unlike
many of the other libraries, there are no connection related
functions because ICMP uses IP datagrams rather than TCP streams.
The following functions are available for use by your
application:
IcmpInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other ICMP API functions.
IcmpCreateHandle
This function will return a handle to a client session which is
used in subsequent calls to the ICMP API. It is only required that
you call this function if you're using the lower level ICMP
functions to send and receive ICMP echo datagrams. The higher level
functions like IcmpEcho and IcmpTraceRoute do not require a
handle.
IcmpCloseHandle
Release the handle that was previously created by the call to
IcmpCreateHandle. Any memory allocated by the library on behalf of
the application is released and the datagram socket that was
created is closed.
IcmpUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Ping and TraceRoute
To determine if a remote host is reachable, your application can
send ICMP echo datagrams. You can also map the route between the
local system and the remote host by sending a series of echo
datagrams to each intermediate host. This is what the ping.exe and
tracert.exe command line utilities do, and you can emulate that
functionality in your own applications.
IcmpEcho
This is the simplest function you can use to send ICMP echo
datagrams. Specify the remote host, the size of the ICMP datagram
you want to send and the number of times you want to send it. The
function will return if the operation was successful along with
information such as the average number of milliseconds it took for
the datagram to be returned by the remote host. Note that it is not
required that you create a handle to use this function.
IcmpTraceRoute
This function will map the route that data packets take from your
local system to a remote host. Whenever you send data over the
Internet, that data is routed from one computer system to another
until it reaches its destination. This function returns statistical
information about each system that the data is routed through, and
the latency between that system and the local host.
IcmpSendEcho
This is a lower level function that will send a single ICMP echo
datagram. It can be used with applications that want to have more
direct control over the process of how the datagrams are sent, and
is typically used with asynchronous sessions.
IcmpRecvEcho
This is a lower level function that will receive a single ICMP echo
reply datagram that was returned by the remote host. Typically this
is used to receive datagrams that were sent in response to the
IcmpSendEcho function. The IcmpGetTripTime function can be used
after the function returns in order to check the amount of time it
took to receive the datagram.
|