SetPerTcpConnectionEStats 函数 (iphlpapi.h)

项目
08/24/2023

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

语法

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
  PMIB_TCPROW     Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

参数

Row

指向 IPv4 TCP 连接的 MIB_TCPROW 结构的指针。

EstatsType

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

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

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_USER_BUFFER	提供给请求操作的用户缓冲区无效。如果 Row 参数为 NULL 指针且 RwSize 参数为非零值，则返回此错误。
ERROR_INVALID_PARAMETER	参数不正确。如果 Row 参数为 NULL 指针，则返回此错误。
ERROR_NOT_FOUND	找不到此请求的条目。如果找不到 Row 参数中指定的 TCP 连接，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。如果未将 RwVersion 或 Offset 参数设置为 0，则返回此错误。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

SetPerTcpConnectionEStats 函数在 Windows Vista 及更高版本上定义。

SetPerTcpConnectionEStats 函数用于在 Row 参数中传递的 IPv4 TCP 连接上启用或禁用扩展统计信息。默认情况下，TCP 连接的扩展统计信息处于禁用状态。 SetPerTcpConnectionEStats 函数用于在 IPv4 TCP 连接的扩展统计信息的读/写信息中设置成员的值。要设置的结构的类型和格式由 EstatsType 参数指定。 Rw 参数包含指向所传递结构的指针。必须指定 Rw 参数指向的结构中的所有成员。

目前支持的唯一 TCP 连接统计信息版本是版本零。因此，传递给 SetPerTcpConnectionEStats 的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 参数当前未使用，必须设置为 0。 Rw 参数指向的可能结构都具有单个成员（TCP_ESTATS_BANDWIDTH_RW_v0 结构除外）。当 EstatsType 参数设置为 TcpConnectionEstatsBandwidth 时，Rw 参数指向的TCP_ESTATS_BANDWIDTH_RW_v0结构必须在对 SetPerTcpConnectionEStats 函数的单个调用中将两个结构成员都设置为首选值。

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

GetTcpTable 函数用于检索本地计算机上的 IPv4 TCP 连接表。此函数返回包含 MIB_TCPROW 项数组的 MIB_TCPTABLE 结构。传递给 SetPerTcpConnectionEStats 函数的 Row 参数必须是现有 IPv4 TCP 连接的条目。

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

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

有关 IPv6 连接的扩展 TCP 统计信息的信息，请参阅 GetPerTcp6ConnectionEStats 和 SetPerTcp6ConnectionEStats 函数。

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

在 Windows 10 版本 1709 (Fall Creators Update) 之前的 Windows 版本中，可以使用 SetPerTcpConnectionEStats 禁用和重新启用连接上的统计信息，从而导致任何统计信息计数器重置为零。从 Windows 10 版本 1709 (Fall Creators Update) 起，某些统计信息计数器在禁用和重新启用时不会重置。此外，如果两个应用程序正在监视同一连接的统计信息，则一个应用程序可能会通过禁用统计信息来混淆另一个应用程序。出于这些原因，我们建议应用程序不要禁用有关连接的统计信息。若要检测一段时间内的更改，应保存上一次调用 GetPerTcpConnectionEStats 读取的计数器值，并从后续调用读取的计数器值中减去这些值。

要求

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