ホーム › NetworkManagement.IpHelper › Icmp6SendEcho2

Icmp6SendEcho2

関数

IPv6でICMPv6エコー要求を送信し応答を受信する。

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

シグネチャ

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

DWORD Icmp6SendEcho2(
    HANDLE IcmpHandle,
    HANDLE Event,   // optional
    PIO_APC_ROUTINE ApcRoutine,   // optional
    void* ApcContext,   // optional
    SOCKADDR_IN6* SourceAddress,
    SOCKADDR_IN6* DestinationAddress,
    void* RequestData,
    WORD RequestSize,
    IP_OPTION_INFORMATION* RequestOptions,   // optional
    void* ReplyBuffer,
    DWORD ReplySize,
    DWORD Timeout
);

パラメーター

名前	型	方向	説明
IcmpHandle	HANDLE	in	Icmp6CreateFile が返したオープン済みのハンドル。
Event	HANDLE	inoptional	ICMPv6 応答が到着するたびにシグナル状態になるイベント。このパラメーターを指定する場合は、有効なイベントオブジェクトへのハンドルが必要です。このイベントオブジェクトを作成するには、 CreateEvent または CreateEventEx 関数を使用します。イベントの使用方法の詳細については、Event Objects を参照してください。
ApcRoutine	PIO_APC_ROUTINE	inoptional	呼び出し元スレッドがアラート可能状態にあり、かつ ICMPv6 応答が到着したときに呼び出されるルーチン。Windows Vista 以降では、このパラメーターのデータ型を FARPROC ではなく PIO_APC_ROUTINE にするために PIO_APC_ROUTINE_DEFINED を定義する必要があります。 Windows Server 2003 および Windows XP では、このパラメーターのデータ型を FARPROC にするために PIO_APC_ROUTINE_DEFINED を定義してはなりません。
ApcContext	void*	inoptional	ICMPv6 応答が到着したとき、またはエラーが発生したときに、ApcRoutine パラメーターで指定したコールバックルーチンに渡される省略可能なパラメーター。
SourceAddress	SOCKADDR_IN6*	in	エコー要求を発行する IPv6 送信元アドレス。sockaddr 構造体の形式で指定します。
DestinationAddress	SOCKADDR_IN6*	in	エコー要求の IPv6 宛先アドレス。sockaddr 構造体の形式で指定します。
RequestData	void*	in	要求で送信するデータを格納したバッファーへのポインター。
RequestSize	WORD	in	RequestData パラメーターが指す要求データバッファーのサイズ(バイト単位)。
RequestOptions	IP_OPTION_INFORMATION*	inoptional	要求の IPv6 ヘッダーオプションへのポインター。IP_OPTION_INFORMATION 構造体の形式で指定します。64 ビットプラットフォームでは、このパラメーターは IP_OPTION_INFORMATION32 構造体の形式になります。 IP ヘッダーオプションを指定する必要がない場合、このパラメーターは NULL でかまいません。 Note Windows Server 2003 および Windows XP では、RequestOptions パラメーターは省略可能ではなく、NULL であってはなりません。また、Ttl および Flags メンバーのみが使用されます。
ReplyBuffer	void*	out	要求に対する応答を格納するバッファーへのポインター。戻り時には、このバッファーには ICMPV6_ECHO_REPLY 構造体に続いて、ICMPv6 エコー応答の応答データのメッセージ本文が格納されます。バッファーは、少なくとも 1 つの ICMPV6_ECHO_REPLY 構造体に加えて、RequestSize パラメーターで指定したバイト数のデータを格納できる十分な大きさが必要です。さらに、このバッファーは追加で 8 バイトのデータ(ICMP エラーメッセージのサイズ)と IO_STATUS_BLOCK 構造体の領域も格納できる大きさにする必要があります。
ReplySize	DWORD	in	ReplyBuffer パラメーターが指す応答バッファーのサイズ(バイト単位)。このバッファーは、少なくとも 1 つの ICMPV6_ECHO_REPLY 構造体に加えて、RequestSize バイトのデータを格納できる十分な大きさが必要です。さらに、このバッファーは追加で 8 バイトのデータ(ICMP エラーメッセージのサイズ)と IO_STATUS_BLOCK 構造体の領域も格納できる大きさにする必要があります。
Timeout	DWORD	in	応答を待機する時間(ミリ秒単位)。このパラメーターは、Icmp6SendEcho2 関数を同期的に呼び出した場合にのみ使用されます。したがって、ApcRoutine または Event パラメーターのいずれかが NULL でない場合、このパラメーターは使用されません。

戻り値の型: DWORD

公式ドキュメント

Icmp6SendEcho2 関数は IPv6 ICMPv6 エコー要求を送信し、(Event または ApcRoutine が非 NULL の場合は)即座に返るか、指定されたタイムアウト後に返ります。ReplyBuffer には、応答があれば IPv6 ICMPv6 エコー応答が格納されます。

戻り値

同期的に呼び出した場合、受信して ReplyBuffer に格納された応答の数を返します。

非同期的に呼び出した場合、ERROR_IO_PENDING を返すことで操作が進行中であることを示します。応答数の結果は、Event パラメーターで指定したイベントがシグナル状態になったとき、または ApcRoutine パラメーターで指定したコールバック関数が呼び出されたときに後から取得できます。

(同期または非同期の)応答数の値がゼロの場合は、拡張エラー情報を得るために 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 のサイズが小さすぎました。
Other	返されたエラーのメッセージ文字列を取得するには FormatMessage を使用します。

解説(Remarks)

ApcRoutine および Event パラメーターが NULL の場合、Icmp6SendEcho2 関数は同期的に呼び出されます。同期的に呼び出された場合、戻り値には、Timeout パラメーターで指定した時間だけ待機した後に受信して ReplyBuffer に格納された応答の数が含まれます。戻り値がゼロの場合は、拡張エラー情報を得るために GetLastError を呼び出します。

ApcRoutine または Event パラメーターのいずれかが指定された場合、Icmp6SendEcho2 関数は非同期的に呼び出されます。非同期的に呼び出された場合、応答を受け取るために ReplyBuffer および ReplySize パラメーターが必要です。ICMP 応答データは指定された ReplyBuffer にコピーされ、(Event パラメーターが指定されている場合は)アプリケーションにシグナルが送られるか、(ApcRoutine パラメーターが指定されている場合は)コールバック関数が呼び出されます。アプリケーションは、Icmp6ParseReplies 関数を使用して ReplyBuffer パラメーターが指すデータを解析する必要があります。

Event パラメーターが指定された場合、Icmp6SendEcho2 関数は非同期的に呼び出されます。Event パラメーターで指定したイベントは、ICMPv6 応答が到着するたびにシグナル状態になります。このイベントオブジェクトを作成するには CreateEvent 関数を使用します。

ApcRoutine パラメーターが指定された場合、Icmp6SendEcho2 関数は非同期的に呼び出されます。ApcRoutine パラメーターは、ユーザー定義のコールバック関数を指す必要があります。ApcRoutine パラメーターで指定したコールバック関数は、ICMPv6 応答が到着するたびに呼び出されます。ApcRoutine パラメーターで指定したコールバック関数の呼び出しは直列化されます。

Event パラメーターと ApcRoutine パラメーターの両方が指定された場合、ICMPv6 応答が到着するたびに Event パラメーターで指定したイベントがシグナル状態になりますが、ApcRoutine パラメーターで指定したコールバック関数は無視されます。

Windows Vista 以降では、ApcRoutine パラメーターを使用して Icmp6SendEcho2 関数を非同期的に呼び出すアプリケーションは、ApcRoutine パラメーターのデータ型を FARPROC ではなく PIO_APC_ROUTINE にするために PIO_APC_ROUTINE_DEFINED を定義する必要があります。

Note PIO_APC_ROUTINE_DEFINED は Icmpapi.h ヘッダーファイルをインクルードする前に定義する必要があります。

Windows Vista 以降では、ApcRoutine が指すコールバック関数は、VOID 型の関数として次の構文で定義する必要があります。

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

Windows Vista 以降では、コールバック関数に渡されるパラメーターは次のとおりです。

パラメーター	説明
IN PVOID ApcContext	Icmp6SendEcho2 関数に渡された ApcContext パラメーター。このパラメーターは、コールバック関数が応答している Icmp6SendEcho2 要求をアプリケーションが識別するために使用できます。
IN PIO_STATUS_BLOCK IoStatusBlock	IO_STATUS_BLOCK へのポインター。この変数には、操作の最終的な完了ステータスと情報が含まれます。応答で実際に受信したバイト数は、IO_STATUS_BLOCK 構造体の Information メンバーに返されます。 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 では、コールバック関数に渡されるパラメーターは次のとおりです。

パラメーター	説明
IN PVOID ApcContext	Icmp6SendEcho2 関数に渡された ApcContext パラメーター。このパラメーターは、コールバック関数が応答している Icmp6SendEcho2 要求をアプリケーションが識別するために使用できます。

ApcRoutine パラメーターで指定したコールバック関数は、Icmp6SendEcho2 関数を呼び出すアプリケーションと同じプロセス内に実装する必要があります。コールバック関数が別の DLL 内にある場合は、その DLL を Icmp6SendEcho2 関数を呼び出す前に読み込む必要があります。

IPv4 の場合は、IcmpCreateFile、IcmpSendEcho、IcmpSendEcho2、IcmpSendEcho2Ex、IcmpParseReplies の各関数を使用します。

Iphlpapi.h ヘッダーファイルのインクルードディレクティブは、Icmpapi.h ヘッダーファイルの前に配置する必要があることに注意してください。

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

各言語での呼び出し定義

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

DWORD Icmp6SendEcho2(
    HANDLE IcmpHandle,
    HANDLE Event,   // optional
    PIO_APC_ROUTINE ApcRoutine,   // optional
    void* ApcContext,   // optional
    SOCKADDR_IN6* SourceAddress,
    SOCKADDR_IN6* 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 Icmp6SendEcho2(
    IntPtr IcmpHandle,   // HANDLE
    IntPtr Event,   // HANDLE optional
    IntPtr ApcRoutine,   // PIO_APC_ROUTINE optional
    IntPtr ApcContext,   // void* optional
    IntPtr SourceAddress,   // SOCKADDR_IN6*
    IntPtr DestinationAddress,   // SOCKADDR_IN6*
    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 Icmp6SendEcho2(
    IcmpHandle As IntPtr,   ' HANDLE
    [Event] As IntPtr,   ' HANDLE optional
    ApcRoutine As IntPtr,   ' PIO_APC_ROUTINE optional
    ApcContext As IntPtr,   ' void* optional
    SourceAddress As IntPtr,   ' SOCKADDR_IN6*
    DestinationAddress As IntPtr,   ' SOCKADDR_IN6*
    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
' Event : HANDLE optional
' ApcRoutine : PIO_APC_ROUTINE optional
' ApcContext : void* optional
' SourceAddress : SOCKADDR_IN6*
' DestinationAddress : SOCKADDR_IN6*
' RequestData : void*
' RequestSize : WORD
' RequestOptions : IP_OPTION_INFORMATION* optional
' ReplyBuffer : void* out
' ReplySize : DWORD
' Timeout : DWORD
Declare PtrSafe Function Icmp6SendEcho2 Lib "iphlpapi" ( _
    ByVal IcmpHandle As LongPtr, _
    ByVal Event As LongPtr, _
    ByVal ApcRoutine As LongPtr, _
    ByVal ApcContext As LongPtr, _
    ByVal SourceAddress As LongPtr, _
    ByVal DestinationAddress As LongPtr, _
    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

Icmp6SendEcho2 = ctypes.windll.iphlpapi.Icmp6SendEcho2
Icmp6SendEcho2.restype = wintypes.DWORD
Icmp6SendEcho2.argtypes = [
    wintypes.HANDLE,  # IcmpHandle : HANDLE
    wintypes.HANDLE,  # Event : HANDLE optional
    ctypes.c_void_p,  # ApcRoutine : PIO_APC_ROUTINE optional
    ctypes.POINTER(None),  # ApcContext : void* optional
    ctypes.c_void_p,  # SourceAddress : SOCKADDR_IN6*
    ctypes.c_void_p,  # DestinationAddress : SOCKADDR_IN6*
    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')
Icmp6SendEcho2 = Fiddle::Function.new(
  lib['Icmp6SendEcho2'],
  [
    Fiddle::TYPE_VOIDP,  # IcmpHandle : HANDLE
    Fiddle::TYPE_VOIDP,  # Event : HANDLE optional
    Fiddle::TYPE_VOIDP,  # ApcRoutine : PIO_APC_ROUTINE optional
    Fiddle::TYPE_VOIDP,  # ApcContext : void* optional
    Fiddle::TYPE_VOIDP,  # SourceAddress : SOCKADDR_IN6*
    Fiddle::TYPE_VOIDP,  # DestinationAddress : SOCKADDR_IN6*
    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 Icmp6SendEcho2(
        IcmpHandle: *mut core::ffi::c_void,  // HANDLE
        Event: *mut core::ffi::c_void,  // HANDLE optional
        ApcRoutine: *const core::ffi::c_void,  // PIO_APC_ROUTINE optional
        ApcContext: *mut (),  // void* optional
        SourceAddress: *mut SOCKADDR_IN6,  // SOCKADDR_IN6*
        DestinationAddress: *mut SOCKADDR_IN6,  // SOCKADDR_IN6*
        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 Icmp6SendEcho2(IntPtr IcmpHandle, IntPtr Event, IntPtr ApcRoutine, IntPtr ApcContext, IntPtr SourceAddress, IntPtr DestinationAddress, IntPtr RequestData, ushort RequestSize, IntPtr RequestOptions, IntPtr ReplyBuffer, uint ReplySize, uint Timeout);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_Icmp6SendEcho2' -Namespace Win32 -PassThru
# $api::Icmp6SendEcho2(IcmpHandle, Event, ApcRoutine, ApcContext, SourceAddress, DestinationAddress, RequestData, RequestSize, RequestOptions, ReplyBuffer, ReplySize, Timeout)

#uselib "IPHLPAPI.dll"
#func global Icmp6SendEcho2 "Icmp6SendEcho2" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; Icmp6SendEcho2 IcmpHandle, Event, ApcRoutine, ApcContext, varptr(SourceAddress), varptr(DestinationAddress), RequestData, RequestSize, varptr(RequestOptions), ReplyBuffer, ReplySize, Timeout   ; 戻り値は stat
; IcmpHandle : HANDLE -> "sptr"
; Event : HANDLE optional -> "sptr"
; ApcRoutine : PIO_APC_ROUTINE optional -> "sptr"
; ApcContext : void* optional -> "sptr"
; SourceAddress : SOCKADDR_IN6* -> "sptr"
; DestinationAddress : SOCKADDR_IN6* -> "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 Icmp6SendEcho2 "Icmp6SendEcho2" sptr, sptr, sptr, sptr, var, var, sptr, int, var, sptr, int, int
; res = Icmp6SendEcho2(IcmpHandle, Event, ApcRoutine, ApcContext, SourceAddress, DestinationAddress, RequestData, RequestSize, RequestOptions, ReplyBuffer, ReplySize, Timeout)
; IcmpHandle : HANDLE -> "sptr"
; Event : HANDLE optional -> "sptr"
; ApcRoutine : PIO_APC_ROUTINE optional -> "sptr"
; ApcContext : void* optional -> "sptr"
; SourceAddress : SOCKADDR_IN6* -> "var"
; DestinationAddress : SOCKADDR_IN6* -> "var"
; 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 Icmp6SendEcho2 "Icmp6SendEcho2" sptr, sptr, sptr, sptr, sptr, sptr, sptr, int, sptr, sptr, int, int
; res = Icmp6SendEcho2(IcmpHandle, Event, ApcRoutine, ApcContext, varptr(SourceAddress), varptr(DestinationAddress), RequestData, RequestSize, varptr(RequestOptions), ReplyBuffer, ReplySize, Timeout)
; IcmpHandle : HANDLE -> "sptr"
; Event : HANDLE optional -> "sptr"
; ApcRoutine : PIO_APC_ROUTINE optional -> "sptr"
; ApcContext : void* optional -> "sptr"
; SourceAddress : SOCKADDR_IN6* -> "sptr"
; DestinationAddress : SOCKADDR_IN6* -> "sptr"
; 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(変数))。