IcmpSendEcho2 함수(icmpapi.h)
IcmpSendEcho2 함수는 IPv4 ICMP 에코 요청을 보내고 즉시(Event 또는 ApcRoutine이 NULL이 아닌 경우) 반환하거나 지정된 시간 제한 후에 를 반환합니다. ReplyBuffer에는 ICMP 에코 응답(있는 경우)이 포함됩니다.
구문
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[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
호출 스레드가 경고 가능한 스레드에 있고 ICMPv4 회신이 도착할 때 호출되는 루틴입니다. 이 매개 변수의 데이터 형식이 FARPROC가 아닌 PIO_APC_ROUTINE 적용하려면 PIO_APC_ROUTINE_DEFINED 정의해야 합니다.
[in, optional] ApcContext
ICMP 응답이 도착하거나 오류가 발생할 때 ApcRoutine 매개 변수에 지정된 콜백 루틴에 전달되는 선택적 매개 변수입니다(최대 한 번).
[in] DestinationAddress
IPAddr 구조체 형식의 에코 요청의 IPv4 대상입니다.
[in] RequestData
요청에 보낼 데이터가 포함된 버퍼에 대한 포인터입니다.
[in] RequestSize
RequestData 매개 변수가 가리키는 요청 데이터 버퍼의 크기(바이트)입니다.
[in, optional] RequestOptions
요청에 대한 IP 헤더 옵션( IP_OPTION_INFORMATION 구조체 형식)에 대한 포인터입니다.
IP 헤더 옵션을 지정할 필요가 없는 경우 이 매개 변수는 NULL 일 수 있습니다.
[out] ReplyBuffer
요청에 대한 회신을 저장할 버퍼에 대한 포인터입니다. 반환 시 버퍼에는 ICMP_ECHO_REPLY 구조의 배열과 옵션 및 데이터가 포함됩니다.
버퍼는 하나 이상의 ICMP_ECHO_REPLY 구조와 RequestSize 바이트 및 추가 8바이트의 데이터(ICMP 오류 메시지 크기)를 포함할 수 있을 만큼 커야 합니다.
[in] ReplySize
회신 버퍼의 할당된 크기(바이트)입니다.
버퍼는 하나 이상의 ICMP_ECHO_REPLY 구조와 RequestSize 바이트 및 추가 8바이트의 데이터(ICMP 오류 메시지 크기)를 포함할 수 있을 만큼 커야 합니다.
[in] Timeout
회신을 기다리는 시간(밀리초)입니다.
반환 값
동기적으로 호출되면 IcmpSendEcho2 함수는 ReplyBuffer에 수신되고 저장된 회신 수를 반환합니다. 반환 값이 0이면 확장 오류 정보에 대해 GetLastError를 호출합니다.
비동기적으로 호출되면 IcmpSendEcho2 함수는 0을 반환합니다. GetLastError에 대한 후속 호출은 작업이 진행 중임을 나타내는 확장 오류 코드 ERROR_IO_PENDING 반환합니다. 나중에 이벤트 매개 변수 신호에 지정된 이벤트 또는 ApcRoutine 매개 변수의 콜백 함수가 호출될 때 결과를 검색할 수 있습니다.
반환 값이 0이면 확장 오류 정보에 대해 GetLastError를 호출합니다.
함수가 실패하면 GetLastError 에서 반환된 확장 오류 코드가 다음 값 중 하나일 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
| ERROR_INVALID_PARAMETER | 잘못된 매개 변수가 함수에 전달되었습니다. 이 오류는 IcmpHandle 매개 변수에 잘못된 핸들이 포함된 경우 반환됩니다. ReplySize 매개 변수가 ICMP_ECHO_REPLY 구조체의 크기보다 작은 값을 지정하는 경우에도 이 오류가 반환될 수 있습니다. |
| ERROR_IO_PENDING | 작업이 진행 중입니다. 이 값은 IcmpSendEcho2에 대한 성공적인 비동기 호출에 의해 반환되며 오류 표시가 아닙니다. |
| ERROR_NOT_ENOUGH_MEMORY | 메모리가 부족 하 여 작업을 완료할 수 없습니다. |
| ERROR_NOT_SUPPORTED | 요청이 지원되지 않습니다. 이 오류는 로컬 컴퓨터에 IPv4 스택이 없으면 반환됩니다. |
| IP_BUF_TOO_SMALL | ReplySize 매개 변수에 지정된 ReplyBuffer의 크기가 너무 작습니다. |
| 기타 | FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
ApcRoutine 또는 이벤트 매개 변수가 NULL인 경우 IcmpSendEcho2 함수는 동기적으로 호출됩니다. 동기적으로 호출되는 경우 반환 값에는 Timeout 매개 변수에 지정된 시간을 기다린 후 ReplyBuffer에 수신되고 저장된 회신 수가 포함됩니다. 반환 값이 0이면 확장 오류 정보에 대해 GetLastError를 호출합니다.
ApcRoutine 또는 Event 매개 변수를 지정하면 IcmpSendEcho2 함수가 비동기적으로 호출됩니다. 비동기적으로 호출되는 경우 응답을 수락하려면 ReplyBuffer 및 ReplySize 매개 변수가 필요합니다. ICMP 응답 데이터가 제공된 ReplyBuffer 에 복사되고 애플리케이션이 신호를 보내거나( Event 매개 변수가 지정된 경우) 콜백 함수가 호출됩니다( ApcRoutine 매개 변수가 지정된 경우). 애플리케이션은 IcmpParseReplies 함수를 사용하여 ReplyBuffer 매개 변수가 가리키는 데이터를 구문 분석해야 합니다.
Event 매개 변수를 지정하면 IcmpSendEcho2 함수가 비동기적으로 호출됩니다. Event 매개 변수에 지정된 이벤트는 ICMP 응답이 도착하면 신호를 한 번 이상 보냅니다. CreateEvent 또는 CreateEventEx 함수를 사용하여 이 이벤트 개체를 만듭니다.
ApcRoutine 매개 변수를 지정하면 IcmpSendEcho2 함수가 비동기적으로 호출됩니다. ApcRoutine 매개 변수는 사용자 정의 콜백 함수를 가리킵니다. ApcRoutine 매개 변수에 지정된 콜백 함수는 ICMP 응답이 도착하면 (최대 한 번) 호출됩니다. ApcRoutine 매개 변수에 지정된 콜백 함수의 호출이 serialize됩니다.
Event 매개 변수와 ApcRoutine 매개 변수를 모두 지정하면 ICMP 응답이 도착할 때 Event 매개 변수에 지정된 이벤트는 신호(최대 한 번)되지만 ApcRoutine 매개 변수에 지정된 콜백 함수는 무시됩니다.
ApcRoutine 매개 변수를 사용하여 IcmpSendEcho2 함수를 비동기적으로 호출하는 모든 애플리케이션은 ApcRoutine 매개 변수의 데이터 형식이 FARPROC가 아닌 PIO_APC_ROUTINE 강제로 PIO_APC_ROUTINE_DEFINED정의해야 합니다.
참고
Icmpapi.h 헤더 파일이 포함되기 전에 PIO_APC_ROUTINE_DEFINED 정의해야 합니다.
ApcRoutine에서 가리키는 콜백 함수는 다음 구문을 사용하여 VOID 형식의 함수로 정의되어야 합니다.
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
콜백 함수에 전달된 매개 변수는 다음과 같습니다.
| 매개 변수 | Description |
|---|---|
| IN PVOID ApcContext | IcmpSendEcho2 함수에 전달된 AppContext 매개 변수입니다. 이 매개 변수는 애플리케이션에서 콜백 함수가 응답하는 IcmpSendEcho2 요청을 식별하는 데 사용할 수 있습니다. |
| IN PIO_STATUS_BLOCK IoStatusBlock | IO_STATUS_BLOCK 대한 포인터입니다. 이 변수에는 최종 완료 상태 및 작업에 대한 정보가 포함됩니다. 회신에서 실제로 받은 바이트 수는 IO_STATUS_BLOCK 구조체의 정보 멤버에 반환됩니다. IO_STATUS_BLOCK 구조체는 헤더 파일에 정의되어 있습니다 Wdm.h. |
| IN ULONG Reserved | 이 매개 변수는 예약되어 있습니다. |
ApcRoutine 매개 변수에 지정된 콜백 함수는 IcmpSendEcho2 함수를 호출하는 애플리케이션과 동일한 프로세스에서 구현되어야 합니다. 콜백 함수가 별도의 DLL에 있는 경우 IcmpSendEcho2 함수를 호출하기 전에 DLL을 로드해야 합니다.
IcmpSendEcho2 함수는 에서 내보냅니다Iphlpapi.dll.
IPv6의 경우 Icmp6CreateFile, Icmp6SendEcho2 및 Icmp6ParseReplies 함수를 사용합니다.
헤더 파일에 대한 Iphlpapi.h include 지시문을 헤더 파일의 Icmpapi.h 앞에 배치해야 합니다.
예제
다음 예제에서는 IcmpSendEcho2 함수를 동기적으로 호출합니다. 이 예제에서는 명령줄에 지정된 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;
DWORD dwError = 0;
char SendData[] = "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;
}
// Allocate space for a single reply.
ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
ReplyBuffer = (VOID *) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory for reply buffer\n");
return 1;
}
dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
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 ", pEchoReply->Status);
switch (pEchoReply->Status) {
case IP_DEST_HOST_UNREACHABLE:
printf("(Destination host was unreachable)\n");
break;
case IP_DEST_NET_UNREACHABLE:
printf("(Destination Network was unreachable)\n");
break;
case IP_REQ_TIMED_OUT:
printf("(Request timed out)\n");
break;
default:
printf("\n");
break;
}
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
} else {
printf("Call to IcmpSendEcho2 failed.\n");
dwError = GetLastError();
switch (dwError) {
case IP_BUF_TOO_SMALL:
printf("\tReplyBufferSize too small\n");
break;
case IP_REQ_TIMED_OUT:
printf("\tRequest timed out\n");
break;
default:
printf("\tExtended error returned: %ld\n", dwError);
break;
}
return 1;
}
return 0;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | 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 |