IcmpSendEcho 関数 (icmpapi.h)
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構造体の配列が含まれます。 バッファーは、少なくとも 1 つの ICMP_ECHO_REPLY 構造体と RequestSize バイトのデータを保持するのに十分な大きさにする必要があります。
[in] ReplySize
応答バッファーの割り当てられたサイズ (バイト単位)。 バッファーは、少なくとも 1 つの ICMP_ECHO_REPLY 構造体と RequestSize バイトのデータを保持するのに十分な大きさにする必要があります。
また、このバッファーは、さらに 8 バイトのデータ (ICMP エラー メッセージのサイズ) を保持するのに十分な大きさにする必要があります。
[in] Timeout
応答を待機する時間 (ミリ秒単位)。
戻り値
IcmpSendEcho 関数は、ReplyBuffer に格納されているICMP_ECHO_REPLY構造体の数を返します。 各応答の状態は、 構造体に含まれています。 戻り値が 0 の場合は、追加のエラー情報として GetLastError を呼び出します。
関数が失敗した場合、 GetLastError によって返される拡張エラー コードには、次のいずれかの値を指定できます。
| リターン コード | 説明 |
|---|---|
|
システム コールに渡したデータ領域が小さすぎます。 このエラーは、 ReplySize パラメーターが ReplyBuffer パラメーターが指すバッファーが小さすぎることを示す場合に返されます。 |
|
無効なパラメーターが関数に渡されました。 このエラーは、 IcmpHandle パラメーターに無効なハンドルが含まれている場合に返されます。 このエラーは、 ReplySize パラメーターが ICMP_ECHO_REPLY 構造体のサイズより小さい値を指定している場合にも返されます。 |
|
メモリ不足のため、操作を完了できません。 |
|
要求はサポートされていません。 このエラーは、ローカル コンピューターに IPv4 スタックがない場合に返されます。 |
|
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.dll に IcmpSendEcho が存在するためにチェックする必要があります。 失敗すると、アプリケーションは、LoadLibrary と GetProcAddress の呼び出しを使用して、Icmp.dll に IcmpSendEcho が存在することをチェックする必要があります。
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 |
| Library | Iphlpapi.lib |
| [DLL] | Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP で Iphlpapi.dll。Windows 2000 Server と Windows 2000 Professional での Icmp.dll |