Export (0) Print
Expand All
Expand Minimize

IcmpSendEcho function

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


DWORD IcmpSendEcho(
  _In_      HANDLE IcmpHandle,
  _In_      IPAddr DestinationAddress,
  _In_      LPVOID RequestData,
  _In_      WORD RequestSize,
  _In_opt_  PIP_OPTION_INFORMATION RequestOptions,
  _Out_     LPVOID ReplyBuffer,
  _In_      DWORD ReplySize,
  _In_      DWORD Timeout
);

Parameters

IcmpHandle [in]

The open handle returned by the IcmpCreateFile function.

DestinationAddress [in]

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

RequestData [in]

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

RequestSize [in]

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

RequestOptions [in, optional]

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.

ReplyBuffer [out]

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.

On a 64-bit platform, upon return the buffer contains an array of ICMP_ECHO_REPLY32 structures followed by the options and data for the replies.

ReplySize [in]

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. On a 64-bit platform, The buffer should be large enough to hold at least one ICMP_ECHO_REPLY32 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).

Timeout [in]

The time, in milliseconds, to wait for replies.

Return value

The IcmpSendEcho function returns the number of ICMP_ECHO_REPLY or ICMP_ECHO_REPLY32 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.

Return codeDescription
ERROR_INSUFFICIENT_BUFFER

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.

ERROR_INVALID_PARAMETER

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 or ICMP_ECHO_REPLY32 structure.

ERROR_NOT_ENOUGH_MEMORY

Not enough memory is available to complete the operation.

ERROR_NOT_SUPPORTED

The request is not supported. This error is returned if no IPv4 stack is on the local computer.

IP_BUF_TOO_SMALL

The size of the ReplyBuffer specified in the ReplySize parameter was too small.

Other

Use FormatMessage to obtain the message string for the returned error.

 

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Icmpapi.h

Library

Iphlpapi.lib

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

See also

GetLastError
ICMP_ECHO_REPLY
ICMP_ECHO_REPLY32
Icmp6CreateFile
Icmp6ParseReplies
Icmp6SendEcho2
IcmpCloseHandle
IcmpCreateFile
IcmpParseReplies
IcmpSendEcho2
IcmpSendEcho2Ex
IP_OPTION_INFORMATION
IP_OPTION_INFORMATION32
IPAddr

 

 

Community Additions

ADD
Show:
© 2014 Microsoft