IcmpSendEcho2

IcmpSendEcho2 関数は IPv4 ICMP エコー要求を送信し、Event または ApcRoutine が NULL 以外なら即座に、そうでなければ指定したタイムアウト後に返る。ReplyBuffer には ICMP エコー応答が格納される。

IcmpSendEcho2 IcmpHandle, Event, ApcRoutine, ApcContext, DestinationAddress, RequestData, RequestSize, RequestOptions, ReplyBuffer, ReplySize, Timeout

IcmpHandle : [intptr] IcmpCreateFile 関数が返したオープンハンドル。
Event : [intptr] ICMP 応答が到着したときに (最大 1 回) シグナル状態にするイベント。指定する場合は有効なイベントオブジェクトへのハンドルが必要。CreateEvent または CreateEventEx でイベントを作成する。イベントの使用方法については Event objects を参照。
ApcRoutine : [int] 呼び出しスレッドがアラート可能な状態で ICMPv4 応答が到着したときに呼ばれるルーチン。このパラメータの型を FARPROC ではなく PIO_APC_ROUTINE にするため PIO_APC_ROUTINE_DEFINED を定義しなければならない。
ApcContext : [intptr] ICMP 応答が到着したかエラーが発生したとき、ApcRoutine で指定したコールバックルーチンに (最大 1 回) 渡される任意パラメータ。
DestinationAddress : [int] エコー要求の IPv4 宛先。IPAddr 構造体の形式で指定する。
RequestData : [intptr] 要求で送信するデータを含むバッファへのポインタ。
RequestSize : [int] RequestData が指す要求データバッファのサイズ (バイト単位)。
RequestOptions : [var] 要求の IP ヘッダオプションへのポインタ。IP_OPTION_INFORMATION 構造体の形式で指定する。IP ヘッダオプションを指定しない場合は NULL でもよい。
ReplyBuffer : [intptr] 要求に対する応答を保持するバッファへのポインタ。戻り時、バッファには ICMP_ECHO_REPLY 構造体の配列に続けてオプションとデータが格納される。バッファは少なくとも ICMP_ECHO_REPLY 構造体 1 つと RequestSize バイトのデータ、さらに 8 バイトの ICMP エラーメッセージ分を収められる大きさでなければならない。
ReplySize : [int] 応答バッファの割り当てサイズ (バイト単位)。少なくとも ICMP_ECHO_REPLY 構造体 1 つと RequestSize バイトのデータ、さらに 8 バイトの ICMP エラーメッセージ分を収められる必要がある。
Timeout : [int] 応答を待機する時間 (ミリ秒単位)。

(プラグイン / モジュール : iphlpapi.dll)

解説

IcmpSendEcho2 関数は IPv4 ICMP エコー要求を送信し、Event または ApcRoutine が NULL
以外なら即座に、そうでなければ指定したタイムアウト後に返る。ReplyBuffer には ICMP エコー応答が格納される。

[戻り値]
同期呼び出し時、IcmpSendEcho2 は ReplyBuffer に格納された応答の数を返す。0 の場合は GetLastError
で拡張エラー情報を取得する。非同期呼び出し時は 0 を返し、続く GetLastError の呼び出しが操作進行中を示す
ERROR_IO_PENDING を返す。結果は Event のシグナル、または ApcRoutine
の呼び出しで取得できる。関数が失敗した場合、GetLastError は次のいずれかを返す:
- ERROR_INVALID_PARAMETER: 無効なパラメータ (IcmpHandle が無効、または ReplySize が
ICMP_ECHO_REPLY 構造体より小さい)
- ERROR_IO_PENDING: 操作進行中 (非同期呼び出しの成功時)
- ERROR_NOT_ENOUGH_MEMORY: メモリ不足
- ERROR_NOT_SUPPORTED: IPv4 スタックがローカルコンピュータに存在しないときの要求未サポート
- IP_BUF_TOO_SMALL: ReplySize が小さすぎる
- その他: FormatMessage でメッセージ文字列を取得する

[備考]
IcmpSendEcho2 関数は ApcRoutine と Event が NULL
の場合は同期的に呼び出される。同期呼び出し時の戻り値は、Timeout で指定した時間待機した後に ReplyBuffer
に格納された応答の数である。0 の場合は GetLastError で拡張エラー情報を取得する。ApcRoutine または Event
が指定されている場合は非同期呼び出しとなる。非同期時は ReplyBuffer / ReplySize が必要で、応答データが
ReplyBuffer にコピーされ、Event または ApcRoutine に通知される。アプリケーションは
IcmpParseReplies で ReplyBuffer を解析する必要がある。両方指定した場合は Event がシグナル状態になり
ApcRoutine は無視される。ApcRoutine による非同期呼び出しを行うアプリケーションは、型を
PIO_APC_ROUTINE にするため Icmpapi.h をインクルードする前に PIO_APC_ROUTINE_DEFINED
を定義しなければならない。コールバック関数は VOID 型で次の構文に従って定義する:
このドキュメントは省略されている。

情報