次の方法で共有


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 によって返される拡張エラー コードには、次のいずれかの値を指定できます。

リターン コード 説明
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 の場合は、 Icmp6CreateFileIcmp6SendEcho2および Icmp6ParseReplies 関数を使用します。

IcmpSendEcho 関数は、Windows 2000 の Icmp.dll からエクスポートされます。 IcmpSendEcho 関数は、Windows XP 以降の Iphlpapi.dll からエクスポートされます。 この関数を使用する場合、Windows バージョン チェックは推奨されません。 Windows 2000、Windows XP、Windows Server 2003 以降の Windows バージョンで、この機能の移植性を必要とするアプリケーションは、 Icmp.lib または Iphlpapi.lib ファイルに静的にリンクしないでください。 代わりに、アプリケーションは、LoadLibraryGetProcAddress の呼び出しを使用して、Iphlpapi.dllIcmpSendEcho が存在するためにチェックする必要があります。 失敗すると、アプリケーションは、LoadLibraryGetProcAddress の呼び出しを使用して、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
Library Iphlpapi.lib
[DLL] Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP で Iphlpapi.dll。Windows 2000 Server と Windows 2000 Professional での Icmp.dll

関連項目

GetLastError

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex