icmp6SendEcho2 函数 (icmpapi.h)

项目
10/12/2023

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 及更高版本上，必须定义 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 参数中指定的数据字节数。此缓冲区还应足够大，以 (ICMP 错误消息的大小再容纳 8 个字节的数据，) 外加 IO_STATUS_BLOCK 结构的空间。

[in] ReplySize

ReplyBuffer 参数指向的回复缓冲区的大小（以字节为单位）。此缓冲区应足够大，以容纳至少一个 ICMPV6_ECHO_REPLY 结构加上 RequestSize 字节的数据。此缓冲区还应足够大，以 (ICMP 错误消息的大小再容纳 8 个字节的数据，) 外加 IO_STATUS_BLOCK 结构的空间。

[in] Timeout

等待答复的时间（以毫秒为单位）。仅当同步调用 Icmp6SendEcho2 函数时，才使用此参数。因此，如果 ApcRoutine 或 Event 参数不为 NULL，则不使用此参数。

返回值

同步调用时，返回在 ReplyBuffer 中接收和存储的答复数。

异步调用时，通过返回 ERROR_IO_PENDING指示操作正在进行中。稍后，当 Event 参数中指定的 事件发出信号时，或者调用 ApcRoutine 参数中的回调函数时，可以检索回复数结果。

如果 (同步或异步) 答复数值为零，则对于扩展错误信息，请调用 GetLastError。

如果函数失败，则 GetLastError 返回的扩展错误代码可以是以下值之一。

返回代码	说明
ERROR_CALL_NOT_IMPLEMENTED	此系统不支持该功能。
ERROR_INSUFFICIENT_BUFFER	传递给系统调用的数据区域太小。如果 ReplySize 参数指示 ReplyBuffer 参数指向的缓冲区太小，则返回此错误。
ERROR_INVALID_PARAMETER	其中一个参数无效。如果 IcmpHandle 参数包含无效句柄，则返回此错误。
ERROR_IO_PENDING	操作正在进行中。此值由对 Icmp6SendEcho2 的成功异步调用返回，并不指示出现错误。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法处理此命令。
ERROR_NOT_SUPPORTED	不支持该请求。如果本地计算机上没有 IPv6 堆栈，则返回此错误。
IP_BUF_TOO_SMALL	在 ReplySize 参数中指定的 ReplyBuffer 的大小太小。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

如果 ApcRoutine 或 Event 参数为 NULL，则将同步调用 Icmp6SendEcho2 函数。以同步方式调用时，返回值包含等待 Timeout 参数中指定的时间后在 ReplyBuffer 中接收和存储的答复数。如果返回值为零，请调用 GetLastError 以获取扩展错误信息。

指定 ApcRoutine 或 Event 参数时，将异步调用 Icmp6SendEcho2 函数。异步调用时， 需要 ReplyBuffer 和 ReplySize 参数才能接受响应。将 ICMP 响应数据复制到提供的 ReplyBuffer 中，当) 指定 Event 参数或) 指定 ApcRoutine 参数时， (调用回调函数时，应用程序 (发出信号。应用程序必须使用 Icmp6ParseReplies 函数分析 ReplyBuffer 参数指向的数据。

如果指定 了 Event 参数，则异步调用 Icmp6SendEcho2 函数。每当 ICMPv6 响应到达时， Event 参数中指定的事件将发出信号。使用 CreateEvent 函数创建此事件对象。

如果指定 了 ApcRoutine 参数，则以异步方式调用 Icmp6SendEcho2 函数。 ApcRoutine 参数应指向用户定义的回调函数。每当 ICMPv6 响应到达时， 将调用 ApcRoutine 参数中指定的回调函数。对 ApcRoutine 参数中指定的回调函数的调用进行序列化。

如果同时指定 了 Event 和 ApcRoutine 参数，则每当 ICMPv6 响应到达时， Event 参数中指定的事件将发出信号，但 ApcRoutine 参数中指定的回调函数将被忽略。

在 Windows Vista 及更高版本上，任何使用 ApcRoutine 参数异步调用 Icmp6SendEcho2 函数的应用程序都必须定义PIO_APC_ROUTINE_DEFINED，以强制 ApcRoutine 参数的数据类型PIO_APC_ROUTINE而不是 FARPROC。

请注意，必须先定义 PIO_APC_ROUTINE_DEFINED ，然后才能包含 Icmpapi.h 头文件。

在 Windows Vista 及更高版本中， 必须将 ApcRoutine 指向的回调函数定义为使用以下语法的 VOID 类型的函数：

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

在 Windows Vista 及更高版本上，传递给回调函数的参数包括：

参数	说明
IN PVOID ApcContext	传递给 Icmp6SendEcho2 函数的 ApcContext 参数。应用程序可以使用此参数来标识回调函数正在响应的 Icmp6SendEcho2 请求。
IN PIO_STATUS_BLOCK IoStatusBlock	指向 IO_STATUS_BLOCK的指针。此变量包含最终完成状态和有关操作的信息。在回复中实际收到的字节数在IO_STATUS_BLOCK结构的 Information 成员中返回。 IO_STATUS_BLOCK结构在 Wdm.h 头文件中定义。
在 ULONG 保留	此参数为保留参数。

在 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 上，传递给回调函数的参数包括：

参数	说明
IN PVOID ApcContext	传递给 Icmp6SendEcho2 函数的 ApcContext 参数。应用程序可以使用此参数来标识回调函数正在响应的 Icmp6SendEcho2 请求。

必须在与调用 Icmp6SendEcho2 函数的应用程序相同的进程中实现 ApcRoutine 参数中指定的回调函数。如果回调函数位于单独的 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