SetPerTcp6ConnectionEStats 函数 (iphlpapi.h)

项目
08/24/2023

SetPerTcp6ConnectionEStats 函数在 IPv6 TCP 连接的读/写信息中设置值。此函数用于启用或禁用 IPv6 TCP 连接的扩展统计信息。

语法

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcp6ConnectionEStats(
  PMIB_TCP6ROW    Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

参数

Row

指向 IPv6 TCP 连接的 MIB_TCP6ROW 结构的指针。

EstatsType

要设置的 TCP 扩展统计信息的类型。此参数确定 Rw 参数中预期的数据和信息格式。

此参数可以是 Tcpestats.h 头文件中定义的 TCP_ESTATS_TYPE 枚举类型的值之一。

值	含义
TcpConnectionEstatsData	此值指定 TCP 连接的扩展数据传输信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_DATA_RW_v0 结构。
TcpConnectionEstatsSndCong	此值指定 TCP 连接的发送方拥塞。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_SND_CONG_RW_v0 结构。
TcpConnectionEstatsPath	此值指定 TCP 连接的扩展路径度量信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_PATH_RW_v0 结构。
TcpConnectionEstatsSendBuff	此值指定 TCP 连接的扩展输出队列信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_SEND_BUFF_RW_v0 结构。
TcpConnectionEstatsRec	此值指定 TCP 连接的扩展本地接收器信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_REC_RW_v0 结构。
TcpConnectionEstatsObsRec	此值指定 TCP 连接的扩展远程接收器信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_OBS_REC_RW_v0 结构。
TcpConnectionEstatsBandwidth	此值指定带宽上的 TCP 连接的带宽估计统计信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_BANDWIDTH_RW_v0 结构。
TcpConnectionEstatsFineRtt	此值指定 TCP 连接的精细往返时间 (RTT) 估计统计信息。指定此值时， Rw 参数指向的缓冲区应指向 TCP_ESTATS_FINE_RTT_RW_v0 结构。

Rw

指向缓冲区的指针，该缓冲区包含要设置的读/写信息。缓冲区应包含每个结构成员的 TCP_BOOLEAN_OPTIONAL 枚举中的值，该值指定每个成员应如何更新。

RwVersion

要设置的读/写信息的版本。对于 Windows Vista、Windows Server 2008 和 Windows 7，此参数应设置为零。

RwSize

Rw 参数指向的缓冲区的大小（以字节为单位）。

Offset

要设置的 Rw 参数指向结构中成员的偏移量（以字节为单位）。此参数当前未使用，必须设置为零。

返回值

如果函数成功，则返回值NO_ERROR。

如果函数失败，则返回值为以下错误代码之一。

返回代码	说明
ERROR_ACCESS_DENIED	访问被拒绝。此错误在以下几种情况下返回：用户在本地计算机上缺少所需的管理权限，或者应用程序没有作为内置管理员 (RunAs 管理员) 在增强的 shell 中运行。
ERROR_INVALID_PARAMETER	参数不正确。如果 Row 参数为 NULL 指针，则返回此错误。
ERROR_INVALID_USER_BUFFER	提供给请求操作的用户缓冲区无效。如果 Row 参数为 NULL 指针且 RwSize 参数为非零值，则返回此错误。
ERROR_NOT_FOUND	找不到此请求的条目。如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。如果未将 RwVersion 或 Offset 参数设置为 0，则返回此错误。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

SetPerTcp6ConnectionEStats 函数是在 Windows Vista 及更高版本上定义的。

SetPerTcp6ConnectionEStats 函数用于为 Row 参数中传递的 IPv6 TCP 连接启用或禁用扩展统计信息。默认情况下，TCP 连接的扩展统计信息处于禁用状态。

SetPerTcp6ConnectionEStats 函数用于在 IPv6 TCP 连接的扩展统计信息的读/写信息中设置成员的值。要设置的结构的类型和格式由 EstatsType 参数指定。 Rw 参数包含指向所传递结构的指针。要在此结构中设置的成员由 Offset 参数指定。必须指定 Rw 参数指向的结构中的所有成员。

目前支持的唯一 TCP 连接统计信息版本是版本零。因此，传递给 SetPerTcp6ConnectionEStats 的RwVersion 参数应设置为 0。

传递此函数的 Rw 参数指向的结构取决于 在 EstatsType 参数中传递的枚举值。下表指示应为每个可能的 EstatsType 参数类型在 Rw 参数中传递的结构类型。

EstatsType	Rw 指向的结构
TcpConnectionEstatsData	TCP_ESTATS_DATA_RW_v0
TcpConnectionEstatsSndCong	TCP_ESTATS_SND_CONG_RW_v0
TcpConnectionEstatsPath	TCP_ESTATS_PATH_RW_v0
TcpConnectionEstatsSendBuff	TCP_ESTATS_SEND_BUFF_RW_v0
TcpConnectionEstatsRec	TCP_ESTATS_REC_RW_v0
TcpConnectionEstatsObsRec	TCP_ESTATS_OBS_REC_RW_v0
TcpConnectionEstatsBandwidth	TCP_ESTATS_BANDWIDTH_RW_v0
TcpConnectionEstatsFineRtt	TCP_ESTATS_FINE_RTT_RW_v0

Offset 参数当前未使用。 Rw 参数指向的可能结构都具有单个成员，TCP_ESTATS_BANDWIDTH_RW_v0 结构除外。当 EstatsType 参数设置为 TcpConnectionEstatsBandwidth 时，Rw 参数指向的 TCP_ESTATS_BANDWIDTH_RW_v0 结构必须在对 SetPerTcp6ConnectionEStats 函数的单个调用中同时将两个结构成员都设置为首选值。

如果 RwSize 参数设置为 0， 则 SetPerTcp6ConnectionEStats 函数将返回NO_ERROR且不会更改扩展统计信息状态。

GetTcp6Table 函数用于检索本地计算机上的 IPv6 TCP 连接表。此函数返回包含 MIB_TCP6ROW 项数组的 MIB_TCP6TABLE 结构。传递给 SetPerTcp6ConnectionEStats 函数的 Row 参数必须是现有 IPv6 TCP 连接的条目。

在 IPv6 的 TCP 连接上启用扩展统计信息后，应用程序将调用 GetPerTcp6ConnectionEStats 函数来检索 TCP 连接上的扩展统计信息。

GetPerTcp6ConnectionEStats 函数旨在使用 TCP 诊断网络和应用程序中的性能问题。如果基于网络的应用程序性能不佳，TCP 可以确定瓶颈是在发送方、接收方还是网络本身。如果瓶颈在网络中，TCP 可以提供有关其性质的特定信息。

有关 IPv4 连接上的扩展 TCP 统计信息的信息，请参阅 GetPerTcpConnectionEStats 和 SetPerTcpConnectionEStats 函数。

SetPerTcp6ConnectionEStats 函数只能由以 Administrators 组成员身份登录的用户调用。如果 SetPerTcp6ConnectionEStats 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。此函数也可能因为 Windows Vista 和 Windows Server 2008 上的用户帐户控制 (UAC) 而失败。如果包含此函数的应用程序由以管理员组成员身份登录（而不是内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。如果 Windows Vista 或 Windows Server 2008 上的应用程序缺少此清单文件，则作为管理员组成员（而不是内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 才能使此功能成功。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	iphlpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll