IcmpSendEcho 함수(icmpapi.h)

아티클
08/24/2023

IcmpSendEcho 함수는 IPv4 ICMP 에코 요청을 보내고 모든 에코 응답 응답을 반환합니다. 제한 시간이 만료되었거나 회신 버퍼가 채워지면 호출이 반환됩니다.

구문

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

매개 변수

[in] IcmpHandle

IcmpCreateFile 함수에서 반환된 열린 핸들입니다.

[in] DestinationAddress

IPAddr 구조체 형식의 에코 요청의 IPv4 대상 주소입니다.

[in] RequestData

요청에 보낼 데이터가 포함된 버퍼에 대한 포인터입니다.

[in] RequestSize

RequestData 매개 변수가 가리키는 요청 데이터 버퍼의 크기(바이트)입니다.

[in, optional] RequestOptions

요청에 대한 IP 헤더 옵션( IP_OPTION_INFORMATION 구조체 형식)에 대한 포인터입니다. 64비트 플랫폼에서 이 매개 변수는 IP_OPTION_INFORMATION32 구조체의 형식입니다.

IP 헤더 옵션을 지정할 필요가 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

[out] ReplyBuffer

에코 요청에 대한 모든 회신을 저장할 버퍼입니다. 반환 시 버퍼에는 ICMP_ECHO_REPLY 구조의 배열과 회신에 대한 옵션 및 데이터가 포함됩니다. 버퍼는 하나 이상의 ICMP_ECHO_REPLY 구조와 RequestSize 바이트 이상의 데이터를 저장할 수 있을 만큼 커야 합니다.

[in] ReplySize

회신 버퍼의 할당된 크기(바이트)입니다. 버퍼는 하나 이상의 ICMP_ECHO_REPLY 구조와 RequestSize 바이트 이상의 데이터를 저장할 수 있을 만큼 커야 합니다.

또한 이 버퍼는 8바이트 이상의 데이터(ICMP 오류 메시지의 크기)를 보유할 수 있을 만큼 커야 합니다.

[in] Timeout

회신을 기다리는 시간(밀리초)입니다.

반환 값

IcmpSendEcho 함수는 ReplyBuffer에 저장된 ICMP_ECHO_REPLY 구조체의 수를 반환합니다. 각 회신의 상태 구조에 포함됩니다. 반환 값이 0이면 GetLastError 를 호출하여 추가 오류 정보를 확인합니다.

함수가 실패하면 GetLastError 에서 반환된 확장 오류 코드가 다음 값 중 하나일 수 있습니다.

반환 코드	설명
ERROR_INSUFFICIENT_BUFFER	시스템 호출에 전달된 데이터 영역이 너무 작습니다. ReplySize 매개 변수가 ReplyBuffer 매개 변수가 가리키는 버퍼가 너무 작다는 것을 나타내는 경우 이 오류가 반환됩니다.
ERROR_INVALID_PARAMETER	잘못된 매개 변수가 함수에 전달되었습니다. 이 오류는 IcmpHandle 매개 변수에 잘못된 핸들이 포함된 경우 반환됩니다. ReplySize 매개 변수가 ICMP_ECHO_REPLY 구조체의 크기보다 작은 값을 지정하는 경우에도 이 오류가 반환될 수 있습니다.
ERROR_NOT_ENOUGH_MEMORY	메모리가 부족 하 여 작업을 완료할 수 없습니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 로컬 컴퓨터에 IPv4 스택이 없으면 반환됩니다.
IP_BUF_TOO_SMALL	ReplySize 매개 변수에 지정된 ReplyBuffer의 크기가 너무 작습니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

IcmpSendEcho 함수는 지정된 주소로 ICMP 에코 요청을 보내고 ReplyBuffer에 수신 및 저장된 회신 수를 반환합니다. IcmpSendEcho 함수는 동기 함수이며 응답에 대한 Timeout 매개 변수에 지정된 시간을 기다린 후 를 반환합니다. 반환 값이 0이면 GetLastError 를 호출하여 확장된 오류 정보를 확인합니다.

IcmpSendEcho2 및 IcmpSendEcho2Ex 함수는 비동기 작업을 지원하는 IcmpSendEcho의 향상된 버전입니다. IcmpSendEcho2Ex 함수를 사용하면 원본 IP 주소를 지정할 수도 있습니다. 이 기능은 여러 네트워크 인터페이스가 있는 컴퓨터에서 유용합니다.

IPv6의 경우 Icmp6CreateFile, Icmp6SendEcho2 및 Icmp6ParseReplies 함수를 사용합니다.

IcmpSendEcho 함수는 Windows 2000의 Icmp.dll 내보냅니다. IcmpSendEcho 함수는 Windows XP 이상의 Iphlpapi.dll 내보냅니다. 이 함수를 사용하려면 Windows 버전 검사를 사용하지 않는 것이 좋습니다. Windows 2000, Windows XP, Windows Server 2003 이상 Windows 버전에서 이 기능을 사용하여 이식성이 필요한 애플리케이션은 Icmp.lib 또는 Iphlpapi.lib 파일에 정적으로 연결해서는 안 됩니다. 대신 애플리케이션은 LoadLibrary 및 GetProcAddress를 호출하여Iphlpapi.dllIcmpSendEcho가 있는지 검사 합니다. 실패하면 애플리케이션이 LoadLibrary 및 GetProcAddress를 호출하여Icmp.dllIcmpSendEcho가 있는지 검사 합니다.

Iphlpapi.h 헤더 파일에 대한 include 지시문은 Icmpapi.h 헤더 파일 앞에 배치해야 합니다.

예제

다음 예제에서는 명령줄에 지정된 IP 주소로 ICMP 에코 요청을 보내고 첫 번째 응답에서 받은 정보를 출력합니다.

#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;
}

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	icmpapi.h
라이브러리	Iphlpapi.lib
DLL	Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP의 Iphlpapi.dll. Windows 2000 Server 및 Windows 2000 Professional의 Icmp.dll