ホーム › NetworkManagement.IpHelper › IcmpSendEcho

IcmpSendEcho

関数

指定先へICMPエコー要求を送信し応答を受信する。

DLLIPHLPAPI.dll呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// IPHLPAPI.dll
#include <windows.h>

DWORD IcmpSendEcho(
    HANDLE IcmpHandle,
    DWORD DestinationAddress,
    void* RequestData,
    WORD RequestSize,
    IP_OPTION_INFORMATION* RequestOptions,   // optional
    void* ReplyBuffer,
    DWORD ReplySize,
    DWORD Timeout
);

パラメーター

名前	型	方向	説明
IcmpHandle	HANDLE	in	IcmpCreateFile 関数が返したオープン済みのハンドルです。
DestinationAddress	DWORD	in	エコー要求の宛先となる IPv4 アドレスです。IPAddr 構造体の形式で指定します。
RequestData	void*	in	要求で送信するデータを格納したバッファへのポインターです。
RequestSize	WORD	in	RequestData パラメーターが指す要求データバッファのサイズ(バイト単位)です。
RequestOptions	IP_OPTION_INFORMATION*	inoptional	要求に使用する IP ヘッダーオプションへのポインターです。IP_OPTION_INFORMATION 構造体の形式で指定します。64 ビットプラットフォームでは、このパラメーターは IP_OPTION_INFORMATION32 構造体の形式になります。 IP ヘッダーオプションを指定する必要がない場合、このパラメーターは NULL でかまいません。
ReplyBuffer	void*	out	エコー要求に対する応答を保持するバッファです。戻り時には、このバッファに ICMP_ECHO_REPLY 構造体の配列が格納され、その後に応答のオプションとデータが続きます。バッファは、少なくとも 1 つの ICMP_ECHO_REPLY 構造体に加えて RequestSize バイトのデータを保持できる大きさが必要です。
ReplySize	DWORD	in	応答バッファに割り当てられたサイズ(バイト単位)です。バッファは、少なくとも 1 つの ICMP_ECHO_REPLY 構造体に加えて RequestSize バイトのデータを保持できる大きさが必要です。また、このバッファは、さらに 8 バイト(ICMP エラーメッセージのサイズ)のデータも保持できる大きさが必要です。
Timeout	DWORD	in	応答を待機する時間(ミリ秒単位)です。

戻り値の型: DWORD

公式ドキュメント

IcmpSendEcho 関数は、IPv4 ICMP エコー要求を送信し、返されたエコー応答を取得します。タイムアウトが経過するか、応答バッファが満杯になると、この呼び出しは戻ります。

戻り値

                    <b>IcmpSendEcho</b> 関数は、<i>ReplyBuffer</i> に格納された

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 を使用して、返されたエラーに対応するメッセージ文字列を取得してください。

解説(Remarks)

IcmpSendEcho 関数は、指定されたアドレスに ICMP エコー要求を送信し、受信して ReplyBuffer に格納された応答の数を返します。IcmpSendEcho 関数は同期関数であり、Timeout パラメーターで指定された時間だけ応答を待機した後に戻ります。戻り値が 0 の場合は、 GetLastError を呼び出して拡張エラー情報を取得してください。

IcmpSendEcho2 関数および IcmpSendEcho2Ex 関数は、非同期操作をサポートする IcmpSendEcho の拡張版です。IcmpSendEcho2Ex 関数では、送信元 IP アドレスを指定することもできます。この機能は、複数のネットワークインターフェイスを備えたコンピューターで役立ちます。

IPv6 の場合は、Icmp6CreateFile、Icmp6SendEcho2、Icmp6ParseReplies の各関数を使用してください。

IcmpSendEcho 関数は、Windows 2000 では Icmp.dll からエクスポートされます。Windows XP 以降では、IcmpSendEcho 関数は 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;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// IPHLPAPI.dll
#include <windows.h>

DWORD IcmpSendEcho(
    HANDLE IcmpHandle,
    DWORD DestinationAddress,
    void* RequestData,
    WORD RequestSize,
    IP_OPTION_INFORMATION* RequestOptions,   // optional
    void* ReplyBuffer,
    DWORD ReplySize,
    DWORD Timeout
);

[DllImport("IPHLPAPI.dll", SetLastError = true, ExactSpelling = true)]
static extern uint IcmpSendEcho(
    IntPtr IcmpHandle,   // HANDLE
    uint DestinationAddress,   // DWORD
    IntPtr RequestData,   // void*
    ushort RequestSize,   // WORD
    IntPtr RequestOptions,   // IP_OPTION_INFORMATION* optional
    IntPtr ReplyBuffer,   // void* out
    uint ReplySize,   // DWORD
    uint Timeout   // DWORD
);

<DllImport("IPHLPAPI.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function IcmpSendEcho(
    IcmpHandle As IntPtr,   ' HANDLE
    DestinationAddress As UInteger,   ' DWORD
    RequestData As IntPtr,   ' void*
    RequestSize As UShort,   ' WORD
    RequestOptions As IntPtr,   ' IP_OPTION_INFORMATION* optional
    ReplyBuffer As IntPtr,   ' void* out
    ReplySize As UInteger,   ' DWORD
    Timeout As UInteger   ' DWORD
) As UInteger
End Function

' IcmpHandle : HANDLE
' DestinationAddress : DWORD
' RequestData : void*
' RequestSize : WORD
' RequestOptions : IP_OPTION_INFORMATION* optional
' ReplyBuffer : void* out
' ReplySize : DWORD
' Timeout : DWORD
Declare PtrSafe Function IcmpSendEcho Lib "iphlpapi" ( _
    ByVal IcmpHandle As LongPtr, _
    ByVal DestinationAddress As Long, _
    ByVal RequestData As LongPtr, _
    ByVal RequestSize As Integer, _
    ByVal RequestOptions As LongPtr, _
    ByVal ReplyBuffer As LongPtr, _
    ByVal ReplySize As Long, _
    ByVal Timeout As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

IcmpSendEcho = ctypes.windll.iphlpapi.IcmpSendEcho
IcmpSendEcho.restype = wintypes.DWORD
IcmpSendEcho.argtypes = [
    wintypes.HANDLE,  # IcmpHandle : HANDLE
    wintypes.DWORD,  # DestinationAddress : DWORD
    ctypes.POINTER(None),  # RequestData : void*
    ctypes.c_ushort,  # RequestSize : WORD
    ctypes.c_void_p,  # RequestOptions : IP_OPTION_INFORMATION* optional
    ctypes.POINTER(None),  # ReplyBuffer : void* out
    wintypes.DWORD,  # ReplySize : DWORD
    wintypes.DWORD,  # Timeout : DWORD
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('IPHLPAPI.dll')
IcmpSendEcho = Fiddle::Function.new(
  lib['IcmpSendEcho'],
  [
    Fiddle::TYPE_VOIDP,  # IcmpHandle : HANDLE
    -Fiddle::TYPE_INT,  # DestinationAddress : DWORD
    Fiddle::TYPE_VOIDP,  # RequestData : void*
    -Fiddle::TYPE_SHORT,  # RequestSize : WORD
    Fiddle::TYPE_VOIDP,  # RequestOptions : IP_OPTION_INFORMATION* optional
    Fiddle::TYPE_VOIDP,  # ReplyBuffer : void* out
    -Fiddle::TYPE_INT,  # ReplySize : DWORD
    -Fiddle::TYPE_INT,  # Timeout : DWORD
  ],
  -Fiddle::TYPE_INT)

#[link(name = "iphlpapi")]
extern "system" {
    fn IcmpSendEcho(
        IcmpHandle: *mut core::ffi::c_void,  // HANDLE
        DestinationAddress: u32,  // DWORD
        RequestData: *mut (),  // void*
        RequestSize: u16,  // WORD
        RequestOptions: *mut IP_OPTION_INFORMATION,  // IP_OPTION_INFORMATION* optional
        ReplyBuffer: *mut (),  // void* out
        ReplySize: u32,  // DWORD
        Timeout: u32  // DWORD
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("IPHLPAPI.dll", SetLastError = true)]
public static extern uint IcmpSendEcho(IntPtr IcmpHandle, uint DestinationAddress, IntPtr RequestData, ushort RequestSize, IntPtr RequestOptions, IntPtr ReplyBuffer, uint ReplySize, uint Timeout);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_IcmpSendEcho' -Namespace Win32 -PassThru
# $api::IcmpSendEcho(IcmpHandle, DestinationAddress, RequestData, RequestSize, RequestOptions, ReplyBuffer, ReplySize, Timeout)

#uselib "IPHLPAPI.dll"
#func global IcmpSendEcho "IcmpSendEcho" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; IcmpSendEcho IcmpHandle, DestinationAddress, RequestData, RequestSize, varptr(RequestOptions), ReplyBuffer, ReplySize, Timeout   ; 戻り値は stat
; IcmpHandle : HANDLE -> "sptr"
; DestinationAddress : DWORD -> "sptr"
; RequestData : void* -> "sptr"
; RequestSize : WORD -> "sptr"
; RequestOptions : IP_OPTION_INFORMATION* optional -> "sptr"
; ReplyBuffer : void* out -> "sptr"
; ReplySize : DWORD -> "sptr"
; Timeout : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "IPHLPAPI.dll"
#cfunc global IcmpSendEcho "IcmpSendEcho" sptr, int, sptr, int, var, sptr, int, int
; res = IcmpSendEcho(IcmpHandle, DestinationAddress, RequestData, RequestSize, RequestOptions, ReplyBuffer, ReplySize, Timeout)
; IcmpHandle : HANDLE -> "sptr"
; DestinationAddress : DWORD -> "int"
; RequestData : void* -> "sptr"
; RequestSize : WORD -> "int"
; RequestOptions : IP_OPTION_INFORMATION* optional -> "var"
; ReplyBuffer : void* out -> "sptr"
; ReplySize : DWORD -> "int"
; Timeout : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "IPHLPAPI.dll"
#cfunc global IcmpSendEcho "IcmpSendEcho" sptr, int, sptr, int, sptr, sptr, int, int
; res = IcmpSendEcho(IcmpHandle, DestinationAddress, RequestData, RequestSize, varptr(RequestOptions), ReplyBuffer, ReplySize, Timeout)
; IcmpHandle : HANDLE -> "sptr"
; DestinationAddress : DWORD -> "int"
; RequestData : void* -> "sptr"
; RequestSize : WORD -> "int"
; RequestOptions : IP_OPTION_INFORMATION* optional -> "sptr"
; ReplyBuffer : void* out -> "sptr"
; ReplySize : DWORD -> "int"
; Timeout : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。