IcmpSendEcho function (icmpapi.h)

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.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
  [in]           HANDLE                 IcmpHandle,
  [in]           IPAddr                 DestinationAddress,
  [in]           LPVOID                 RequestData,
  [in]           WORD                   RequestSize,
  [in, optional] PIP_OPTION_INFORMATION RequestOptions,
  [out]          LPVOID                 ReplyBuffer,
  [in]           DWORD                  ReplySize,
  [in]           DWORD                  Timeout
);

Parameters

[in] IcmpHandle

The open handle returned by the IcmpCreateFile function.

[in] DestinationAddress

The IPv4 destination address of the echo request, in the form of an IPAddr structure.

[in] RequestData

A pointer to a buffer that contains data to send in the request.

[in] RequestSize

The size, in bytes, of the request data buffer pointed to by the RequestData parameter.

[in, optional] RequestOptions

A pointer to the IP header options for the request, in the form of an IP_OPTION_INFORMATION structure. On a 64-bit platform, this parameter is in the form for an IP_OPTION_INFORMATION32 structure.

This parameter may be NULL if no IP header options need to be specified.

[out] ReplyBuffer

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.

[in] ReplySize

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).

[in] Timeout

The time, in milliseconds, to wait for replies.

Return value

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.

Remarks

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.

For IPv6, use the Icmp6CreateFile, Icmp6SendEcho2, and Icmp6ParseReplies functions.

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.

Examples

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>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

int __cdecl main(int argc, char **argv)  {

    // Declare and initialize variables
    
    HANDLE hIcmpFile;
    unsigned long ipaddr = INADDR_NONE;
    DWORD dwRetVal = 0;
    char SendData[32] = "Data Buffer";
    LPVOID ReplyBuffer = NULL;
    DWORD ReplySize = 0;
    
    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IP address\n", argv[0]);
        return 1;
    }

    ipaddr = inet_addr(argv[1]);
    if (ipaddr == INADDR_NONE) {
        printf("usage: %s IP address\n", argv[0]);
        return 1;
    }
    
    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE) {
        printf("\tUnable to open handle.\n");
        printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
        return 1;
    }    

    ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
    ReplyBuffer = (VOID*) malloc(ReplySize);
    if (ReplyBuffer == NULL) {
        printf("\tUnable to allocate memory\n");
        return 1;
    }    
    
    
    dwRetVal = IcmpSendEcho(hIcmpFile, ipaddr, SendData, sizeof(SendData), 
        NULL, ReplyBuffer, ReplySize, 1000);
    if (dwRetVal != 0) {
        PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY)ReplyBuffer;
        struct in_addr ReplyAddr;
        ReplyAddr.S_un.S_addr = pEchoReply->Address;
        printf("\tSent icmp message to %s\n", argv[1]);
        if (dwRetVal > 1) {
            printf("\tReceived %ld icmp message responses\n", dwRetVal);
            printf("\tInformation from the first response:\n"); 
        }    
        else {    
            printf("\tReceived %ld icmp message response\n", dwRetVal);
            printf("\tInformation from this response:\n"); 
        }    
        printf("\t  Received from %s\n", inet_ntoa( ReplyAddr ) );
        printf("\t  Status = %ld\n", 
            pEchoReply->Status);
        printf("\t  Roundtrip time = %ld milliseconds\n", 
            pEchoReply->RoundTripTime);
    }
    else {
        printf("\tCall to IcmpSendEcho failed.\n");
        printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
        return 1;
    }
    return 0;
}    
    

Requirements

See also

GetLastError

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex