The IcmpSendEcho function sends an IPv4 ICMP echo request and returns any echo response replies. The call returns when the time-out has expired or the reply buffer is filled.
DWORD IcmpSendEcho( HANDLE IcmpHandle, IPAddr DestinationAddress, LPVOID RequestData, WORD RequestSize, PIP_OPTION_INFORMATION RequestOptions, LPVOID ReplyBuffer, DWORD ReplySize, DWORD Timeout );
The open handle returned by the IcmpCreateFile function.
The IPv4 destination address of the echo request, in the form of an IPAddr structure.
A pointer to a buffer that contains data to send in the request.
The size, in bytes, of the request data buffer pointed to by the RequestData parameter.
This parameter may be NULL if no IP header options need to be specified.
A buffer to hold any replies to the echo request. Upon return, the buffer contains an array of ICMP_ECHO_REPLY structures followed by the options and data for the replies. The buffer should be large enough to hold at least one ICMP_ECHO_REPLY structure plus RequestSize bytes of data.
The allocated size, in bytes, of the reply buffer. The buffer should be large enough to hold at least one ICMP_ECHO_REPLY structure plus RequestSize bytes of data.
This buffer should also be large enough to also hold 8 more bytes of data (the size of an ICMP error message).
The time, in milliseconds, to wait for replies.
The IcmpSendEcho function returns the number of ICMP_ECHO_REPLY structures stored in the ReplyBuffer. The status of each reply is contained in the structure. If the return value is zero, call GetLastError for additional error information.
If the function fails, the extended error code returned by GetLastError can be one of the following values.
||The data area passed to a system call is too small. This error is returned if the ReplySize parameter indicates that the buffer pointed to by the ReplyBuffer parameter is too small.|
||An invalid parameter was passed to the function. This error is returned if the IcmpHandle parameter contains an invalid handle. This error can also be returned if the ReplySize parameter specifies a value less than the size of an ICMP_ECHO_REPLY structure.|
||Not enough memory is available to complete the operation.|
||The request is not supported. This error is returned if no IPv4 stack is on the local computer.|
||The size of the ReplyBuffer specified in the ReplySize parameter was too small.|
||Use FormatMessage to obtain the message string for the returned error.|
The IcmpSendEcho function send an ICMP echo request to the specified address and returns the number of replies received and stored in ReplyBuffer. The IcmpSendEcho function is a synchronous function and returns after waiting for the time specified in the Timeout parameter for a response. If the return value is zero, call GetLastError for extended error information.
The IcmpSendEcho2 and IcmpSendEcho2Ex functions are enhanced version of IcmpSendEcho that support asynchronous operation. The IcmpSendEcho2Ex function also allows the source IP address to be specified. This feature is useful on computers with multiple network interfaces.
The IcmpSendEcho function is exported from the Icmp.dll on Windows 2000. The IcmpSendEcho function is exported from the Iphlpapi.dll on Windows XP and later. Windows version checking is not recommended to use this function. Applications requiring portability with this function across Windows 2000, Windows XP, Windows Server 2003 and later Windows versions should not statically link to either the Icmp.lib or the Iphlpapi.lib file. Instead, the application should check for the presence of IcmpSendEcho in the Iphlpapi.dll with calls to LoadLibrary and GetProcAddress. Failing that, the application should check for the presence of IcmpSendEcho in the Icmp.dll with calls to LoadLibrary and GetProcAddress.
Note that the include directive for Iphlpapi.h header file must be placed before the Icmpapi.h header file.
The following example sends an ICMP echo request to the IP address specified on the command line and prints the information received from the first response.
#include <winsock2.h> #include <iphlpapi.h> #include <icmpapi.h> #include <stdio.h>
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|
|DLL||Iphlpapi.dll on Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP; Icmp.dll on Windows 2000 Server and Windows 2000 Professional|