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