IcmpSendEcho2Ex 함수(icmpapi.h)

아티클
08/24/2023

IcmpSendEcho2Ex 함수는 IPv4 ICMP 에코 요청을 보내고 즉시(Event 또는 ApcRoutine이 NULL이 아닌 경우) 반환하거나 지정된 시간 제한 후에 를 반환합니다. ReplyBuffer에는 ICMP 응답(있는 경우)이 포함됩니다.

구문

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           IPAddr                 SourceAddress,
  [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, optional] Event

ICMP 응답이 도착할 때마다 신호를 받을 이벤트입니다. 이 매개 변수를 지정하면 유효한 이벤트 개체에 대한 핸들이 필요합니다. CreateEvent 또는 CreateEventEx 함수를 사용하여 이 이벤트 개체를 만듭니다.

이벤트 사용에 대한 자세한 내용은 이벤트 개체를 참조하세요.

[in, optional] ApcRoutine

호출 스레드가 경고 가능한 스레드에 있고 ICMP 회신이 도착할 때 호출되는 루틴입니다. 이 매개 변수의 데이터 형식이 FARPROC가 아닌 PIO_APC_ROUTINE 적용하려면 PIO_APC_ROUTINE_DEFINED 정의해야 합니다.

[in, optional] ApcContext

ICMP 응답이 도착하거나 오류가 발생할 때마다 ApcRoutine 매개 변수에 지정된 콜백 루틴에 전달되는 선택적 매개 변수입니다.

[in] SourceAddress

에코 요청을 실행할 IPv4 원본 주소입니다. 이 주소는 IPAddr 구조체 형식입니다.

[in] DestinationAddress

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

[in] RequestData

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

[in] RequestSize

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

[in, optional] RequestOptions

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

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

[out] ReplyBuffer

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

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

[in] ReplySize

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

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

[in] Timeout

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

반환 값

동기적으로 호출되면 IcmpSendEcho2Ex 함수는 ReplyBuffer에 수신되고 저장된 회신 수를 반환합니다. 반환 값이 0이면 GetLastError 를 호출하여 확장된 오류 정보를 확인합니다.

비동기적으로 호출되면 IcmpSendEcho2Ex 함수는 ERROR_IO_PENDING 반환하여 작업이 진행 중임을 나타냅니다. 나중에 이벤트 매개 변수 신호에 지정된 이벤트 또는 ApcRoutine 매개 변수의 콜백 함수가 호출될 때 결과를 검색할 수 있습니다.

반환 값이 0이면 GetLastError 를 호출하여 확장된 오류 정보를 확인합니다.

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

반환 코드	설명
ERROR_INVALID_PARAMETER	잘못된 매개 변수가 함수에 전달되었습니다. 이 오류는 IcmpHandle 매개 변수에 잘못된 핸들이 포함된 경우 반환됩니다. ReplySize 매개 변수가 ICMP_ECHO_REPLY 구조체의 크기보다 작은 값을 지정하는 경우에도 이 오류가 반환될 수 있습니다.
ERROR_IO_PENDING	작업이 진행 중입니다. 이 값은 IcmpSendEcho2Ex 에 대한 성공적인 비동기 호출에 의해 반환되며 오류 표시가 아닙니다.
ERROR_NOT_ENOUGH_MEMORY	메모리가 부족 하 여 작업을 완료할 수 없습니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 로컬 컴퓨터에 IPv4 스택이 없으면 반환됩니다.
IP_BUF_TOO_SMALL	ReplySize 매개 변수에 지정된 ReplyBuffer의 크기가 너무 작습니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

IcmpSendEcho2Ex 함수는 Windows Server 2008 이상에서 사용할 수 있습니다.

IcmpSendEcho2Ex 함수는 사용자가 ICMP 요청을 실행할 IPv4 원본 주소를 지정할 수 있는 IcmpSendEcho2 함수의 향상된 버전입니다. IcmpSendEcho2Ex 함수는 컴퓨터에 여러 네트워크 인터페이스가 있는 경우에 유용합니다.

ApcRoutine 또는 Event 매개 변수가 NULL인 경우 IcmpSendEcho2Ex 함수는 동기적으로 호출됩니다. 동기적으로 호출되는 경우 반환 값에는 Timeout 매개 변수에 지정된 시간을 기다린 후 ReplyBuffer에 수신되고 저장된 회신 수가 포함됩니다. 반환 값이 0이면 GetLastError 를 호출하여 확장된 오류 정보를 확인합니다.

ApcRoutine 또는 Event 매개 변수를 지정하면 IcmpSendEcho2Ex 함수가 비동기적으로 호출됩니다. 비동기적으로 호출되면 ReplyBuffer 및 ReplySize 매개 변수가 응답을 수락해야 합니다. ICMP 응답 데이터는 제공된 ReplyBuffer 에 복사되고 애플리케이션이 신호를 보내거나( Event 매개 변수가 지정된 경우) 콜백 함수가 호출됩니다( ApcRoutine 매개 변수가 지정된 경우). 애플리케이션은 IcmpParseReplies 함수를 사용하여 ReplyBuffer 매개 변수가 가리키는 데이터를 구문 분석해야 합니다.

Event 매개 변수를 지정하면 IcmpSendEcho2Ex 함수가 비동기적으로 호출됩니다. Event 매개 변수에 지정된 이벤트는 ICMP 응답이 도착할 때마다 신호를 보냅니다. CreateEvent 함수를 사용하여 이 이벤트 개체를 만듭니다.

ApcRoutine 매개 변수를 지정하면 IcmpSendEcho2Ex 함수가 비동기적으로 호출됩니다. ApcRoutine 매개 변수는 사용자 정의 콜백 함수를 가리킵니다. ApcRoutine 매개 변수에 지정된 콜백 함수는 ICMP 응답이 도착할 때마다 호출됩니다. ApcRoutine 매개 변수에 지정된 콜백 함수의 호출이 serialize됩니다.

Event 및 ApcRoutine 매개 변수를 모두 지정하면 ICMP 응답이 도착할 때마다 Event 매개 변수에 지정된 이벤트가 신호를 수신하지만 ApcRoutine 매개 변수에 지정된 콜백 함수는 무시됩니다.

ApcRoutine 매개 변수를 사용하여 IcmpSendEcho2Ex 함수를 비동기적으로 호출하는 모든 애플리케이션은 ApcRoutine 매개 변수의 데이터 형식이 FARPROC가 아닌 PIO_APC_ROUTINE 강제로 PIO_APC_ROUTINE_DEFINED 정의해야 합니다.

참고PIO_APC_ROUTINE_DEFINEDIcmpapi.h 헤더 파일이 포함되기 전에 정의해야 합니다.

ApcRoutine에서 가리키는 콜백 함수는 다음 구문을 사용하여 VOID 형식의 함수로 정의되어야 합니다.

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

콜백 함수에 전달되는 매개 변수는 다음과 같습니다.

매개 변수	Description
IN PVOID ApcContext	IcmpSendEcho2Ex 함수에 전달된 ApcContext 매개 변수입니다. 이 매개 변수는 애플리케이션에서 콜백 함수가 응답하는 IcmpSendEcho2Ex 요청을 식별하는 데 사용할 수 있습니다.
IN PIO_STATUS_BLOCK IoStatusBlock	IO_STATUS_BLOCK 대한 포인터입니다. 이 변수에는 최종 완료 상태 및 작업에 대한 정보가 포함됩니다. 회신에서 실제로 수신된 바이트 수는 IO_STATUS_BLOCK 구조체의 정보 멤버에 반환됩니다. IO_STATUS_BLOCK 구조체는 Wdm.h 헤더 파일에 정의되어 있습니다.
IN ULONG Reserved	이 매개 변수는 예약되어 있습니다.

ApcRoutine 매개 변수에 지정된 콜백 함수는 IcmpSendEcho2Ex 함수를 호출하는 애플리케이션과 동일한 프로세스에서 구현되어야 합니다. 콜백 함수가 별도의 DLL에 있는 경우 IcmpSendEcho2Ex 함수를 호출하기 전에 DLL을 로드해야 합니다.

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

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

요구 사항


지원되는 최소 클라이언트	WINDOWS Vista SP1 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	icmpapi.h
라이브러리	Iphlpapi.lib
DLL	Iphlpapi.dll