다음을 통해 공유


Icmp6SendEcho2 함수(icmpapi.h)

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

구문

IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           sockaddr_in6           *SourceAddress,
  [in]           sockaddr_in6           *DestinationAddress,
  [in]           LPVOID                 RequestData,
  [in]           WORD                   RequestSize,
  [in, optional] PIP_OPTION_INFORMATION RequestOptions,
  [out]          LPVOID                 ReplyBuffer,
  [in]           DWORD                  ReplySize,
  [in]           DWORD                  Timeout
);

매개 변수

[in] IcmpHandle

Icmp6CreateFile에서 반환된 열린 핸들입니다.

[in, optional] Event

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

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

[in, optional] ApcRoutine

호출 스레드가 경고 가능한 스레드에 있고 ICMPv6 회신이 도착할 때 호출되는 루틴입니다. Windows Vista 이상에서는 이 매개 변수의 데이터 형식이 FARPROC가 아닌 PIO_APC_ROUTINE 강제로 PIO_APC_ROUTINE_DEFINED 정의해야 합니다.

Windows Server 2003 및 Windows XP에서는 이 매개 변수의 데이터 형식을 FARPROC로 강제 적용하기 위해 PIO_APC_ROUTINE_DEFINED 정의해서는 안 됩니다.

[in, optional] ApcContext

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

[in] SourceAddress

sockaddr 구조체의 형태로 에코 요청을 실행할 IPv6 원본 주소입니다.

[in] DestinationAddress

sockaddr 구조체의 형태로 에코 요청의 IPv6 대상 주소입니다.

[in] RequestData

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

[in] RequestSize

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

[in, optional] RequestOptions

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

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

참고 Windows Server 2003 및 Windows XP에서 RequestOptions 매개 변수는 선택 사항이 아니며 NULL이 아니어야 하며 TtlFlags 멤버만 사용됩니다.
 

[out] ReplyBuffer

요청에 대한 회신을 저장할 버퍼에 대한 포인터입니다. 반환 시 버퍼에는 ICMPV6_ECHO_REPLY 구조와 ICMPv6 에코 응답 응답 데이터의 메시지 본문이 포함됩니다. 버퍼는 하나 이상의 ICMPV6_ECHO_REPLY 구조체와 RequestSize 매개 변수에 지정된 데이터 바이트 수를 저장할 수 있을 만큼 커야 합니다. 또한 이 버퍼는 8바이트 이상의 데이터(ICMP 오류 메시지 크기)와 IO_STATUS_BLOCK 구조의 공간을 보유할 수 있을 만큼 커야 합니다.

[in] ReplySize

ReplyBuffer 매개 변수가 가리키는 회신 버퍼의 크기(바이트)입니다. 이 버퍼는 하나 이상의 ICMPV6_ECHO_REPLY 구조와 RequestSize 바이트 이상의 데이터를 저장할 수 있을 만큼 커야 합니다. 또한 이 버퍼는 8바이트 이상의 데이터(ICMP 오류 메시지 크기)와 IO_STATUS_BLOCK 구조의 공간을 보유할 수 있을 만큼 커야 합니다.

[in] Timeout

회신을 기다리는 시간(밀리초)입니다. 이 매개 변수는 Icmp6SendEcho2 함수를 동기적으로 호출하는 경우에만 사용됩니다. 따라서 ApcRoutine 또는 Event 매개 변수가 NULL이 아닌 경우 이 매개 변수는 사용되지 않습니다.

반환 값

동기적으로 호출되는 경우 은 ReplyBuffer에 수신되고 저장된 회신 수를 반환합니다.

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

(동기 또는 비동기) 회신 수 값이 0이면 확장 오류 정보에 대해 GetLastError를 호출합니다.

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

반환 코드 설명
ERROR_CALL_NOT_IMPLEMENTED
이 함수는 이 시스템에서 지원되지 않습니다.
ERROR_INSUFFICIENT_BUFFER
시스템 호출에 전달된 데이터 영역이 너무 작습니다. ReplySize 매개 변수가 ReplyBuffer 매개 변수가 가리키는 버퍼가 너무 작다는 것을 나타내는 경우 이 오류가 반환됩니다.
ERROR_INVALID_PARAMETER
매개 변수 중 하나가 잘못되었습니다. 이 오류는 IcmpHandle 매개 변수에 잘못된 핸들이 포함된 경우 반환됩니다.
ERROR_IO_PENDING
작업이 진행 중입니다. 이 값은 Icmp6SendEcho2 에 대한 성공적인 비동기 호출에 의해 반환되며 오류 표시가 아닙니다.
ERROR_NOT_ENOUGH_MEMORY
이 명령을 처리하는 데 메모리가 부족합니다.
ERROR_NOT_SUPPORTED
요청이 지원되지 않습니다. 이 오류는 로컬 컴퓨터에 IPv6 스택이 없는 경우 반환됩니다.
IP_BUF_TOO_SMALL
ReplySize 매개 변수에 지정된 ReplyBuffer의 크기가 너무 작습니다.
기타
FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

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

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

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

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

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

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

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

 

Windows Vista 이상에서는 ApcRoutine 이 가리키는 콜백 함수를 다음 구문을 사용하여 VOID 형식의 함수로 정의해야 합니다.

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

Windows Vista 이상에서는 콜백 함수에 전달된 매개 변수에 다음이 포함됩니다.

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

IO_STATUS_BLOCK 구조체는 Wdm.h 헤더 파일에 정의되어 있습니다.

IN ULONG Reserved 이 매개 변수는 예약되어 있습니다.
 

Windows Server 2003 및 Windows XP에서 ApcRoutine 매개 변수를 사용하여 Icmp6SendEcho2 함수를 비동기적으로 호출하는 모든 애플리케이션은 ApcRoutine 매개 변수의 데이터 형식을 PIO_APC_ROUTINE 대신 FARPROC로 강제 적용하는 PIO_APC_ROUTINE_DEFINED 정의하지 않아야 합니다.

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

typedef
VOID WINAPI
(*FARPROC) (
    IN PVOID ApcContext,
    );

Windows Server 2003 및 Windows XP에서 콜백 함수에 전달된 매개 변수에는 다음이 포함됩니다.

매개 변수 Description
IN PVOID ApcContext Icmp6SendEcho2 함수에 전달된 ApcContext 매개 변수입니다. 이 매개 변수는 애플리케이션에서 콜백 함수가 응답하는 Icmp6SendEcho2 요청을 식별하는 데 사용할 수 있습니다.
 

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

IPv4의 경우 IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2ExIcmpParseReplies 함수를 사용합니다.

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

요구 사항

요구 사항
지원되는 최소 클라이언트 Windows XP [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 icmpapi.h
라이브러리 Iphlpapi.lib
DLL Iphlpapi.dll

추가 정보

CreateEvent

CreateEventEx

이벤트 개체

GetLastError

ICMPV6_ECHO_REPLY

ICMP_ECHO_REPLY

IP_OPTION_INFORMATION

Icmp6CreateFile

Icmp6ParseReplies

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2

IcmpSendEcho2Ex

sockaddr