Icmp6SendEcho2 函数发送 IPv6 ICMPv6 回显请求，并立即返回（如果事件或 ApcRoutine 为非 NULL），或在指定的超时后返回。ReplyBuffer 包含 IPv6 ICMPv6 回显响应（如果有）。
Syntax
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 及更高版本中，必须定义 PIO_APC_ROUTINE_DEFINED 以强制此参数的数据类型 PIO_APC_ROUTINE 而不是 FARPROC。
在 Windows Server 2003 和 Windows XP 上，不得定义 PIO_APC_ROUTINE_DEFINED 才能将此参数的数据类型强制为 FARPROC。
[in, optional] ApcContext
每当 ICMPv6 响应到达或发生错误时，传递给 ApcRoutine 参数中指定的回调例程的可选参数。
[in] SourceAddress
要对其发出回显请求的 IPv6 源地址，采用 sockaddr 结构的形式。
[in] DestinationAddress
回显请求的 IPv6 目标地址，采用 sockaddr 结构的形式。
[in] RequestData
指向包含在请求中发送数据的缓冲区的指针。
[in] RequestSize
RequestData 参数指向的请求数据缓冲区的大小（以字节为单位）。
[in, optional] RequestOptions
指向请求的 IPv6 标头选项的指针，格式为 IP_OPTION_INFORMATION 结构。 在 64 位平台上，此参数采用 IP_OPTION_INFORMATION32 结构的形式。
如果不需要指定任何 IP 标头选项，此参数可能为 NULL。
注意 在 Windows Server 2003 和 Windows XP 上， RequestOptions 参数不是可选的，不能为 NULL，并且只使用 Ttl 和 Flags 成员。
[out] ReplyBuffer
指向缓冲区的指针，用于保存对请求的答复。 返回后，缓冲区包含 一个ICMPV6_ECHO_REPLY 结构，后跟 ICMPv6 回显响应回复数据中的消息正文。 缓冲区必须足够大，才能容纳至少一 个ICMPV6_ECHO_REPLY 结构，加上 RequestSize 参数中指定的数据字节数。 此缓冲区还应该足够大，足以容纳 8 个以上的数据字节（ICMP 错误消息的大小）以及 IO_STATUS_BLOCK 结构的空间。
[in] ReplySize
ReplyBuffer 参数指向的回复缓冲区的大小（以字节为单位）。 此缓冲区应足够大，可以容纳至少一 个ICMPV6_ECHO_REPLY 结构加上 RequestSize 字节的数据。 此缓冲区还应该足够大，足以容纳 8 个以上的数据字节（ICMP 错误消息的大小）以及 IO_STATUS_BLOCK 结构的空间。
[in] Timeout
等待答复的时间（以毫秒为单位）。 仅当 以同步方式调用 Icmp6SendEcho2 函数时，才使用此参数。 因此，如果 ApcRoutine 或 Event 参数不是 NULL，则不使用此参数。
返回值
同步调用时，返回在 ReplyBuffer 中接收和存储的答复数。
异步调用时，通过返回 ERROR_IO_PENDING指示作正在进行中。 可以在以后检索答复数结果、 事件参数信号 中指定的事件或调用 ApcRoutine 参数中的回调函数时。
如果（同步或异步）答复数值为零，则对于扩展错误信息调用 GetLastError。
如果函数失败， 则 GetLastError 返回的扩展错误代码可以是以下值之一。
| 返回代码 | Description |
|---|---|
|
此系统上不支持此函数。 |
|
传递给系统调用的数据区域太小。 如果 ReplySize 参数指示 ReplyBuffer 参数指向的缓冲区太小，则返回此错误。 |
|
其中一个参数无效。 如果 IcmpHandle 参数包含无效句柄，则返回此错误。 |
|
作正在进行中。 此值由对 Icmp6SendEcho2 的成功异步调用返回，而不是错误指示。 |
|
没有足够的内存可用于处理此命令。 |
|
不支持该请求。 如果本地计算机上没有 IPv6 堆栈，则返回此错误。 |
|
ReplySize 参数中指定的 ReplyBuffer 的大小太小。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
如果 ApcRoutine 和 Event 参数为 NULL，则以同步方式调用 Icmp6SendEcho2 函数。 以同步方式调用时，返回值包含在等待 Timeout 参数中指定的时间后收到的回复数并将其存储在 ReplyBuffer 中。 如果返回值为零，请调用 GetLastError 以获取扩展错误信息。
指定 ApcRoutine 或事件参数时，以异步方式调用 Icmp6SendEcho2 函数。 异步调用时，需要 ReplyBuffer 和 ReplySize 参数才能接受响应。 ICMP 响应数据将复制到提供的 ReplyBuffer ，并发出应用程序信号（指定 事件 参数时）或调用回调函数（指定 ApcRoutine 参数时）。 应用程序必须使用 Icmp6ParseReplies 函数分析 ReplyBuffer 参数指向的数据。
如果指定 了 Event 参数，则以异步方式调用 Icmp6SendEcho2 函数。 每当 ICMPv6 响应到达时， 事件 参数中指定的事件都发出信号。 使用 CreateEvent 函数创建此事件对象。
如果指定 了 ApcRoutine 参数，则以异步方式调用 Icmp6SendEcho2 函数。 ApcRoutine 参数应指向用户定义的回调函数。 每当 ICMPv6 响应到达时， 将调用 ApcRoutine 参数中指定的回调函数。 序列化 ApcRoutine 参数中指定的回调函数的调用。
如果同时指定 了 Event 和 ApcRoutine 参数，则每当 ICMPv6 响应到达时， 事件 参数中指定的事件都发出信号，但 忽略 ApcRoutine 参数中指定的回调函数。
在 Windows Vista 及更高版本中，使用 ApcRoutine 参数异步调用 Icmp6SendEcho2 函数的任何应用程序都必须定义PIO_APC_ROUTINE_DEFINED，以强制 ApcRoutine 参数的数据类型PIO_APC_ROUTINE而不是 FARPROC。
请注意， 在包含 Icmpapi.h 头文件之前，必须定义PIO_APC_ROUTINE_DEFINED。
在 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_DEFINED以强制 ApcRoutine 参数的数据类型转换为 FARPROC，而不是PIO_APC_ROUTINE。
在 Windows Server 2003 和 Windows XP 上， ApcRoutine 指向的回调函数必须定义为具有以下语法的 VOID 类型的函数：
typedef
VOID WINAPI
(*FARPROC) (
IN PVOID ApcContext,
);
在 Windows Server 2003 和 Windows XP 上，传递给回调函数的参数包括：
| 参数 | Description |
|---|---|
| IN PVOID ApcContext | 传递给 Icmp6SendEcho2 函数的 ApcContext 参数。 应用程序可以使用此参数来标识回调函数正在响应的 Icmp6SendEcho2 请求。 |
ApcRoutine 参数中指定的回调函数必须与调用 Icmp6SendEcho2 函数的应用程序在同一进程中实现。 如果回调函数位于单独的 DLL 中，则应在调用 Icmp6SendEcho2 函数之前加载 DLL。
对于 IPv4，请使用 IcmpCreateFile、 IcmpSendEcho、 IcmpSendEcho2、 IcmpSendEcho2Ex 和 IcmpParseReplies 函数。
请注意， Iphlpapi.h 头文件的 include 指令必须放在 Icmpapi.h 头文件之前。
要求
| Requirement | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [桌面应用 |UWP 应用] |
| 支持的最低服务器 | Windows Server 2003 [桌面应用 |UWP 应用] |
| 目标平台 | Windows操作系统 |
| Header | icmpapi.h |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |