IcmpSendEcho2Ex 関数 (icmpapi.h)
IcmpSendEcho2Ex 関数は、IPv4 ICMP エコー要求を送信し、すぐに (Event または ApcRoutine が NULL 以外の場合) を返すか、指定したタイムアウト後に を返します。ReplyBuffer には、ICMP 応答 (存在する場合) が含まれます。
構文
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] IPAddr SourceAddress,
[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, optional] Event
ICMP 応答が到着するたびに通知されるイベント。 このパラメーターを指定する場合は、有効なイベント オブジェクトへのハンドルが必要です。 CreateEvent または CreateEventEx 関数を使用して、このイベント オブジェクトを作成します。
イベントの使用方法の詳細については、「 イベント オブジェクト」を参照してください。
[in, optional] ApcRoutine
呼び出し元スレッドがアラート可能なスレッドにあり、ICMP 応答が到着したときに呼び出されるルーチン。 このパラメーターのデータ型を FARPROC ではなく強制的にPIO_APC_ROUTINEするには、PIO_APC_ROUTINE_DEFINEDを定義する必要があります。
[in, optional] ApcContext
ICMP 応答が到着したとき、またはエラーが発生するたびに 、ApcRoutine パラメーターで指定されたコールバック ルーチンに渡される省略可能なパラメーター。
[in] SourceAddress
エコー要求を発行する IPv4 ソース アドレス。 このアドレスは IPAddr 構造体の形式です。
[in] DestinationAddress
エコー要求の IPv4 宛先アドレス。 このアドレスは IPAddr 構造体の形式です。
[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 バイトのデータを保持するのに十分な大きさである必要があります。
また、このバッファーは、さらに 8 バイトのデータ (ICMP エラー メッセージのサイズ) と 、IO_STATUS_BLOCK 構造体の領域を保持するのに十分な大きさにする必要があります。
[in] ReplySize
応答バッファーの割り当てられたサイズ (バイト単位)。 バッファーは、少なくとも 1 つの ICMP_ECHO_REPLY 構造体と RequestSize バイトのデータを保持するのに十分な大きさにする必要があります。
また、このバッファーは、さらに 8 バイトのデータ (ICMP エラー メッセージのサイズ) と 、IO_STATUS_BLOCK 構造体の領域を保持するのに十分な大きさにする必要があります。
[in] Timeout
応答を待機する時間 (ミリ秒単位)。
戻り値
同期的に呼び出されると、 IcmpSendEcho2Ex 関数は 、ReplyBuffer で受信および格納された応答の数を返します。 戻り値が 0 の場合は、 GetLastError を呼び出して拡張エラー情報を取得します。
非同期で呼び出されると、 IcmpSendEcho2Ex 関数は、操作が進行中であることを示すERROR_IO_PENDINGを返します。 結果は、後で Event パラメーターで指定されたイベントがシグナルを受け取るか 、ApcRoutine パラメーターのコールバック関数が呼び出されたときに取得できます。
戻り値が 0 の場合は、 GetLastError を呼び出して拡張エラー情報を取得します。
関数が失敗した場合、 GetLastError によって返される拡張エラー コードには、次のいずれかの値を指定できます。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが関数に渡されました。 このエラーは、 IcmpHandle パラメーターに無効なハンドルが含まれている場合に返されます。 このエラーは、 ReplySize パラメーターが ICMP_ECHO_REPLY 構造体のサイズより小さい値を指定している場合にも返されます。 |
|
操作が進行中です。 この値は、 IcmpSendEcho2Ex への非同期呼び出しが成功すると返され、エラーを示すものではありません。 |
|
メモリ不足のため、操作を完了できません。 |
|
要求はサポートされていません。 このエラーは、ローカル コンピューターに IPv4 スタックがない場合に返されます。 |
|
ReplySize パラメーターで指定された ReplyBuffer のサイズが小さすぎます。 |
|
FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。 |
解説
IcmpSendEcho2Ex 関数は、Windows Server 2008 以降で使用できます。
IcmpSendEcho2Ex 関数は、ユーザーが ICMP 要求を発行する IPv4 ソース アドレスを指定できるようにする IcmpSendEcho2 関数の拡張バージョンです。 IcmpSendEcho2Ex 関数は、コンピューターに複数のネットワーク インターフェイスがある場合に便利です。
ApcRoutine または Event パラメーターが NULL の場合、IcmpSendEcho2Ex 関数は同期的に呼び出されます。 同期的に呼び出されると、戻り値には、Timeout パラメーターで指定された時間を待機した後に、ReplyBuffer で受信および格納された応答の数が含まれます。 戻り値が 0 の場合は、 GetLastError を呼び出して拡張エラー情報を取得します。
ApcRoutine パラメーターまたは Event パラメーターが指定されている場合、IcmpSendEcho2Ex 関数は非同期的に呼び出されます。 非同期で呼び出される場合は、応答を受け入れるために ReplyBuffer パラメーターと ReplySize パラメーターが必要です。 ICMP 応答データは、指定された ReplyBuffer にコピーされ、アプリケーションが通知されるか ( Event パラメーターが指定されている場合)、コールバック関数が呼び出されます ( ApcRoutine パラメーターが指定されている場合)。 アプリケーションでは、IcmpParseReplies 関数を使用して、ReplyBuffer パラメーターが指すデータを解析する必要があります。
Event パラメーターが指定されている場合、IcmpSendEcho2Ex 関数は非同期的に呼び出されます。 Event パラメーターで指定された イベント は、ICMP 応答が到着するたびに通知されます。 CreateEvent 関数を使用して、このイベント オブジェクトを作成します。
ApcRoutine パラメーターが指定されている場合、IcmpSendEcho2Ex 関数は非同期的に呼び出されます。 ApcRoutine パラメーターは、ユーザー定義のコールバック関数を指している必要があります。 ApcRoutine パラメーターで指定されたコールバック関数は、ICMP 応答が到着するたびに呼び出されます。 ApcRoutine パラメーターで指定されたコールバック関数の呼び出しがシリアル化されます。
Event パラメーターと ApcRoutine パラメーターの両方を指定すると、ICMP 応答が到着するたびに Event パラメーターで指定されたイベントが通知されますが、ApcRoutine パラメーターで指定されたコールバック関数は無視されます。
ApcRoutine パラメーターを使用して IcmpSendEcho2Ex 関数を非同期的に呼び出すアプリケーションでは、ApcRoutine パラメーターのデータ型を FARPROC ではなくPIO_APC_ROUTINEするPIO_APC_ROUTINE_DEFINEDを定義する必要があります。
ApcRoutine によって指されるコールバック関数は、次の構文を使用して VOID 型の関数として定義する必要があります。
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
コールバック関数に渡されるパラメーターには、次のものがあります。
ApcRoutine パラメーターで指定されたコールバック関数は、IcmpSendEcho2Ex 関数を呼び出すアプリケーションと同じプロセスで実装する必要があります。 コールバック関数が別の DLL 内にある場合は、 IcmpSendEcho2Ex 関数を呼び出す前に DLL を読み込む必要があります。
IPv6 の場合は、 Icmp6CreateFile、 Icmp6SendEcho2、 および Icmp6ParseReplies 関数を使用します。
Iphlpapi.h ヘッダー ファイルの include ディレクティブは、Icmpapi.h ヘッダー ファイルの前に配置する必要があることに注意してください。
要件
| サポートされている最小のクライアント | Windows Vista と SP1 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | icmpapi.h |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |