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
);
parameters
[in] IcmpHandle
ICMPCreateFile 函数返回的打开句柄。
[in, optional] Event
每当 ICMP 响应到达时要发出信号的事件。 如果指定此参数，则需要有效事件对象的句柄。 使用 CreateEvent 或 CreateEventEx 函数创建此事件对象。
有关使用事件的详细信息，请参阅 事件对象。
[in, optional] ApcRoutine
当调用线程位于可警报线程中并且 ICMP 回复到达时调用的例程。 必须定义PIO_APC_ROUTINE_DEFINED，以强制此参数的数据类型PIO_APC_ROUTINE而不是 FARPROC。
[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 结构数组，后跟选项和数据。 缓冲区必须足够大，以容纳至少一个 ICMP_ECHO_REPLY 结构加上 RequestSize 字节的数据。
此缓冲区还应足够大，以 (ICMP 错误消息的大小再容纳 8 个字节的数据，) 外加 IO_STATUS_BLOCK 结构的空间。
[in] ReplySize
回复缓冲区的分配大小（以字节为单位）。 缓冲区应足够大，以容纳至少一个 ICMP_ECHO_REPLY 结构和 RequestSize 字节的数据。
此缓冲区还应足够大，以 (ICMP 错误消息的大小再容纳 8 个字节的数据，) 外加 IO_STATUS_BLOCK 结构的空间。
[in] Timeout
等待答复的时间（以毫秒为单位）。
返回值
以同步方式调用时， IcmpSendEcho2Ex 函数返回 在 ReplyBuffer 中接收和存储的答复数。 如果返回值为零，请调用 GetLastError 以获取扩展错误信息。
以异步方式调用时， IcmpSendEcho2Ex 函数返回ERROR_IO_PENDING以指示操作正在进行。 稍后，当调用 Event 参数信号中指定的事件或 ApcRoutine 参数中的回调函数时，可以检索结果。
如果返回值为零，请调用 GetLastError 以获取扩展错误信息。
如果函数失败， GetLastError 返回的扩展错误代码可以是以下值之一。
| 返回代码 | 说明 |
|---|---|
|
向该函数传递了无效参数。 如果 IcmpHandle 参数包含无效句柄，则返回此错误。 如果 ReplySize 参数指定的值小于 ICMP_ECHO_REPLY 结构的大小，也可能会返回此错误。 |
|
操作正在进行中。 此值由对 IcmpSendEcho2Ex 的成功异步调用返回，并不指示出现错误。 |
|
没有足够的可用内存来完成该操作。 |
|
不支持该请求。 如果本地计算机上没有 IPv4 堆栈，则返回此错误。 |
|
在 ReplySize 参数中指定的 ReplyBuffer 的大小太小。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
IcmpSendEcho2Ex 函数在 Windows Server 2008 及更高版本上可用。
IcmpSendEcho2Ex 函数是 IcmpSendEcho2 函数的增强版本，允许用户指定要对其发出 ICMP 请求的 IPv4 源地址。 在计算机具有多个网络接口的情况下， IcmpSendEcho2Ex 函数非常有用。
如果 ApcRoutine 或 Event 参数为 NULL，则同步调用 IcmpSendEcho2Ex 函数。 以同步方式调用时，返回值包含等待 Timeout 参数中指定的时间后在 ReplyBuffer 中接收和存储的答复数。 如果返回值为零，请调用 GetLastError 以获取扩展错误信息。
指定 ApcRoutine 或 Event 参数时，将异步调用 IcmpSendEcho2Ex 函数。 异步调用时， 需要 ReplyBuffer 和 ReplySize 参数才能接受响应。 将 ICMP 响应数据复制到提供的 ReplyBuffer 中，当) 指定 Event 参数或) 指定 ApcRoutine 参数时， (调用回调函数时，应用程序 (发出信号。 应用程序必须使用 IcmpParseReplies 函数分析 ReplyBuffer 参数指向的数据。
如果指定 了 Event 参数，则异步调用 IcmpSendEcho2Ex 函数。 每当 ICMP 响应到达时， Event 参数中指定的事件都发出信号。 使用 CreateEvent 函数创建此事件对象。
如果指定 了 ApcRoutine 参数，则异步调用 IcmpSendEcho2Ex 函数。 ApcRoutine 参数应指向用户定义的回调函数。 每当 ICMP 响应到达时， 将调用 ApcRoutine 参数中指定的回调函数。 对 ApcRoutine 参数中指定的回调函数的调用进行序列化。
如果同时指定 了 Event 和 ApcRoutine 参数，则每当 ICMP 响应到达时， Event 参数中指定的事件将发出信号，但 ApcRoutine 参数中指定的回调函数将被忽略。
任何使用 ApcRoutine 参数异步调用 IcmpSendEcho2Ex 函数的应用程序都必须定义PIO_APC_ROUTINE_DEFINED，以强制 ApcRoutine 参数的数据类型PIO_APC_ROUTINE而不是 FARPROC。
必须使用以下语法将 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 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈